documentlisted

# 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) 1. **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. 2. **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." 3. **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. 4. **How / What / Where**: how the touched flow works end to end, what each ne