Agent Skills: Session Debrief

Session Debrief

Capture learnings from the current session and persist them into project documentation. The goal is continuous improvement: never repeat the same mistakes, always build on what we learn.

Phase 1: Review the Session

Scan the conversation history for learnings. Look for these signals:

| Signal | What to capture | |--------|----------------| | Corrections ("no, use X instead") | The right approach and why the wrong one fails | | Debugging breakthroughs | Root cause and fix, not just the symptom | | Repeated mistakes | Pattern that keeps tripping us up | | Architectural decisions | What was chosen and the reasoning | | Surprising behavior | Gotchas, edge cases, unintuitive APIs | | Process friction | Steps that were slow, confusing, or error-prone | | Discovered conventions | Patterns in the codebase that weren't documented |

Categorize each learning:

| Category | Typical destination | |----------|-------------------| | Mistake/Correction | CLAUDE.md (universal) or .claude/rules/ (domain-specific) | | Architectural Decision | CLAUDE.md or project docs (ARCHITECTURE.md, ADRs) | | Gotcha/Pitfall | .claude/rules/ with path-scoping | | Pattern/Convention | .claude/rules/ with path-scoping | | Process Improvement | CLAUDE.md or CONTRIBUTING.md | | Debugging Insight | .claude/rules/ topic file |

If the session had no meaningful learnings (simple task, everything went smoothly), say so and stop. Don't force learnings that aren't there.

Phase 2: Audit Existing Documentation

Before proposing changes, read CLAUDE.md, scan .claude/rules/ for existing rule files, and check for project docs (ARCHITECTURE.md, CONTRIBUTING.md, docs/). Follow any @ imports and path references in CLAUDE.md to discover documentation locations.

For each learning, check:

• Is it already documented? → Skip
• Does it contradict existing docs? → Propose update to existing entry
• Is it genuinely new? → Propose addition

Estimate CLAUDE.md line count and track against the 300-line budget.

Phase 2.5: Prune Stale Entries

Activates when BOTH conditions are true:

• CLAUDE.md is above 250 lines
• Phase 1 found high-signal learnings that warrant CLAUDE.md addition

Scan CLAUDE.md for entries that no longer earn their place:

| Category | How to verify | |----------|--------------| | Duplicated by docs | Entry restates guidance in a docs/*.md file that CLAUDE.md already references | | Enforced by toolchain | Linter, ast-grep, CI, or pre-commit hook already catches this (check config files) | | Outdated | Convention no longer matches codebase (verify with grep/glob) | | Session debris | Ephemeral context from a past session that was never cleaned up |

Rules:

• Require evidence for every removal — cite the doc, linter rule, or grep result that proves staleness
• When uncertain, keep the entry — false removals are worse than bloat
• Never prune architectural decisions or safety-critical rules without explicit user confirmation
• Present removals in Phase 3 alongside additions so the user sees the full picture

Phase 3: Propose Updates

Present ALL proposed changes to the user in a single summary before writing anything.

Format for Proposals

## Session Debrief: Proposed Updates

### 1. CLAUDE.md (289 → 285 lines, net -4)
**Removals (pruned):**
- **Remove line 142**: "Use X pattern" — now documented in docs/SERVICES.md (referenced on line 12)
- **Remove line 87**: "Run prettier before committing" — enforced by pre-commit hook in .husky/pre-commit

**Additions:**
- **Add**: "IExceptionHandler gotcha: need both AddExceptionHandler() and UseExceptionHandler() (see src/Program.cs:42)"
- **Update**: Change "Use npm" → "Use pnpm (npm causes lockfile conflicts)"

### 2. .claude/rules/api-conventions.md (new file)
- **Add**: Path-scoped rule for `src/api/**/*.ts`
- Content: "All API handlers must validate input with zod schemas before processing"

### 3. Skipped
- [Session-specific detail] — not generalizable
- [Already documented in .claude/rules/testing.md]

CLAUDE.md Token Discipline

These rules are non-negotiable when proposing CLAUDE.md changes:

1. Under 300 lines — If above 250, trigger Phase 2.5 pruning before routing to .claude/rules/
2. Earn its place — Ask: "Would removing this cause Claude to make mistakes in future sessions?" If no, don't add it.
3. One-liners only — Brief, actionable. No paragraphs.
4. No inline code blocks — Use file:line references (e.g., see src/config.ts:15-20)
5. Use @imports for detailed docs — @docs/api-patterns.md not inline explanations
6. Route domain knowledge to .claude/rules/ — Path-scope when possible
7. Prefer updating over adding — Extend an existing bullet point rather than adding a new one
8. Never duplicate linter rules — If ESLint/Prettier/Ruff enforces it, don't document it

.claude/rules/ Best Practices

• One topic per file — api-conventions.md, testing.md, debugging.md
• Use path-scoping when the rule only applies to certain files
• Keep files focused — 20-50 lines per file, not sprawling documents
• Use clear filenames — Future sessions need to find these by name

Project Docs Updates

When updating CONTRIBUTING.md, ARCHITECTURE.md, docs/*.md:

• Check for a docs/ folder and route learnings to the most specific existing doc
• Follow CLAUDE.md @ references to find authoritative locations
• Match existing style, add to existing sections
• Keep it useful for humans too — these docs serve the whole team

Phase 4: Apply with Approval

Use AskUserQuestion to get approval:

{
  "questions": [{
    "question": "Here are the proposed documentation updates from this session. Which should I apply?",
    "header": "Updates",
    "multiSelect": false,
    "options": [
      { "label": "Apply all", "description": "Apply all proposed changes listed above" },
      { "label": "CLAUDE.md only", "description": "Only update CLAUDE.md, skip other files" },
      { "label": "Rules only", "description": "Only update .claude/rules/ files" },
      { "label": "Let me pick", "description": "Show each change individually for approval" }
    ]
  }]
}

After applying, show a summary table of what was updated with file, change description, and line delta. Report final CLAUDE.md line count and remaining budget.

What NOT to Capture

• Session-specific context — "We were debugging issue #42" (ephemeral)
• Speculative conclusions — "This might also affect X" (unverified)
• Obvious things — "Use git to commit" (Claude already knows)
• Temporary workarounds — Unless they're long-lived and affect the team
• Personal preferences — Route to ~/.claude/CLAUDE.md or CLAUDE.local.md instead
• Things the linter catches — Trust the toolchain

Edge Cases

• No CLAUDE.md exists: Create a minimal one with the project name and the first learning
• CLAUDE.md above 250 lines: Trigger Phase 2.5 pruning first. Only fall back to routing all learnings to .claude/rules/ if pruning cannot free sufficient space
• .claude/rules/ doesn't exist: Create it with the first rule file
• Contradictory information: Flag explicitly. Don't silently overwrite — the existing docs may be correct
• No learnings found: Say so honestly. Don't manufacture learnings to justify running the skill

$ARGUMENTS