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