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. Exit the work session: The SessionEnd hook automatically saves transcript segments and builds session.md as a hub note with links to all artifacts.

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

   claude
   

3. Invoke session-recap with the session folder:

   Recap the session at {KB_PATH}/_sessions/YYYY-MM-DD/{session_id}/
   

   Or:

   /second-brain:session-recap {KB_PATH}/_sessions/YYYY-MM-DD/{session_id}/
   

Legacy: Raw Transcript Path

If no session folder exists (e.g., hooks were not configured), you can still provide a raw .jsonl transcript path:

Recap the session at /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

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

Full Recap — No Shortcuts

Every session recap executes all 5 phases completely — no exceptions. A daily log alone is not a recap; it's a log entry. The knowledge bank compounds from extracted concepts, reflections, and best practices, not from session summaries. Skipping phases produces a diary, not a brain.

Even when processing many sessions, each session gets its own full Phase 2.1 reflection gate, Phase 2.4 source ingestion plan, and Phase 3 document creation. Do not batch sessions into a single daily log or skip phases for throughput.

Batch Recap

When recapping multiple sessions (e.g., "recap all sessions since March 29"):

1. Discover — list all sessions in date range, read each session.md for metadata
2. Triage — skip sessions with no transcript, trivial (<5 user messages), or already recapped
3. Process chronologically — full 5-phase workflow per session, each gets its own daily log + extracted docs
4. Parallelize when independent — different projects/topics can use parallel agents; same investigation thread should be sequential for cross-references
5. Integrate once at end — index regeneration and log append after all sessions, not per session

Workflow

Phase 1: ANALYZE

Goal: Load session data and extract facts.

1.1 Load Session Data

If session folder provided:

First, read session.md as the hub note for both metadata and content navigation:

obsidian vault="knowledge-bank" read path="_sessions/{date}/{session_id}/session.md"

Frontmatter metadata (supplements later phases):

• project, session_name, tags, summary, duration_seconds, started_at, ended_at, transcript_source

Body navigation — follow session.md body sections:

Then locate the transcript:

# Preferred: read transcript_source from session.md frontmatter (v2.1+)
TRANSCRIPT_SOURCE=$(read_frontmatter_prop "$SESSION_FOLDER/session.md" "transcript_source")

if [ -n "$TRANSCRIPT_SOURCE" ] && [ -f "$TRANSCRIPT_SOURCE" ]; then
    TRANSCRIPT="$TRANSCRIPT_SOURCE"
else
    # Fallback for old sessions: find latest segment copy
    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"
    TRANSCRIPT="$LATEST_SEGMENT/transcript.jsonl"
fi

If no folder (current conversation mode): Skip session.md reading. Analyze current conversation context.

1.2 Detect Project

If session.md project property is set (non-empty) → use it directly.

Otherwise → fall back to transcript parsing:

./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.

1.4 Detect Session Sources (SHOULD complete when session folder provided)

Scan session.md body sections and transcript for ingestible knowledge:

./scripts/detect_session_sources.sh "$SESSION_FOLDER" "$TRANSCRIPT"

Outputs classified sources, one per line: artifact|<path>|<description> or reference|<path>|<description>.

Record the classified list for Phase 2.5.

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 Source Ingestion Plan (SHOULD complete when sources detected in 1.4)

For each source detected in Phase 1.4, decide:

Guidelines:

• Artifacts in docs/ are high-value by default — they were already distilled during the session
• Plans capture decision rationale — ingest when they document non-obvious architectural choices
• Memory snapshots supplement context but rarely need their own KB doc — skip unless they contain unique project insights
• External references need judgment — don't ingest the entire article, extract its key insights relevant to the session's work

Record decisions for Phase 3 creation.

2.5 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. Artifact-derived docs - SHOULD if Phase 2.4 decision = ingest (from session docs/ artifacts, plans). Use 5-8 WikiLinks. Frontmatter: source-type: artifact, ingested-from: {path}
5. Reference-derived docs - MAY if Phase 2.4 decision = ingest (from external references). Use 5-8 WikiLinks. Frontmatter: source-type: reference, ingested-from: {path or URL}
6. Process reflections - MUST if Phase 2.1 decision = required OR insight reveals workflow/anti-pattern
7. 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
session-folder: _sessions/YYYY-MM-DD/{session_id}
source-type: session|artifact|reference    # Optional: how this knowledge entered the KB
ingested-from: /path/to/source.md          # Optional: provenance for artifact/reference docs
---

The session-folder field applies to ALL recap-created docs (daily log, concepts, components, best practices, reflections). It creates a reverse reference — Obsidian's backlinks panel on session.md will show all KB docs extracted from that session. Omit if no session folder was provided (current conversation mode).

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
• Knowledge Bank index regenerated (_meta/index.md)
• Operation log entry appended (_meta/log.md)
• 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 Regenerate Knowledge Bank Index (MUST complete when new docs created)

Without this, newly created docs won't appear in _meta/index.md and knowledge-bank-lookup can't discover them via the unified catalog:

source skills/common/generate_index.sh
generate_index "$KB_PATH"

5.3 Append Operation Log (MUST complete)

The operation log feeds kb-lint's staleness detection and provides an audit trail of what changed when:

source skills/common/obsidian_helpers.sh
append_kb_log "$KB_PATH" "ingest" "session-recap" "Created: [list created docs]. Updated: [list updated docs]"

5.4 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.

Scripts Reference

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

• KB Schema — Unified conventions for all KB documents (document types, frontmatter, WikiLinks, naming)
• Templates
• Cross-Reference Guide
• Quality Standards
• Completion Checklist
• Common Mistakes — top 3: skipping reflections, insufficient cross-refs, premature completion
• Decision Reference — when reflection is required, when to create each doc type
• Distillation Guide