Session Recap

Session Recap

Systematically document Claude Code sessions into the knowledge bank.

Knowledge Bank Location: Read from ~/.claude/plugins/config/second-brain/config.json. Configure via skills/common/setup_kb_path.sh --configure.

Philosophy: Knowledge Bank = BRAIN, not ARCHIVE. Preserve workflows, edge cases, decisions—not verbose traces. Target 95% size reduction, 100% actionable knowledge.

Invocation

Recommended Workflow

Important: Session recap should run in a new session after the work session ends. This ensures the full transcript is captured.

1. During your work session: Note down the session path displayed at startup

   • Claude Code shows: Session: /path/to/.claude/projects/.../session-id.jsonl
   • Save this path for later

2. Exit the work session: The final transcript is automatically saved

3. Start a new session: Begin fresh to run the recap

   claude
   

4. Invoke session-recap with the path:

   Recap the session at /path/to/session-id.jsonl
   

   Or:

   /second-brain:session-recap /path/to/session-id.jsonl
   

Why a New Session?

Running session-recap in the same session would miss the final conversation context. The transcript must be fully saved before knowledge extraction can begin.

Manual Invocation

• Slash command: /second-brain:session-recap
• Skill tool: Skill({ skill: "second-brain:session-recap" })

Visibility Settings

Quick Reference

RFC 2119 Keywords

This skill uses RFC 2119 keywords:

• MUST: Absolute requirement, cannot be skipped
• SHOULD: Valid exceptions may exist but require conscious weighing
• MAY: Truly optional

Workflow

Phase 1: ANALYZE

Goal: Load session data and extract facts.

1.1 Load Session Data

If session folder provided:

# Find latest segment
LATEST_SEGMENT=$(ls -d "$SESSION_FOLDER"/segment-* 2>/dev/null | grep -v 'segment-final' | sort -t- -k2 -n | tail -1)
[ -z "$LATEST_SEGMENT" ] && [ -d "$SESSION_FOLDER/segment-final" ] && LATEST_SEGMENT="$SESSION_FOLDER/segment-final"

# Read transcript
TRANSCRIPT="$LATEST_SEGMENT/transcript.jsonl"

If no folder: Analyze current conversation context.

1.2 Detect Project

./scripts/parse_transcript.sh "$TRANSCRIPT" project

1.3 Extract Session Facts

./scripts/parse_transcript.sh "$TRANSCRIPT" all

Extracts: user requests, files read, files modified, commands, errors, subagents, insights.

Phase 2: PLAN

Goal: Determine what to document and whether reflection is required.

2.1 Reflection Decision Gate (MUST complete)

Answer these questions:

Decision:

• If ANY answer is YES → MUST create at least 1 reflection
• If ALL answers are NO → MAY skip reflections

Record decision for Phase 4 verification.

2.2 Search Cross-References (MUST complete before Phase 3)

./scripts/search_cross_references.sh "keyword"

Target 10-15 cross-references distributed across:

• Concepts (3-5)
• Components (3-5)
• Best Practices (1-2)
• Recent Sessions (1-2)
• MOCs (1-2)

See cross-reference-guide.md for methodology.

2.3 External Document Distillation (MUST complete when investigation docs exist)

If external investigation documents exist (100+ KB):

1. MUST detect documents for distillation:

./scripts/detect_external_docs.sh "$SESSION_FOLDER"

2. MUST analyze distillation requirements:

./scripts/analyze_for_distillation.sh "$DOC_PATH"

See distillation-guide.md for detailed methodology.

2.4 Insight Classification (SHOULD complete when insights exist)

If insights were extracted in Phase 1.3, classify each:

Record classifications for Phase 3.

Phase 3: CREATE

Goal: Write documentation in priority order.

Priority Order

1. Concept docs - MUST if patterns discovered OR insight reveals architecture
2. Component docs - MUST if components modified OR insight describes behavior
3. Best practice docs - SHOULD if methodology identified OR insight documents technique
4. Process reflections - MUST if Phase 2.1 decision = required OR insight reveals workflow/anti-pattern
5. Daily session log - MUST (always required, includes all insights)

Document Locations

Reflection Categories

Note: These are example categories. The system discovers reflection categories dynamically from subdirectories in {KB}/reflections/. Create any category folders that fit your workflow.

Cross-Reference Requirements

Every document MUST include:

• Technical docs: 10-15 WikiLinks (minimum 10)
• Reflections: 5-8 WikiLinks (minimum 5)

Verify with:

./scripts/count_wikilinks.sh document.md

YAML Frontmatter (MUST include)

---
title: Document Title
aliases: [Alt 1, Alt 2]
tags: [category, topic]
type: concept|component|best-practice|daily-log|reflection
created: YYYY-MM-DD
modified: YYYY-MM-DD
project: Claude Code
---

Obsidian Syntax (MUST invoke when obsidian skills installed)

When obsidian skills are available, MUST invoke before creating knowledge bank documents:

/obsidian:obsidian-markdown

This ensures proper Obsidian Flavored Markdown syntax for:

• WikiLinks: [[Note]], [[Note#Heading]], [[Note|Display]]
• Callouts: > [!note], > [!warning], > [!tip], etc.
• Properties (YAML frontmatter)
• Tags: #tag, #nested/tag
• Embeds: ![[Note]], ![[image.png]]
• Block references: [[Note#^block-id]]

Verification: Check if obsidian skills exist in available skills list before creating documents.

Phase 4: VERIFY

Goal: Confirm all requirements met before declaring complete.

4.1 Run Verification Script (MUST complete)

./scripts/verify_session_recap.sh \
  --kb-path "$KB_PATH" \
  --project "$PROJECT" \
  --daily-log "YYYY-MM-DD [Topic].md" \
  --reflection-required  # or --no-reflection based on Phase 2.1

4.2 Validate Obsidian Syntax (MUST complete)

./scripts/validate_obsidian_syntax.sh "$DAILY_LOG_PATH"
./scripts/validate_obsidian_syntax.sh "$REFLECTION_PATH"  # if reflection created

MUST validate:

• Frontmatter required fields (title, tags, type, created)
• Callout syntax ([!note], [!warning], etc.)
• WikiLink format and heading anchors

4.3 Verification Checklist

Documentation (MUST verify):

• Daily session log created
• Cross-references ≥ 10 in daily log
• YAML frontmatter present

Reflection Gate (MUST verify):

• Phase 2.1 decision recorded
• If decision = required → reflection exists
• Reflection has ≥ 5 cross-references

Quality (MUST verify):

• No broken WikiLinks
• Code references include file paths and line numbers

Syntax Validation (MUST verify):

• validate_obsidian_syntax.sh exits with code 0 for daily log
• validate_obsidian_syntax.sh exits with code 0 for reflections (if created)

Index Maintenance (MUST verify):

• Obsidian Base indices regenerated for project
• MOC Canvas updated (if MOC modified)

4.4 MOC Updates (conditional)

If new categories or significant content: Add links to relevant MOC.

Phase 5: MAINTAIN

Goal: Update knowledge bank indices and visualizations.

5.1 Regenerate Obsidian Base Indices (MUST complete when new docs created)

MUST regenerate indices when new documents added to knowledge bank:

./scripts/generate_knowledge_base.sh --project "$PROJECT"

Generates queryable indices for concepts, components, practices, and sessions.

5.2 Update MOC Canvas (MUST complete when MOC modified)

MUST update canvas when MOC files modified:

./scripts/generate_moc_canvas.sh "$MOC_PATH"

Creates visual JSON Canvas representation of knowledge relationships.

Decision Reference

When Reflection is REQUIRED

When to Create Each Document Type

Scripts Reference

Common Mistakes

Mistake 1: Skipping Reflections

Symptom: Only technical docs created, no reflections. Cause: Treating "OPTIONAL" as "skip if unsure". Fix: Complete Phase 2.1 decision gate explicitly.

Mistake 2: Insufficient Cross-References

Symptom: Document has < 10 WikiLinks. Cause: Skipping cross-reference discovery. Fix: Run search_cross_references.sh before writing.

Mistake 3: Premature Completion

Symptom: Declaring done without verification. Cause: Not running Phase 4 checklist. Fix: MUST run verify_session_recap.sh before declaring complete.

See common-mistakes.md for full list.

Completion Criteria

Session recap is complete when:

1. ✅ verify_session_recap.sh exits with code 0
2. ✅ Daily log created with ≥ 10 cross-references
3. ✅ Reflection created (if Phase 2.1 decision = required)
4. ✅ All documents have YAML frontmatter
5. ✅ No broken WikiLinks
6. ✅ Obsidian syntax validation passes
7. ✅ Knowledge bank indices updated (if new docs created)

Only then declare: "✅ Session Recap Complete"

Resources

• Templates
• Cross-Reference Guide
• Quality Standards
• Completion Checklist
• Common Mistakes
• Distillation Guide