/doc-manager

name: doc-manager
description: "Generate or update docs to match the code, citing each claim to path:line and asking on ambiguity; runbook docs also get a check-only validation script. Don't use for API-reference autogen (JSDoc/Sphinx), landing pages, or CLAUDE.md/AGENTS.md."
license: MIT
effort: medium
metadata:
  version: 2.1.1
  author: "Luong NGUYEN <luongnv89@gmail.com>"

Doc Manager

Keep a project's Markdown documentation **true to the code**. Every run ends with each doc `updated`, `verified-current`, or `flagged` — and every non-obvious claim traced to a source. Scope is Markdown only (`README.md`, `docs/*.md`, per-component READMEs); docstrings and comments are read as source-of-truth but not rewritten.

**Prime directive — never invent.** If the code does not show it and the user has not stated it, do not write it. For code-provable facts, reconcile the docs to the code and cite `path:line`; ask the user only when code cannot settle an intent or fact, then record the resolution in `docs/DECISIONS.md`. Preserve user-authored prose unless the user approves its deletion. A guess is a defect here, not a convenience.

Repo Sync Before Edits (mandatory)

Before creating/updating/deleting any file in the repo, sync the current branch:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"

If the tree is dirty: `git stash push -u -m "pre-sync"` → sync → `git stash pop`. If `origin` is missing, or rebase/stash conflicts occur, **stop and ask** before continuing.

Prerequisites

Validate before starting; if any fails, stop and surface it:

• **Git**: `git --version` ≥ 2.30. Working tree clean or stashable.
• **Remote**: `git remote get-url origin` resolves (needed for sync). If absent, ask before any pull/rebase.
• **Write access**: analysis needs read only. Writing files needs the tree to be writable; if read-only, emit a diff/summary instead of writing.
• **Mermaid** (optional): only if diagrams must be exported — `command -v mmdc`.

Branch selector

Work one doc at a time. For each doc in the inventory, pick the path:

| Situation | Path | |---|---| | A needed doc does not exist | **A. Generate** | | A doc exists but may not match the code | **B. Reconcile** | | A doc **or a section of one** covers deploy / release / setup / operational process | also run **C. Runbook add-on** |

A single run usually mixes A and B across the inventory. C is additive — it layers onto whichever of A/B produced runbook content. Classify **at the section level**: a doc that mixes a runbook section with reference content gets C applied to the runbook section only, not the whole file.

Workflow

0. Feature branch

1. If already on a task feature branch, skip. 2. Detect convention: `git branch -r | head -20` (`feat/`, `feature/`, …). 3. Create `feat/doc-manager` (or the repo's convention). If that branch already exists, ask the user whether to reuse it or create `feat/doc-manager-<YYYYMMDD>`.

1. Inventory + scope

Read the codebase to establish ground truth, then build the doc inventory.

• **Project facts**: type (library/API/web/CLI/service), entry points, config, scripts, env vars, endpoints — each with its source location. This is your citation pool.
• **Existing docs**: every `README.md`, `docs/*.md`, per-component README.
• **Inventory table** — for each doc: `path | purpose | status(unknown) | is-runbook?`. Also list **needed-but-missing** docs implied by the code (e.g. code has a `deploy/` dir but no `docs/deployment.md`).

Present the inventory and ask the user to confirm the scope. If the user narrows it, use the narrowed scope. If the user declines or does not answer, stop before editing and report `BLOCKED — scope not confirmed`. **Do not silently expand** beyond confirmed scope.

2. Per-doc pass

For each doc, run its path. Cite as you write — do not defer citation to a review pass.

**A. Generate** — create from code analysis. Include only what the code (or a user answer) supports. Structure by relevance to project type; skip categories that don't apply.

**B. Reconcile** — diff doc against code:

• Claim matches code → keep; add a citation if missing, and **re-verify any existing `path:line` still resolves to the claimed fact** (line numbers rot when code above them shifts — repoint or FLAG stale cites).
• Claim contradicts code → fix to match code, cite the code.
• Claim unverifiable from code and not user-stated → **flag** inline (`<!-- FLAG: unverified — {what} -->`) and ask the user; never silently keep or delete.
• Doc fully current (every cite re-verified) → mark `verified-current`, touch nothing.

**Citation rule (checkable).** Every non-obvious factual claim carries an inline source. Forms, in order of preference:

• Single line — `src/server.ts:12` (a specific value: port, default, flag).
• Range / multi-source — `src/retry.ts:8-24` or `config.ts:4, env.ts:11` for an emergent fact that spans lines/files (e.g. "retries 3× with backoff", "config merges env > file > defaults"). This is a real citation, **not** a FLAG — FLAG is only for facts the code cannot confirm.
• Whole file — `src/router.ts` when the fact is the file's overall behavior and no line is more authoritative.

> The server listens on port 8080 (`src/server.ts:12`).

**Cite unless trivially obvious.** Default to citing; the burden is on treating a claim as obvious, not on citing it. Section intros and definitions of common terms are obvious. Anything a reader could get wrong — ports, commands, paths, env vars, versions, endpoints, defaults, behavior — is not. This coverage check is a **judgment pass** (grep can't verify it), so err toward over-citing: an uncited factual claim is the exception you must be able to justify.

**Decisions log.** Every ambiguity you ask about gets appended to `docs/DECISIONS.md`:

## YYYY-MM-DD
- Q: {the ambiguity}
- A ({who}): {resolution}
- Source: `path:line` (if code-derived)

Use the