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 run date; never fabricate one. Get it from the environment context, not a guess.

3. Runbook add-on (path C)

For any deploy/release/setup/operational doc, produce a check-only validation script and keep a troubleshooting log. Read references/runbook-validation.md for the script contract, template, and the fix→document loop. In short:

• The validation script (scripts/validate-<name>.sh) is check/dry-run by default. It verifies preconditions and asserts expected state idempotently. Every destructive or outward-facing step is gated behind --run-destructive or a MANUAL: marker — never auto-run.
• Script lives in the documented repo's scripts/, and the runbook section links to it. On a read-only tree, emit the script inline and run it once so you can report its --check outcome.
• Run it (--check). Classify each failure: if the doc/check is wrong, fix it; if it is an operator env/tool/network prerequisite the agent cannot satisfy here, document it as a runbook prereq or MANUAL: step (do not weaken or drop the check just to force green). Append only real fix findings to docs/troubleshooting.md, cited.

4. Validate the run

1. Citations: no non-obvious claim is unsourced. Grep for FLAG: markers. Each marker that remains is an open FLAG: it was raised with the user and is listed in the change summary.
2. Links: every internal [text](path) resolves.
3. Orphans: every docs/*.md is reachable from README.md or another doc within one hop.
4. Inventory closed: every doc is updated, verified-current, or flagged (with the flag surfaced to the user). None left unknown.
5. Runbook: each runbook section links a well-formed check-only validate-<name>.sh: bash -n passes, --help exits 0, and with no arguments it defaults to check mode (MODE="check"). Run --check. Agent-satisfiable local/static checks must pass; env/tool/network gaps that only an operator can close are documented as prereqs/MANUAL: rather than forced to exit 0. docs/troubleshooting.md reflects any real fix applied.
6. Diagrams (if any): Mermaid renders without error (mmdc if available).

Present the change summary defined in references/change-summary.md. It opens with Result: COMPLETE | PARTIAL | FAIL | BLOCKED, then Evidence:, Uncertainty:, Decision:, and a per-doc table. A run that stops early still ends with it. Do not commit unless the user explicitly asks.

Expected output

• Root README.md and docs/*.md reconciled to the code, each non-obvious claim cited to path:line.
• docs/DECISIONS.md — append-only log of every ambiguity resolved with the user.
• For runbook sections: scripts/validate-<name>.sh (check-only) linked from the section, plus docs/troubleshooting.md updated with fixes found during validation.
• The change summary (references/change-summary.md).

Acceptance criteria

A run passes when all hold:

• No invented facts. Every non-obvious claim in every touched doc is either cited to path:line or marked FLAG and raised with the user. Every FLAG left at close is an open FLAG listed in the change summary.
• Inventory closed. Every doc in scope ends updated, verified-current, or flagged; none left unknown or known-stale-and-untouched.
• Decisions logged. Every user-resolved ambiguity is appended to docs/DECISIONS.md with the resolution and (where applicable) source.
• Runbook validated. Each deploy/process/setup section links a check-only, well-formed (Step 4.5) validate-<name>.sh that gates every destructive step, and its --check outcome is reported. Not "exit 0 at all costs": a non-zero exit is acceptable only when every failure is a documented operator prerequisite — never invent a green path by dropping real checks. docs/troubleshooting.md records any real fix applied.
• Links + orphans. Every internal link resolves; no docs/*.md is orphaned.
• Branch discipline. No commits on main/master; all changes on a feature branch. No commit without an explicit user request.
• Summary readable. The change summary meets the four reader checks in references/change-summary.md. Without user feedback on them, report human understanding as unconfirmed.

Edge cases

• No docs exist: all-Generate run. Start from README.md, add docs/ files the code justifies. Still cite everything.
• Docs conflict with code: code wins. Fix the doc to match, cite the code, and log the conflict in DECISIONS.md. Do not delete the user's prose without asking.
• Ambiguity with no code answer: ask the user; never guess. If unreachable, leave the claim as a FLAG and report it — do not fill the gap.
• Monorepo: limit per-component READMEs to packages with public APIs or user-facing behavior; skip build output and generated packages.
• Secrets: never document credentials, tokens, or internal-only endpoints beyond what code comments already expose.
• Read-only repo: emit docs and the validation script as a diff/inline summary instead of writing files; still run the script once to report its --check outcome (including documented prereq failures).

Step Completion Reports

After each major step, emit:

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          × fail — [reason]
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

Use √ pass, × fail, — for context. Per-phase checks:

• Inventory + scope — Ground-truth read, Inventory built, Scope confirmed
• Per-doc pass — Claims cited, Conflicts flagged, Decisions logged
• Runbook add-on — Validate script check-only, Destructive steps gated, Troubleshooting updated
• Validate the run — Open FLAGs listed, Links resolve, Inventory closed, Runbook script well-formed

Guidelines

• Protect the context budget. State the fact, cite it, move on. No filler, no restating the obvious, no marketing tone.
• Adapt structure to project type — not every docs/ category applies.
• Prefer code-derived facts over stale prose; keep existing accurate docs untouched (verified-current).
• Maintain cross-references; remove content only when it's wrong or orphaned, and say so in the summary.