Wrap up a session — capture discoveries, verify, prepare for PR or next session
Before ending this session, complete these steps in order.
Why: Discoveries are the surprises — things that weren't in the spec or that contradicted expectations. They prevent future sessions from hitting the same walls.
Check: did anything surprising happen during this session? If yes, create or update a discovery file at docs/discoveries/YYYY-MM-DD-topic.md. Create the docs/discoveries/ directory if it doesn't exist.
Only capture what's NOT obvious from the code or git diff:
Do NOT capture:
Use this format:
# Discoveries — [topic]
**Date:** YYYY-MM-DD
**Spec:** [link to spec if applicable]
## [Discovery title]
**Expected:** [what we thought would happen]
**Actual:** [what actually happened]
**Impact:** [what this means for future work]
If nothing surprising happened, skip the discovery file entirely. No discovery is a good sign — the spec was accurate.
If docs/context/ exists, quickly check whether this session revealed anything about:
docs/context/production-map.mddocs/context/dangerous-assumptions.mddocs/context/decision-log.mddocs/context/institutional-knowledge.mdSkip this if nothing applies. Don't force it — only update when there's genuine new context.
Run the project's validation commands. Check CLAUDE.md or AGENTS.md for project-specific commands. Common checks:
tsc --noEmit, mypy, cargo check)npm test, pytest, cargo test)eslint, ruff, clippy)Fix any failures before proceeding.
If working from an atomic spec in docs/specs/ (scan recursively — specs may be in subdirectories like docs/specs/<feature-name>/):
CompleteIn Progress, note what's leftIf working from a Feature Brief in docs/briefs/, check off completed specs in the decomposition table.
Commit all changes including the discovery file (if created) and spec status updates. The commit message should reference the spec if applicable.
Check CLAUDE.md or AGENTS.md for "Git Autonomy" in the Behavioral Boundaries section. If it says "STRICTLY ENFORCED" or the ALWAYS section includes "Push to feature branches immediately after every commit":
git push origin <branch> — do not ask, do not hesitate.gh pr create with a summary of all completed specs. Do not ask first.If CLAUDE.md or AGENTS.md does NOT have autonomous git rules (or has "ASK FIRST" for pushing), ask the user before pushing.
Session complete.
- Spec: [spec name] — [Complete / In Progress]
- Build: [passing / failing]
- Discoveries: [N items / none]
- Pushed: [yes / no — and why not]
- PR: [opened #N / not yet — N specs remaining]
- Next: [what the next session should tackle]
Tip: Run /new before starting the next step. Your artifacts are saved to files — this conversation context is disposable.