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
- [x] 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