# Full Document

> Full-repo documentation pass — audit what's documented vs what exists, then create and update the repo's docs until it is fully understandable by any future maintainer or LLM. Use for "document the whole repo", "full doc scan", "get this repo documented end to end", or on an unfamiliar/inherited codebase.

- Skill: `danielimad/full-document` (Agent Skill)
- Install (CLI): `npx skillmds@latest add danielimad/full-document`
- Raw SKILL.md: https://api.skillmd.com/api/skills/danielimad/full-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/full-document

---


# 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
1. Read the repo structure, entry points, package manifests, existing `.docs/` (if any), README, migrations, CI config. Build a mental model of every subsystem.
2. **Gap audit**: list each subsystem/feature and mark documented / partial / undocumented. Present this list first — it's the work plan. Never silently decide scope.
3. 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).