---

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>

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/<descriptive-kebab-name>/SKILL.md

Structure:

---
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:

## 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**: <branch name>
- **Status**: <brief status>
- **Last updated**: <today's date>

## Task Progress

- [x] <completed items>
- [ ] <in-progress items> ← CURRENT
- [ ] <planned next items>

## Key Decisions

- <decision>: <rationale>

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:

## 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:

# 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

</brain-dump>