vt-c-session-consolidator¶

Consolidate session journal entries into high-level documentation updates upon task completion. Synthesizes decisions and learnings into spec, PRD, and architecture docs. - Read - Write - Edit - Bash - Grep - Glob

Plugin: core-standards
Category: Knowledge Capture
Command: /vt-c-session-consolidator

session-consolidator Skill¶

Purpose: Transform granular session journal entries into high-level documentation updates, ensuring decisions and learnings persist in project specs, PRDs, and architecture documents.

Overview¶

While session-journal captures details DURING work, this skill synthesizes those details INTO lasting documentation AFTER task completion.

Flow:

session-journal (during work)
        ↓
    [task complete]
        ↓
session-consolidator (synthesize → update docs)

What Gets Consolidated¶

From Session Journal → To Project Docs¶

Journal Entry Type	Consolidates To
Decisions (architectural)	Architecture Decision Records (ADRs)
Decisions (feature)	spec.md or PRD updates
Decisions (technical)	Technical documentation
Learnings (constraints)	spec.md constraints section
Learnings (patterns)	Architecture/patterns docs
Activities (completed features)	PRD status updates, changelog

Consolidation Targets¶

1. Specification Updates (spec.md)¶

When to update: - Feature requirements changed during implementation - New constraints discovered - Edge cases identified - Acceptance criteria refined

Update format:

## [Feature Name]

### Requirements
- [Updated requirement based on implementation learnings]

### Constraints (Updated YYYY-MM-DD)
- [New constraint discovered during implementation]
  - Source: [link to journal entry]

### Edge Cases
- [Edge case identified during development]

2. PRD Updates¶

When to update: - Scope changes during implementation - New user stories emerged - Success criteria refined - Timeline/milestone impacts

Update format:

## Implementation Notes (Added YYYY-MM-DD)

### Scope Adjustments
- [What changed and why]

### Discovered Requirements
- [Requirements that emerged during implementation]

### Updated Success Criteria
- [Refined metrics based on implementation]

3. Architecture Decision Records (ADRs)¶

When to create: - Significant architectural decisions made - Technology choices with tradeoffs - Pattern selections with rationale

ADR format:

# ADR-NNN: [Decision Title]

## Status
Accepted

## Context
[From journal decision entries - what problem needed solving]

## Decision
[From journal - what was decided]

## Consequences
[From journal - expected impact]

## Alternatives Considered
[From journal - rejected options and why]

## Related
- Journal entries: [links]
- Affected files: [list]

4. Technical Documentation¶

When to update: - API behavior clarified - Configuration patterns established - Integration details discovered

Consolidation Workflow¶

Step 1: Trigger Detection¶

Auto-trigger on: - "Task complete" / "Feature done" / "Finished implementing" - All todos marked complete for a feature - Merge to main branch - /vt-c-consolidate command

Step 2: Gather Journal Entries¶

# Find recent entries for this task/feature
FEATURE="user-authentication"  # or detected from context
DATE_RANGE="last 7 days"       # or since task started

# Search journal for related entries
grep -r "$FEATURE" docs/vt-c-journal/
grep -r "authentication" docs/vt-c-journal/  # related terms

Collect: - All decision entries related to task - All learning entries from task period - Activity entries showing completed work

Step 3: Classify Consolidation Targets¶

For each journal entry, determine destination:

┌─────────────────────┐
│ Journal Entry       │
└──────────┬──────────┘
           │
     ┌─────┴─────┐
     │ Decision? │
     └─────┬─────┘
           │
    ┌──────┼──────┬──────────┐
    ↓      ↓      ↓          ↓
  ADR   spec.md  PRD    tech-docs
(arch)  (feat)  (scope) (technical)

Classification rules:

If decision involves...	Target
System architecture, service boundaries	ADR
Feature behavior, requirements	spec.md
Scope, timeline, success metrics	PRD
API contracts, configurations	Tech docs

If learning involves...	Target
Hard constraints, limitations	spec.md constraints
Patterns, best practices	Architecture docs
External API behavior	Integration docs

Step 4: Generate Consolidated Content¶

For each target document:

4a. Extract key points: - Remove implementation noise - Keep strategic decisions - Preserve rationale and alternatives - Maintain links to detailed journal entries

4b. Transform to document style: - Journal: detailed, timestamped, verbose - Consolidated: concise, organized, reference-style

Example transformation:

Journal entry:

# Decision: Use PostgreSQL JSONB for user preferences

## Context
Need to store flexible user preferences that vary by feature flag...

## Options Considered
1. Separate preferences table with key-value pairs...
2. JSONB column in users table...
3. External config service...

## Decision
JSONB column because: single query, schema flexibility, good enough performance for our scale...

Consolidated spec.md addition:

### User Preferences Storage

**Approach:** PostgreSQL JSONB column in users table

**Rationale:** Single-query access, schema flexibility for feature-flag-dependent preferences

**Constraints:**
- JSONB indexing required for common query paths
- Max 1MB preference payload

**Details:** See [ADR-012](docs/adr/012-user-preferences-storage.md)

Step 5: Update Target Documents¶

5a. Check if document exists:

# SpecKit project
if [ -d ".specify" ]; then
  # Derive active spec from branch name (feature/spec-NNN-* → SPEC-NNN)
  SPEC_FILE="specs/[N]-feature/spec.md"  # per active spec derived from branch
else
  SPEC_FILE="docs/spec.md"  # or SPECIFICATION.md
fi

5b. Find appropriate section: - Look for existing section matching feature/topic - If not found, create new section - Preserve document structure

5c. Apply update: - Add consolidated content - Include "Updated YYYY-MM-DD" marker - Add source reference to journal entries

Step 6: Create Consolidation Summary¶

After updates, create summary:

# Consolidation Summary - [Feature Name]

**Date:** YYYY-MM-DD
**Task:** [Brief description]

## Documents Updated

### spec.md
- Added: User Preferences Storage section
- Updated: Authentication constraints

### PRD
- Added: Implementation Notes section
- Updated: Success Criteria

### ADRs Created
- ADR-012: User Preferences Storage
- ADR-013: Session Token Strategy

## Journal Entries Consolidated
- 2026-01-26-1430-decision.md → ADR-012
- 2026-01-26-1500-learning.md → spec.md constraints
- 2026-01-26-1545-decision.md → ADR-013

## Key Decisions Captured
1. PostgreSQL JSONB for preferences (vs. key-value table)
2. JWT with Redis session store (vs. stateless JWT)
3. Rate limiting at API gateway (vs. application level)

## Key Learnings Captured
1. Redis cluster mode required for session failover
2. JSONB GIN index needed for preference queries
3. OAuth token refresh window must be > session timeout

Step 7: Archive Processed Entries¶

Mark journal entries as consolidated:

# Add consolidated marker to entry frontmatter
# consolidated: true
# consolidated_to: [spec.md, ADR-012]
# consolidated_date: 2026-01-26

Integration Points¶

With SpecKit¶

If .specify/ directory exists: - Update active spec's specs/[N]-feature/spec.md for requirements - Update .specify/memory/constitution.md for constraints (suggest only) - Trigger /speckit.validate after updates

Step History Preservation¶

When consolidating for a completed SPEC: - Derive active spec from branch — check .active-spec file first, then parse branch name (feature/spec-NNN-* → SPEC-NNN) - If steps: exists in specs/[N]-feature/state.yaml for the SPEC, include in consolidation summary:

## Implementation Steps (from specs/[N]-feature/state.yaml)
| Step | Description | Status |
|------|-------------|--------|
| 1 | Setup | completed |
| 2 | Core Mechanism | completed |
| ... | ... | completed |

Optionally suggest adding completion timestamps if journal entries provide them
The steps: block remains in specs/[N]-feature/state.yaml as historical documentation
If no steps: exist for the SPEC, skip this section silently

With PRD Documents¶

Look for PRD in common locations: - docs/PRD.md - PRD.md - docs/product-requirements.md - .specify/memory/prd.md

With ADR System¶

Check for existing ADR structure: - docs/adr/ - docs/architecture/decisions/ - Create if not exists

Number ADRs sequentially:

LAST_ADR=$(ls docs/adr/*.md 2>/dev/null | sort -V | tail -1)
NEXT_NUM=$((${LAST_ADR##*-} + 1))

Commands¶

`/vt-c-consolidate`¶

Manually trigger consolidation for current task.

/vt-c-consolidate                    # Consolidate recent entries
/vt-c-consolidate "authentication"   # Consolidate specific feature
/vt-c-consolidate --since 2026-01-20 # Consolidate from date

`/vt-c-consolidate-preview`¶

Preview what would be consolidated without making changes.

/vt-c-consolidate-preview

Shows: - Journal entries to process - Target documents - Proposed changes

Configuration¶

In project CLAUDE.md:

## Session Consolidator

consolidation:
  auto_trigger: true          # Trigger on task completion
  targets:
    - spec                    # Update spec.md
    - prd                     # Update PRD
    - adr                     # Create ADRs
    - changelog               # Update CHANGELOG.md
  spec_path: specs/[N]-feature/spec.md # Custom spec location (per active spec)
  prd_path: docs/PRD.md       # Custom PRD location
  adr_path: docs/adr/         # Custom ADR location
  archive_entries: true       # Mark entries as consolidated

Example Scenario¶

Context: Completed user authentication feature over 3 days.

Journal entries created: - Day 1: Decision - JWT vs session cookies - Day 1: Learning - Redis cluster mode requirement - Day 2: Decision - Rate limiting approach - Day 2: Activity - Implemented login flow - Day 3: Decision - Password hashing algorithm - Day 3: Learning - OAuth token refresh behavior

On task completion, /vt-c-consolidate produces:

ADR-015: Authentication Token Strategy
Covers JWT decision with session store
Documents Redis cluster requirement
ADR-016: Rate Limiting Architecture
API gateway approach
Threshold configurations
spec.md updates:
Authentication section with requirements
Security constraints section
Session management constraints
PRD updates:
Implementation notes
Discovered requirements
Updated success criteria
Consolidation summary in docs/vt-c-journal/consolidations/

Quality Checks¶

Before finalizing consolidation:

[ ] All significant decisions captured (not just activities)
[ ] Rationale preserved (not just what, but why)
[ ] Alternatives documented for major decisions
[ ] Constraints include source/evidence
[ ] Cross-references to journal entries included
[ ] Document structure preserved (no formatting breaks)
[ ] No duplicate content (check existing sections)

Sprint Retrospective via Commit Analysis¶

In addition to journal consolidation, this skill supports a /vt-c-consolidate --retro mode that analyzes git commit history to produce a sprint retrospective report.

Retro Workflow¶

/vt-c-consolidate --retro                    # Analyze last 2 weeks
/vt-c-consolidate --retro --since 2026-03-01 # Analyze from date

Step 1: Gather Commit Data¶

git log --since="2 weeks ago" --format="%h|%ai|%s" --no-merges
git log --since="2 weeks ago" --numstat --format="%h"

Step 2: Analyze Patterns¶

Extract and report:

Metric	How to Compute
Commit frequency	Commits per day, peak hours
File change hotspots	Files modified most frequently (potential fragility)
Spec completion rate	SPECs moved to completed in .design-state.yaml
Test coverage trends	Ratio of test files to implementation files in commits
Fix-after-commit rate	Commits containing "fix" that follow a non-fix commit to the same file
Review iteration count	Number of fix cycles per feature (from commit messages)

Step 3: Generate Retro Report¶

# Sprint Retrospective — [Date Range]

## Work Distribution
- [X] commits across [Y] SPECs
- Hotspot files: [top 3 most-modified files]

## What Went Well
- [Patterns suggesting efficiency: low fix-after-commit rate, high spec throughput]

## What Could Improve
- [Patterns suggesting friction: high file churn, many fix commits, concentrated hotspots]

## Metrics
| Metric | Value |
|--------|-------|
| Total commits | N |
| SPECs completed | N |
| Avg commits per SPEC | N |
| Fix-after-commit rate | N% |

Step 4: Surface Failure-to-Rule Opportunities¶

Scan commit messages for patterns suggesting repeated mistakes: - Multiple "fix" commits to the same file → candidate for a CLAUDE.md rule - Reverted commits → what went wrong? - Commits mentioning "forgot" or "missed" → systematic gap

Error Handling¶

No journal entries found:

No session journal entries found for consolidation.
Run /vt-c-journal during work to capture decisions and learnings.

Target document not found:

spec.md not found. Options:
1. Create new spec.md with consolidated content
2. Specify custom path: /vt-c-consolidate --spec-path docs/SPEC.md
3. Skip spec updates: /vt-c-consolidate --skip-spec

Conflicting content:

Existing section "Authentication" found in spec.md.
Options:
1. Append to existing section
2. Create new subsection
3. Review and merge manually

Open Brain Capture (Optional)¶

After consolidating journal entries into durable artifacts, if the capture_thought MCP tool is available, capture the consolidation summary.

When to capture: After every completed consolidation run.

How: 1. Check if capture_thought tool is available. If not: skip silently. 2. If no entries were consolidated: skip capture. 3. Call capture_thought with:

thought: "Session consolidation: {N} journal entries synthesized into {artifacts updated}. Key decisions promoted: {list}. Spec updates: {list}. Project: {name}."

4. On timeout or error: log debug message and continue. Never fail the skill.