/repo-docs

name: repo-docs
description: Build and maintain a Markdown guide that helps humans understand a repository through real behavior, concepts, and evidence. Use when a user asks to understand a repo, generate or update repo-docs, answer repo-architecture/onboarding questions, seed docs for a new project, sync docs after code changes, or delete generated repo docs.

Repo-Docs

Mission

`repo-docs` explains a repository to a human reader.

Do not start with a tree tour. Build a reader model first: what problem the repo solves, one real behavior it performs, the concepts behind that behavior, where those responsibilities live in code, where source truth lives, and how to verify the understanding.

Load Order

1. Read this file first. 2. Open [REFERENCE.md](REFERENCE.md) for task routing when detailed rules are needed. 3. Open only the topic file the router points to. 4. Open [EXAMPLES.md](EXAMPLES.md) only for finished-page tone or output-shape examples. 5. Prefer bundled scripts over rewriting deterministic checks.

Keep the routing narrow. `SKILL.md` defines the contract; topic files carry the detailed rules. If a detail appears in two places, keep it in the topic file and leave a pointer here.

Document Contract

| File | Role | | --- | --- | | `SKILL.md` | Entry: mission, core laws, output contract, mode router, finish gate | | `REFERENCE.md` | Router to topic files; open only when detail is needed | | `WRITING.md` | Explanation design, voice, evidence discovery | | `PAGE_RULES.md` | Build workflow, reader paths, page types, output shape, navigation | | `SCOPE_MODES.md` | Seed, large/monorepo scope, specialized repos | | `SYNC_RULES.md` | Sync decision gate, question loop, change sync, widened content alignment | | `ROOT_AGENT_RULES.md` | Root `AGENTS.md` / `CLAUDE.md` routing block and install contract | | `QUALITY_RULES.md` | Evidence labels, source truth, quality bar | | `EXAMPLES.md` | Finished-page tone and output-shape examples | | `scripts/validate_repo_docs.py` | Structure, links, sync anchors, freshness, evidence, references scope, and quality-review checks | | `validate_repo_docs.py` | Compatibility wrapper for older invocations | | `evals/` | Source-repository regression fixtures and assertions for this skill; not required at runtime | | `../repo-docs-zh/SKILL.md` | Chinese language overlay |

Core Laws

• Behavior before inventory: teach one real workflow, request, task, failure, or data path before describing the tree.
• Code location after behavior: once the reader understands one real path, map every in-scope first-party source directory and the key files or symbols needed to locate changes without repeating module explanations.
• Representative case before abstraction: when a module explains a mechanism whose meaning depends on inputs, state changes, outputs, decisions, or boundaries, include a compact evidence-backed case or explicitly state why a case would mislead.
• Shape follows reader need: prose explains why; structure shows what. Use tables, lists, timelines, fenced blocks, or flowcharts when they make comparisons, cases, sequences, commands, or lookup easier to scan.
• Evidence before claims: inspect source, tests, config, data, commands, or artifacts before writing durable statements.
• One durable fact, one home: code location lives in `code-map.md`; concept knowledge and mechanism details live in `modules/`; fixed generated audit artifacts live in `references/`; terms live in `glossary.md`; guide history lives in `change-log.md`.
• Sync only when the guide would mislead: ordinary repo questions require a foreground decision, not automatic doc edits.
• Validate before delivery: run the validator or state why it could not run.

Red flags that mean stop and re-route:

| Thought or draft move | Better action | | --- | --- | | "I'll start with the file tree." | Pick the behavior the reader should follow. | | "The path/function name explains it." | Write the reader handle first; use source as proof. | | "This schema/catalog deserves a references page." | Put details in the owning module; keep `references/` fixed. | | "A repo question always means patch docs." | Run the sync decision gate and use `answer-only` when the guide is already safe. | | "The docs look fine; no validator needed." | Run the validator or report the blocker. |

Output Contract

Use the smallest package that teaches the repo honestly.

• Standard: `README.md`, `walkthroughs/one-real-run.md`, `code-map.md`, `modules/`, `references/source-evidence.md`, `glossary.md`, `change-log.md`; add `references/quality-review.md` when the guide is source-heavy, high-risk, generated, or handoff-sensitive.
• Lite: `README.md`, `walkthroughs/one-real-run.md`, `references/source-evidence.md`, `change-log.md`; use for small repos with little durable terminology. Add `code-map.md` when the small repo still has multiple first-party implementation areas or the reader needs a change-location index.
• Seed: `README.md`, `change-log.md`, optional `glossary.md`; label facts as `Confirmed`, `Planned`, or `Unknown`.

Page Ownership

| Page | Job | | --- | --- | | `README.md` | Orient the reader and point to the first useful path. | | `walkthroughs/one-real-run.md` | Follow one real behavior end to end with numbered `## Step N: behavior` headings. | | `code-map.md` | Map in-scope first-party directories to responsibilities, key files or symbols, main-path connections, and change locations after the behavior model is established. | | `modules/<concept>.md` | Explain one durable concept named by the walkthrough, including details, representative cases, call/data shapes, commands, fields, caveats, and verification hooks needed to understand it. | | `references/source-evidence.md` | Fixed generated evidence base: traversal log, coverage notes, claim/evidence/confidence/caveat rows, and source material later pages may use. | | `references/quality-review.md` | Optional fixed generated audit note for sourc