Document — session capture (project-agnostic)
Scope: only what THIS session changed or learned. Not a full-repo pass (that's /full-document). Docs live in .docs/ by default — create the folder if absent. If the repo's runbook names a different docs folder, the runbook wins. Write for someone who wasn't here: a future maintainer or LLM with zero context.
The rule that outranks all others
Capture the WHY, not just the WHAT. Git already records what changed. Docs exist to record what git can't: the intention behind a feature vs how it ended up built, the decision and its rejected alternatives, the mistake that cost hours. If a line only restates the diff, cut it.
What to write (only the parts this session touched)
- Decisions →
.docs/decisions.md (append-only, dated). Each: the decision, the trade-off accepted, what was rejected and why. Never rewrite an old entry — append.
- Mistakes learned →
.docs/gotchas.md (or a ## Gotchas section). The failure, the symptom that fooled you, the root cause, the fix. This is the highest-value doc — it stops the next person (and the next Claude) repeating hours of trial-and-error. Frame each as "if you see X, it's actually Y — do Z."
- Dos & Don'ts for the touched area: the invariant that must hold ("money is integer cents", "server-write-only ledger", "new pages need the shared layout") and the tempting-but-wrong move to avoid.
- How / What / Where: how the touched flow works end to end, what each new/changed piece does, WHERE it lives (file:line, table, edge function, endpoint).
- References: external (API docs, dashboard, ticket, Stack/GitHub thread that unblocked it) and internal (the related doc, the sibling docs file, the migration, the PR). A ref you needed this session, the next person will need too.
- Verification: how this was actually proven to work (the command/URL/screenshot path), so "done" is reproducible — not "typecheck passed".
Discipline
- Dated, titled, factual — an investigation's findings go in a titled dated doc, referenceable later.
- Update
architecture.md ONLY if the structure actually changed. Treat it as protected: append and extend, never rewrite it in a doc pass without explicit instruction.
- Comment the code too: leave
// see .docs/<doc> breadcrumbs at the non-obvious spots so the doc is discoverable from the source.
- No secrets in docs — pointers only ("token in Keychain as
SERVICE_KEY", never the value).
- Report back short: which docs were touched, one line each.
1---2name: document3description: Capture THIS session's work into the repo's docs so a future maintainer or LLM understands it. Use at the end of a meaningful session, after a bug fix, after a decision, or on "document this", "doc it", "log this".4---56# Document — session capture (project-agnostic)78Scope: only what THIS session changed or learned. Not a full-repo pass (that's /full-document). Docs live in `.docs/` by default — create the folder if absent. If the repo's runbook names a different docs folder, the runbook wins. Write for someone who wasn't here: a future maintainer or LLM with zero context.910## The rule that outranks all others11**Capture the WHY, not just the WHAT.** Git already records what changed. Docs exist to record what git can't: the intention behind a feature vs how it ended up built, the decision and its rejected alternatives, the mistake that cost hours. If a line only restates the diff, cut it.1213## What to write (only the parts this session touched)141. **Decisions** → `.docs/decisions.md` (append-only, dated). Each: the decision, the trade-off accepted, what was rejected and why. Never rewrite an old entry — append.152. **Mistakes learned** → `.docs/gotchas.md` (or a `## Gotchas` section). The failure, the symptom that fooled you, the root cause, the fix. This is the highest-value doc — it stops the next person (and the next Claude) repeating hours of trial-and-error. Frame each as "if you see X, it's actually Y — do Z."163. **Dos & Don'ts** for the touched area: the invariant that must hold ("money is integer cents", "server-write-only ledger", "new pages need the shared layout") and the tempting-but-wrong move to avoid.174. **How / What / Where**: how the touched flow works end to end, what each new/changed piece does, WHERE it lives (file:line, table, edge function, endpoint).185. **References**: external (API docs, dashboard, ticket, Stack/GitHub thread that unblocked it) and internal (the related doc, the sibling docs file, the migration, the PR). A ref you needed this session, the next person will need too.196. **Verification**: how this was actually proven to work (the command/URL/screenshot path), so "done" is reproducible — not "typecheck passed".2021## Discipline22- Dated, titled, factual — an investigation's findings go in a titled dated doc, referenceable later.23- Update `architecture.md` ONLY if the structure actually changed. Treat it as protected: append and extend, never rewrite it in a doc pass without explicit instruction.24- Comment the code too: leave `// see .docs/<doc>` breadcrumbs at the non-obvious spots so the doc is discoverable from the source.25- No secrets in docs — pointers only ("token in Keychain as `SERVICE_KEY`", never the value).26- Report back short: which docs were touched, one line each.
danielimad