Skip to content

/vt-c-consolidate

Consolidate session journal entries into spec, PRD, and ADR updates

Plugin: core-standards
Usage: /vt-c-consolidate [feature-name] [--since DATE] [--preview]

Consolidate Command

Synthesize session journal entries into high-level documentation updates after task completion.

Usage

# Consolidate recent entries (auto-detect feature from context)
/vt-c-consolidate

# Consolidate specific feature
/vt-c-consolidate "user-authentication"

# Consolidate from specific date
/vt-c-consolidate --since 2026-01-20

# Preview without making changes
/vt-c-consolidate --preview

# Skip specific targets
/vt-c-consolidate --skip-adr
/vt-c-consolidate --skip-spec
/vt-c-consolidate --skip-prd

What It Does

  1. Reads session journal entries from docs/vt-c-journal/
  2. Classifies entries by consolidation target (spec, PRD, ADR)
  3. Transforms detailed entries into concise documentation
  4. Updates target documents with consolidated content
  5. Creates ADRs for significant architectural decisions
  6. Archives processed entries (marks as consolidated)

Consolidation Targets

Source Consolidates To
Architectural decisions (journal) ADR (Architecture Decision Record)
Feature decisions (journal) spec.md
Scope/timeline changes (journal) PRD
Technical learnings (journal) Tech docs, spec constraints
Completed activities (journal) Changelog
Completed review todos (todos/) critical-patterns.md, ADRs

Example

After completing user authentication:

Journal entries: - 2026-01-24-1430-decision.md - JWT vs session cookies - 2026-01-24-1600-learning.md - Redis cluster requirement - 2026-01-25-0930-decision.md - Rate limiting approach

Running /vt-c-consolidate "authentication":

Consolidating session journal entries for: authentication

Found 3 entries to process:
  ✓ 2026-01-24-1430-decision.md → ADR-015
  ✓ 2026-01-24-1600-learning.md → spec.md (constraints)
  ✓ 2026-01-25-0930-decision.md → ADR-016

Documents updated:
  ✓ docs/adr/015-authentication-tokens.md (created)
  ✓ docs/adr/016-rate-limiting.md (created)
  ✓ specs/[N]-authentication/spec.md (updated: Authentication section)
  ✓ docs/PRD.md (updated: Implementation Notes)

Summary saved: docs/vt-c-journal/consolidations/2026-01-26-authentication.md

Output

ADR Created

# ADR-015: Authentication Token Strategy

## Status
Accepted

## Context
Need secure, scalable authentication for API...

## Decision
JWT tokens with Redis session store...

## Rationale
- Stateless validation for scale
- Redis for session revocation capability
- Refresh token rotation for security

Spec.md Updated

## Authentication (Updated 2026-01-26)

### Constraints
| Constraint | Reason |
|------------|--------|
| Redis cluster mode required | Session failover needs |
| JWT expiry < 15 minutes | Security requirement |

Flags

Flag Description
--preview Show what would be consolidated without changes
--since DATE Only process entries from this date
--skip-adr Don't create ADRs
--skip-spec Don't update spec.md
--skip-prd Don't update PRD
--skip-changelog Don't update CHANGELOG
--force Consolidate even if entries already processed

Integration

Works with: - session-journal - Source of entries to consolidate - SpecKit - Updates the active spec (see .design-state.yaml for specs_dir) if present - compound-docs - Links to solution documentation

Review Findings Integration

In addition to journal entries, consolidate also processes completed review todos:

  1. Scan todos/ directory for files with status: complete in their YAML frontmatter
  2. Extract learnings from the "Work Log" section of each completed todo
  3. Identify patterns — if multiple completed todos share a tag or finding type:
  4. Check if the pattern is already in docs/solutions/patterns/critical-patterns.md
  5. If not documented: add it as a new pattern
  6. Extract architectural decisions — if a completed todo's resolution involved an architectural choice, create an ADR
  7. Update review history — if docs/review-history.md exists, update the Recurring Findings table with any patterns discovered during consolidation

Example

Consolidating review findings...

Found 5 completed todos in todos/:
  ✓ 001-complete-p1-sql-injection.md → critical-patterns.md (new pattern)
  ✓ 002-complete-p2-n-plus-one.md → critical-patterns.md (existing pattern, frequency updated)
  ✓ 003-complete-p2-missing-auth.md → ADR-017 (authentication middleware decision)
  ✓ 004-complete-p3-unused-imports.md → (no consolidation needed)
  ✓ 005-complete-p2-race-condition.md → critical-patterns.md (new pattern)

Review patterns updated: 2 new, 1 updated
ADRs created: 1

When to Run

  • After completing a feature or significant task
  • At end of sprint/milestone
  • Before creating a PR (to capture decisions)
  • Manually when you realize important decisions were made
  • After resolving review todos (to capture learnings)
  • /vt-c-journal - Capture individual entries during work
  • /vt-c-consolidate-preview - Preview consolidation without changes