danielimad Full-Document — whole-repo coverage (project-agnostic)
Goal: a cold maintainer or LLM can open the docs folder (.docs/ by default; if the repo's runbook names a different one, the runbook wins) and understand the entire system — what it is, how it works, why it's built this way, and where every mistake-prone edge lives — without reading all the code. This is the repo-wide version of /document.
Phase 1 — Map before writing
- Read the repo structure, entry points, package manifests, existing
.docs/(if any), README, migrations, CI config. Build a mental model of every subsystem. - Gap audit: list each subsystem/feature and mark documented / partial / undocumented. Present this list first — it's the work plan. Never silently decide scope.
- Treat
architecture.md(and any project-designated protected file) as extend-only — never rewritten without an explicit go.
Phase 2 — The document set every project should have
Create/update these under .docs/ (skip only what genuinely doesn't apply, and say which):
architecture.md— the live system: layers, data flow, how major components connect, the doc index. The map everything else hangs off.codebase-map.md— what every significant file/module does, one line each. The "where is X" lookup.domain-model.md— what the business logic MEANS (entities, states, the definition of every money/date/status value). Screens render this; they don't invent it.decisions.md— append-only log: each decision, date, trade-off accepted, alternatives rejected. The "why is it like this".gotchas.md— mistakes learned, in "symptom → real cause → fix" form. The anti-repeat ledger. Mine it from past session history and from the code's own scar tissue (workarounds,// hack, defensive checks).conventions.md— the dos & don'ts / unbreakable laws of this repo: invariants (money units, write-paths, i18n, RLS), naming, package manager, the tempting-wrong moves.integrations.md— every external service: auth method, rate limits, known limitations, where its secret is stored (pointer, never value), the dashboard/docs URL.runbook.md— the operational card (see the /runbook skill): test tenants, known IDs, health checks, deploy commands, git rules, dev-server port.verification.md— how to prove the app works: the exact typecheck/lint/test battery + the runtime check (URL/simulator/curl) that counts as real proof.
Phase 3 — Wire it together
- Cross-link docs; add
// see .docs/<doc>breadcrumbs at non-obvious code spots. - Every external + internal reference captured where it's relevant.
- A reusable pattern worth keeping beyond this repo → flag it for wherever you keep cross-project notes, citing this repo as the source.
Discipline
- WHY over WHAT throughout — if a doc just narrates the code, it's noise.
- Dated, factual, no secrets (pointers only).
- Sequence-safe: for many files, work through the audit list steadily; don't dump 50 files of prose at once — cover subsystem by subsystem.
- Reply: the gap-audit table first (for approval on scope), then progress per subsystem, then a coverage summary (documented N/total subsystems).