# Document

> 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".

- Skill: `danielimad/document` (Agent Skill)
- Install (CLI): `npx skillmds@latest add danielimad/document`
- Raw SKILL.md: https://api.skillmd.com/api/skills/danielimad/document/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: danielimad (https://skillmd.com/u/danielimad)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/danielimad/document

---


# 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 new/changed piece does, WHERE it lives (file:line, table, edge function, endpoint).
5. **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.
6. **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.