Done

Distill the current session into a single markdown file capturing decisions, questions, next steps, and context for future sessions.

Manual, end-of-session action. Not every session needs it — skip when the session was trivial or exploratory with no decisions worth preserving.

Workflow

Copy this checklist to track progress:

Done progress:

• Step 1: Gather context
• Step 2: Assess significance
• Step 3: Write session file
• Step 4: Confirm

Step 1: Gather context

Collect automatically — do not ask the user:

Git context:

• Current branch: git branch --show-current

• Files changed: git diff --name-only and git diff --cached --name-only

• Recent commits: git log --oneline -10

Session context:

• Claude session ID

• Key decisions made and their reasoning

• Questions raised (answered and unanswered)

• Blockers encountered

• Patterns or learnings discovered

If not in a git repo, use no-repo as branch and skip files-changed.

Step 2: Assess significance

• Write a file when: decisions were made, architecture was discussed, non-obvious approaches were chosen, there are open questions, or meaningful code was written.

• Skip when: quick fix with no decisions, pure exploration with no conclusions, or the user says it is not needed.

If skipping, tell the user why and stop.

Step 3: Write session file

Location:

Default: .claude/done/ in the repo root.

If the folder does not exist, create it:

mkdir -p .claude/done

The user can override this path in their CLAUDE.md or CLAUDE.local.md:

Session files go in /path/to/my/folder

If the custom path does not exist, create it with mkdir -p before writing.

Common alternatives: an Obsidian vault folder, docs/sessions/ , or any custom path.

Filename: YYYY-MM-DD-<branch>-<short-session-id>.md

• Branch: / replaced with - , truncated at 40 chars

• Session ID: first 8 chars

• Example: 2026-02-19-feat-auth-a1b2c3d4.md

Template:

Session: YYYY-MM-DD <branch>

Session ID: <id> Branch: <branch> Date: <date>

Summary

1-2 sentences of what was accomplished.

Decisions

• Decision title: What was decided. Why this approach was chosen.

Questions

• Open question
• Resolved question — answer

Next Steps

• Specific actionable task

Files Changed

• path/to/file — what changed and why

Learnings

• Non-obvious gotcha or pattern discovered

Context for Next Session

Where to pick up. What state is the code in. What needs attention first.

Writing rules:

• Omit any section with no content

• Bullets, not paragraphs

• Decisions must include the "why"

• Next steps must be actionable without re-reading the session

• If 20+ files changed, summarize by directory

• Never overwrite existing session files

Step 4: Confirm

Report the file path and a one-line summary:

Session captured: .claude/done/2026-02-19-feat-auth-a1b2c3d4.md

Sections: decisions (3), questions (1 open), next steps (4), files changed (7)

Anti-patterns

• Do not create a file for trivial sessions (quick typo fix, one-liner)

• Do not include full code snippets — reference file paths and line numbers instead

• Do not ask the user to fill in sections — extract everything from session context

• Do not overwrite existing session files — each session gets a unique file

• Do not create rolling/append files (like PROJECT-STATUS.md) — one file per session

• Do not modify any project files other than the session file itself