Reflect — Session Knowledge Capture

Scan the current session for valuable lessons and route them to the right knowledge target.

Workflow

Step 1: Gather Session Context

Read-only scan of what happened this session:

git diff main --stat
git log main..HEAD --oneline
git diff main

Also review conversation context: problems solved, errors hit, workarounds applied, patterns discovered.

Step 2: Scan Existing Knowledge Base

Quick skim (not full read) to avoid duplicates:

• ~/.claude/projects/*/memory/MEMORY.md — current gotchas
• Project CLAUDE.md — current rules
• ~/.claude/skills/ directory listing — skill coverage
• docs/ directory listing — existing documentation

Step 3: Identify Knowledge Gaps

Classify each insight into exactly one category:

Filters:

• Skip routine changes (simple renames, formatting, obvious fixes)
• Skip duplicates of existing knowledge
• Max 7 suggestions
• Priority: gotchas > rules > skill updates > docs > new skills

Step 4: Present Summary

Concise table — scannable in 5 seconds:

## Session Reflection

| # | Category | Target | Suggestion |
|---|----------|--------|------------|
| 1 | Gotcha | MEMORY.md | Convex v.array() inside unions panics |
| 2 | Skill | /workos | Add headless login refresh pattern |

**Why 1:** We hit a runtime panic when... (1 sentence)
**Why 2:** The headless flow required... (1 sentence)

If nothing worth capturing: "No new knowledge. Existing docs cover this session." — stop here.

Step 5: User Approval

Use AskUserQuestion with multiSelect. Options:

• Each numbered suggestion as a selectable item
• "Apply all"
• "Skip all"

NEVER auto-apply without explicit user approval.

Step 6: Apply Approved Updates

For each approved suggestion:

Keep edits minimal — add bullet points, don't reorganize existing content.

Step 7: Commit Knowledge Changes (Optional)

Ask user whether to commit with: docs: capture session lessons

If user declines, leave changes staged but uncommitted.

Rules

• NEVER auto-apply without user approval (Step 5)
• NEVER create new skills directly — route to /skill-creator
• NEVER modify source code — only knowledge files (MEMORY.md, CLAUDE.md, skills, docs)
• Max 7 suggestions per reflection
• Keep it FAST — this should take under 60 seconds
• Gotchas → MEMORY.md, permanent patterns → CLAUDE.md
• One sentence of "why" context per suggestion — no essays