--- name: cor-docs description: "Updates a project's Markdown documentation from a git diff between two branches plus the existing codebase, following the Diataxis framework (tutorials, how-to guides, reference, explanation). Edits only the quadrants the change actually affects, asks the user when intent is missing, and keeps output compatible with MkDocs and Zensical. Initializes the docs directory (default docs/) when absent. Use when the user asks to document a branch, update docs from a diff or PR, sync documentation with code changes, set up Diataxis docs, or mentions Diataxis, MkDocs, or Zensical. Claude Code users: invoke as /cor:cor-docs." status: stable stability: guaranteed --- # COR Docs — diff-driven Diataxis documentation Turn a branch diff into precise documentation updates. Write only what the change requires, only in the quadrants it affects, only from verifiable facts. Scope: writes inside the docs directory, the site config file (`mkdocs.yml` or `zensical.toml`), and `.cor/docs.md`. Never edits source code. --- ## Parameters | Parameter | Required | Resolution order | | --- | --- | --- | | `base` | yes | user argument -> ask (suggest `Default Base Branch` from `.cor/docs.md`, else `main`) | | `head` | no | user argument -> current branch (`git rev-parse --abbrev-ref HEAD`) | | `docs-dir` | no | user argument -> `Docs Directory` in `.cor/docs.md` -> `docs` | Never guess `base`. If the user gave none and `.cor/docs.md` has none, ask. Verify both refs exist before anything else: ```bash git rev-parse --verify && git rev-parse --verify ``` If one fails, try `origin/`. If still missing, stop and ask the user for the correct ref. --- ## Asking the user Every question is multiple choice with one `(Recommended)` option plus a free-text option. Use the native question tool when available (`AskUserQuestion` in Claude Code, `vscode_askQuestions` in GitHub Copilot, `request_user_input` in Codex plan mode); otherwise an inline numbered list. Batch related questions in one round; at most four per round. --- ## Workflow ``` Docs Progress: - [ ] Step 1: Resolve parameters - [ ] Step 2: Check docs setup - [ ] Step 3: Collect the diff - [ ] Step 4: Read code and existing docs - [ ] Step 5: Build the impact map - [ ] Step 6: Resolve gaps and confirm - [ ] Step 7: Write pages - [ ] Step 8: Validate - [ ] Step 9: Report ``` **Step 1 — Resolve parameters.** Apply the table above. Read `.cor/docs.md` if present. **Step 2 — Check docs setup.** Run: ```bash python /scripts/check_docs.py --root . --docs-dir ``` - Docs directory missing, or layout errors (`missing root index.md`, `missing quadrant directory`, `missing quadrant index.md`) -> follow [references/setup.md](references/setup.md), then rerun the check. - Existing Markdown not in Diataxis layout -> follow the "Adopting existing docs" section of [references/setup.md](references/setup.md). Load [references/diataxis.md](references/diataxis.md) first; adoption needs the classification. - Pre-existing `broken link` or `nav` errors -> note them; fix only those on pages this run touches, list the rest in the report. **Step 3 — Collect the diff.** Always diff from the merge base (three dots), so changes merged into `base` after branching are excluded: ```bash git diff --name-status ... git diff --stat ... git log --no-merges --format='%h %s%n%b' .. ``` Then read the patch per file or per directory, not all at once on large diffs: ```bash git diff ... -- ``` Skip lockfiles, generated files, snapshots, and formatting-only hunks. Changes in tests are evidence of intended behavior, not doc targets. **Step 4 — Read code and existing docs.** - Read each relevant changed file at `head` in full (`git show :` when `head` is not checked out). Diff hunks alone miss signatures, defaults, and callers. - Find user-facing entry points that expose the change (CLI definitions, routes, config schemas, public exports). - Search the docs directory for every changed public name to find pages that already mention it: ```bash grep -rn "" ``` **Step 5 — Build the impact map.** Load [references/diataxis.md](references/diataxis.md). Classify every user-visible change. Produce this table: | Change | Quadrant | Action | Target page | Evidence | | --- | --- | --- | --- | --- | | `RATE_LIMIT_PER_MINUTE` env added | reference | update | `docs/reference/configuration.md` | `src/config.ts:42` | | Configure rate limits | how-to | create | `docs/how-to/configure-rate-limits.md` | `src/config.ts:42`, commit `a1b2c3d` | Action is one of `create`, `update`, `remove`, `none`. Add one line per quadrant that gets no change, with the reason (e.g. "tutorials: none, first-run path unchanged"). A quadrant with no change is a valid outcome; never pad a quadrant to look complete. Mark a row `GAP` in the Evidence column when the code shows **what** changed but nothing (code comment, test name, commit message, linked issue) shows **why** or **for whom**. Explanation rows depend on intent; reference rows rarely do. A how-to whose steps follow from the code (set this variable, call this command, handle this response) is not a GAP; only recommendations inside it (which value to pick, when to use it) need evidence. **Step 6 — Resolve gaps and confirm.** Show the impact map. In the same round, ask one question per `GAP` row (purpose, target user, recommended usage, known limits). Wait for answers. - User answers -> record the answer as evidence ("user, ") and keep the row. - User declines or does not know -> omit only the unsupported content (rationale, recommendations); keep reference facts and code-derived how-to steps; list the gap in the report. - User edits the map -> apply edits before writing. Never write rationale, intent, or recommendations that no evidence supports. **Step 7 — Write pages.** Follow the page shapes and mixing rules in [references/diataxis.md](references/diataxis.md). For each page written: 1. Prefer updating an existing page over creating a new one. 2. Use names, signatures, and defaults exactly as at `head`. 3. Cross-link quadrants with relative links instead of duplicating content. 4. For created pages: add a bullet under the marker in the quadrant `index.md` and add the path to `nav` in the site config, same order. 5. For removed features: remove or update the reference entry, delete obsolete how-to steps, fix every inbound link (`grep -rn ".md" `). Standard CommonMark plus fenced code blocks with a language tag. No generator-specific syntax (admonitions, tabs, macros) unless the docs directory already uses it. **Step 8 — Validate.** Rerun: ```bash python /scripts/check_docs.py --root . --docs-dir ``` Fix every `ERROR` on pages touched in this run, then rerun. Do not proceed to Step 9 while those errors remain. Triage each `WARN` on touched pages: fix it or state why it is intentional. If the user has the generator installed, also run a strict build (`mkdocs build --strict` or `zensical build`) and fix reported issues on touched pages. Do not install the generator. **Step 9 — Report.** Output: - Range documented: `...` with merge-base short SHA. - Pages created, updated, removed, grouped by quadrant. - Quadrants left unchanged, with reason. - Open gaps the user declined or could not answer. - Pre-existing check errors not fixed. - Preview command for the configured generator (`mkdocs serve` or `zensical serve`). --- ## Anti-patterns - Diffing with two dots (`base..head`) in `git diff`; it includes unrelated changes merged into `base`. - Documenting from diff hunks without reading the full file at `head`. - Touching all four quadrants on every run. - Copying the option table into a how-to guide instead of linking to reference. - Inventing a "why" for an unexplained flag or constant. - Writing a tutorial for a feature that is not on the newcomer path. - Creating a page without adding it to the quadrant `index.md` and `nav`. --- ## Bundled resources - [references/diataxis.md](references/diataxis.md) — quadrant axes, change-to-quadrant signals, page shapes, mixing and writing rules. - [references/setup.md](references/setup.md) — target layout, generator choice, `mkdocs.yml`/`zensical.toml` templates, index page templates, `.cor/docs.md` format, adopting existing docs. - `scripts/check_docs.py` — run it (do not read it). Checks quadrant layout, index pages, relative links and images, quadrant index coverage, nav coverage in `mkdocs.yml`/`zensical.toml`, and numbered steps in tutorials and how-to pages. Python 3 standard library only.