Doc Manager

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:

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.