--- name: brain-dump description: Two-phase session persistence. Phase A extracts reusable skills from non-obvious discoveries. Phase B persists full session state to CLAUDE.md and docs folder for seamless resume after clear. Use when context window is low, before clear, or when user says brain-dump or save state. metadata: version: 2.0.0 allowed-tools: - Read - Write - Edit - Bash - Glob - Grep - WebSearch --- # Brain Dump — Session Persistence + Knowledge Extraction ## Problem Claude Code loses all session context on `/clear` or `/compact`. Long sessions with complex debugging, architectural decisions, and task progress vanish entirely. Worse, non-obvious discoveries (workarounds, root causes, gotchas) are lost forever — even though they'd help in future sessions on different projects. This skill solves both problems in one pass: - **Phase A**: Extract reusable knowledge into permanent skills (survives across projects) - **Phase B**: Persist session state for immediate resume (survives across `/clear`) ## Trigger Conditions - User types `brain-dump` or `/brain-dump` - User mentions context is running low or they're about to `/clear` - User asks to "save state", "save progress", "persist session" - Session has been long and complex with significant accumulated knowledge --- ## Phase A: Knowledge Extraction (Skill Creation) Review the entire conversation and ask yourself: 1. Did this session involve **non-obvious debugging** (>10 min investigation, not in docs)? 2. Were there **misleading error messages** where the real cause was different from what the error suggested? 3. Did we discover **workarounds** through trial and error? 4. Did we find **configuration gotchas** that differ from standard documentation? 5. Were there **project-specific patterns** worth codifying? ### If YES to any: Create a Skill For each extractable piece of knowledge, create a skill file: **Path**: `~/.claude/skills/brain-dump/extracted//SKILL.md` **Structure**: ```markdown --- name: descriptive-kebab-name description: | [Precise description with exact error messages, trigger conditions, frameworks involved. Use "Use when:" numbered lists. Be specific enough for semantic matching to find this skill when needed.] author: Claude Code version: 1.0.0 date: YYYY-MM-DD --- # [Human-Readable Title] ## Problem [2-3 sentences. Why is this non-obvious?] ## Context / Trigger Conditions - [Exact error message 1] - [Observable symptom 2] - [Environmental condition 3] ## Solution ### Step 1: [Action] [Instructions with code examples] ### Step 2: [Action] [Continue...] ## Verification [How to confirm it worked — testable outcomes] ## Example **Before**: [error or problematic state] **After**: [fixed state] ## Notes - [Caveats, edge cases, when NOT to use] ``` ### Quality Gates Before creating a skill, verify: - [ ] **Reusable**: Will help future sessions (not just this instance) - [ ] **Non-trivial**: Required discovery, not just a docs lookup - [ ] **Specific**: Exact trigger conditions defined (error messages, symptoms) - [ ] **Verified**: The solution actually worked in this session - [ ] **Description is searchable**: Contains exact error messages and framework names ### If NO to all: Skip Phase A Not every session produces extractable knowledge. Mundane tasks, simple fixes, and documentation lookups don't need skills. That's fine — move to Phase B. --- ## Phase B: Session State Persistence ### Step 1: Gather Session Knowledge Review the entire conversation and extract: 1. **Task Status**: What's completed, in progress, and planned next 2. **Key Decisions**: Architectural choices, approach decisions, and WHY they were made 3. **Important File Paths**: Files created, modified, or critical to current work — with line numbers 4. **Active Branch**: Run `git branch --show-current` to get the current branch 5. **Blockers / Open Questions**: Anything unresolved 6. **Debugging Insights**: Non-obvious findings, root causes, gotchas discovered 7. **Dependencies / Setup**: Environment setup, installed packages, config changes ### Step 2: Update CLAUDE.md Read the existing `CLAUDE.md` in the project root. **Preserve any existing permanent instructions** — merge, don't overwrite. Add or update these sections: ```markdown ## Context Recovery IMPORTANT: At session start, read all .md files in the /docs/ directory to restore full project context from the previous session. ## Current State - **Branch**: - **Status**: - **Last updated**: ## Task Progress - [x] - [ ] ← CURRENT - [ ] ## Key Decisions - : ``` This is the **first thing Claude reads** on next session — it must give a clear picture in under 30 seconds. ### Step 3: Create/Update /docs/ Files Create `/docs/` in the project root if needed. **Only create files with genuinely useful content** — no empty boilerplate. #### `docs/current-task.md` Detailed state of current work: - What exactly is being built or fixed - Current approach and implementation details - What's been tried — what worked, what didn't - Specific next steps with enough detail for a fresh session to continue immediately #### `docs/decisions.md` **Append-only** decision log (never overwrite previous entries): - Each entry: date, decision, context, rationale, alternatives considered - This file grows across sessions as a persistent record #### `docs/architecture.md` If architectural decisions were made: - System structure, component relationships - Data flow, API design - Patterns being followed #### `docs/debugging-notes.md` If debugging was involved: - Problem description and symptoms - Root cause analysis - Solution applied - Gotchas and non-obvious behaviors discovered #### `docs/setup.md` If environment or setup steps were performed: - Commands run, packages installed - Config changes made - How to reproduce the current dev environment ### Step 4: Confirm to User After writing all files, report: - **Skills created** (Phase A): list skill names and what they capture - **State persisted** (Phase B): list files created/updated - Confirm they can safely `/clear` - Confirm next session will auto-load `CLAUDE.md` → read `/docs/` --- ## Verification After running brain-dump, verify: 1. `CLAUDE.md` exists and contains `## Context Recovery` pointing to `/docs/` 2. `/docs/` contains only files with real content (no empty files) 3. `docs/decisions.md` preserved all previous entries (if it existed before) 4. Any created skills pass quality gates (reusable, non-trivial, specific, verified) 5. A fresh Claude session reading `CLAUDE.md` + `/docs/` could continue without asking "what are we doing?" ## Example **Scenario**: User spent a session debugging a Prisma connection pool issue in serverless, then building a new API endpoint. **Phase A output** — new skill created: `~/.claude/skills/prisma-serverless-pool.md` capturing the non-obvious fix (connection pooler needed, not just pool size increase). **Phase B output** — state persisted: `CLAUDE.md`: ```markdown ## Context Recovery IMPORTANT: At session start, read all .md files in the /docs/ directory. ## Current State - **Branch**: feat/user-api - **Status**: Prisma bug fixed, API endpoint 80% done - **Last updated**: 2026-02-02 ## Task Progress - [x] Fixed Prisma pool exhaustion (needed PgBouncer, not pool_size increase) - [x] Created GET /api/users endpoint with pagination - [ ] Add POST /api/users with validation ← CURRENT - [ ] Write integration tests ``` `docs/debugging-notes.md`: ```markdown # Prisma Pool Exhaustion (2026-02-02) ## Symptoms - P2024: Timed out fetching a new connection from the pool - Works locally, fails on Vercel after ~10 requests ## Root Cause Serverless functions each create a new Prisma client = new pool. 10 functions × 10 connections = 100 connections > database limit. ## Fix Added PgBouncer connection pooler. Changed DATABASE_URL to pooler URL. ## Gotcha Must use port 6543 (pooler) not 5432 (direct) in production. ``` ## Rules - **Never delete existing useful content** in CLAUDE.md — merge and update - **decisions.md is append-only** — never remove previous entries, only append - **Be specific, not vague** — `src/auth/config.ts:28` not "the auth file" - **Include file paths with line numbers** when referencing code - **Write for a Claude that has zero context** — assume nothing is remembered - **No git operations** — only write files, let the user handle commits - **Only create docs files that have real content** — skip empty categories - **Only create skills that pass quality gates** — don't over-extract mundane fixes ## Notes - `CLAUDE.md` is automatically read by Claude Code at session start — no user action needed - The `## Context Recovery` directive in `CLAUDE.md` tells the next session to read `/docs/` - `decisions.md` is the only append-only file; all others can be fully rewritten each session - Skills created in Phase A are **global** (`~/.claude/skills/`) — they help across all projects - State persisted in Phase B is **project-local** (`CLAUDE.md` + `/docs/`) — specific to this repo - This skill does NOT push to git — the user decides when to commit - For very large projects, consider adding a `docs/file-map.md` listing key files and their purposes