|
| 1 | +--- |
| 2 | +description: Reconcile this repo's documentation to the current state of its code. Read-only on code; edits docs only. Runs unattended (no questions). |
| 3 | +allowed-tools: Read, Grep, Glob, Edit, Write, Bash(date:*), Bash(git status:*), Bash(git checkout:*), Bash(git branch:*), Bash(git add:*), Bash(git commit:*), Bash(git diff:*), Bash(git log:*), Bash(git rev-parse:*) |
| 4 | +--- |
| 5 | + |
| 6 | +You are running **unattended** in a fresh session inside ONE target repository. Your only job: |
| 7 | +make this repo's **documentation accurately reflect the current state of its code** — and change |
| 8 | +nothing else. |
| 9 | + |
| 10 | +## Absolute rules (non-negotiable) |
| 11 | + |
| 12 | +1. **Code is read-only ground truth.** You may READ any file. You may EDIT only documentation: |
| 13 | + `README.md`, `CLAUDE.md`, `AGENTS.md`, a new `DOC-RECONCILIATION.md`, and anything under `docs/`. |
| 14 | + Never create, modify, or delete source code, config, tests, lockfiles, or any non-doc file. |
| 15 | +2. **Do not execute anything.** No running the app, no builds, installs, test runs, or project |
| 16 | + scripts. Determine reality by READING: source, test files, manifests, git history. (Reading a |
| 17 | + test file is fine; running it is not.) |
| 18 | +3. **Do not push. Do not commit to `main`/`master`.** Work on a branch. |
| 19 | +4. **Run unattended — never ask the user a question.** Where you would normally ask, instead record |
| 20 | + the ambiguity in the report and proceed conservatively (leave the doc unchanged, mark it |
| 21 | + `unverifiable`). |
| 22 | +5. **Never guess or upgrade a claim the code can't support.** If the code can't confirm something, |
| 23 | + leave the doc text as-is and mark it `unverifiable` with the reason. Honesty over completeness. |
| 24 | +6. **Preserve human-authored nuance.** Don't delete content you merely can't verify — flag it. |
| 25 | + Edit surgically, in each doc's existing voice and structure. Smaller diffs are better. |
| 26 | + |
| 27 | +## What "current state" means |
| 28 | + |
| 29 | +**Accuracy, not completeness.** A half-built project should get docs that honestly say |
| 30 | +"Phase 2 of 4 — X built, Y stubbed, Z not started." A finished-but-underdocumented project should |
| 31 | +get its docs brought **up** to reflect what's actually there. If the code shows the project is |
| 32 | +broken or stalled, the doc should say so plainly — you report the state, you never fix it. |
| 33 | + |
| 34 | +## Procedure |
| 35 | + |
| 36 | +**0 · Orient.** Identify the project type from manifests (`package.json`, `Cargo.toml`, |
| 37 | +`pyproject.toml`, `go.mod`, `*.xcodeproj` / `Package.swift`, etc.). List the doc files present and |
| 38 | +the top-level directory structure. Note the current git branch and HEAD sha. |
| 39 | + |
| 40 | +**1 · Establish ground truth from code (read-only).** Gather evidence for each of the six claims: |
| 41 | +- **What it is** — entry points (main / index / app / route files / CLI commands / library root), |
| 42 | + core modules, README intro. |
| 43 | +- **Current state** — implemented features vs. stubs/TODOs; presence and breadth of tests; recent |
| 44 | + git history; any `STATUS` / `ROADMAP` / `HANDOFF` docs. Be conservative about status labels. |
| 45 | +- **Stack** — languages, frameworks, key tools, from manifests + a file-extension census. |
| 46 | +- **How to run** — the run/build commands that **actually exist** (package.json scripts, Makefile |
| 47 | + targets, Cargo bins, `console_scripts`, etc.). Confirm whether the documented command is defined. |
| 48 | + Do **not** execute it. |
| 49 | +- **Known risks** — only flag where docs and code **contradict** (e.g., "doc says no tests" but a |
| 50 | + full suite exists; "doc says SQLite" but code uses Postgres). |
| 51 | +- **Next move** — what's demonstrably incomplete (stubs, TODOs, roadmap items absent from code). |
| 52 | + |
| 53 | +**2 · Compare.** For each of the six claims, classify against the docs: |
| 54 | +- `consistent` — the docs already match the code. Leave the text alone. |
| 55 | +- `drifted` — the docs are wrong or stale. Fix them. |
| 56 | +- `unverifiable` — the code can't confirm it (forward-looking or too vague). Leave the text alone. |
| 57 | +Cite evidence for each as `path:line`. |
| 58 | + |
| 59 | +**3 · Reconcile the docs.** For every `drifted` claim, edit the relevant doc so it matches reality — |
| 60 | +minimal, in-voice edits. Do not touch `consistent` or `unverifiable` text. Do not restructure or |
| 61 | +reformat beyond the specific correction. |
| 62 | + |
| 63 | +**4 · Write the reconciliation record.** Create/overwrite `DOC-RECONCILIATION.md` at the repo root, |
| 64 | +in this order: |
| 65 | +- **Why this file exists** (2–3 sentence preamble): state that it was generated by the |
| 66 | + `/doc-truth-up` documentation-reconciliation pass, which treats the code as read-only ground truth |
| 67 | + and edits only documentation so it reflects the repo's actual current state — it changed no code |
| 68 | + and ran no builds or tests. This explains the file's purpose to anyone who finds it later. |
| 69 | +- **Per-claim findings** — for each of the six claims: its status |
| 70 | + (`consistent` / `drifted` / `unverifiable`), the evidence basis (`verified-by-reading-code` or |
| 71 | + `unverifiable-because-<reason>`), and — for `drifted` claims — what you changed (file + a one-line |
| 72 | + before→after gist). |
| 73 | +- **Contradictions for manual review** — if you find real drift in a file you are NOT allowed to |
| 74 | + edit (anything outside `README.md` / `CLAUDE.md` / `AGENTS.md` / `DOC-RECONCILIATION.md` / `docs/`, |
| 75 | + e.g. `IMPLEMENTATION-ROADMAP.md`, `HANDOFF.md`, `STATUS.md`), do NOT edit that file. List it here |
| 76 | + with `path:line`, what is wrong, and the one-line fix a human should make. (Omit this section if |
| 77 | + there are none.) |
| 78 | +- **Footer** — a full **date + time stamp** (run `date "+%Y-%m-%d %H:%M:%S %Z"` and use its output), |
| 79 | + the branch name, and the HEAD sha you reconciled against (`git rev-parse HEAD`). |
| 80 | + |
| 81 | +This is the auditable sign-off the operator will batch-review. |
| 82 | + |
| 83 | +**5 · Commit on a branch.** `git checkout -b docs/truth-up-<YYYY-MM-DD>`; stage **only** doc files; |
| 84 | +commit with `docs: reconcile documentation to current code state`. Do **not** push. Do **not** |
| 85 | +commit to main/master. If any non-doc file shows up in `git status`, STOP, do not commit it, and |
| 86 | +report it in the summary instead. |
| 87 | + |
| 88 | +## Finish with a one-screen summary (for batch review) |
| 89 | + |
| 90 | +Print a block under ~15 lines so a reviewer scanning 100 of these can triage fast: |
| 91 | +- repo name · branch created · HEAD sha reconciled against · date+time stamp |
| 92 | +- per-claim one-word status (6 claims) |
| 93 | +- counts: `consistent` / `drifted-fixed` / `unverifiable` |
| 94 | +- doc files changed (paths) |
| 95 | +- any code↔doc contradictions worth a human's eye, in one line each |
| 96 | +- any non-doc files that unexpectedly appeared in `git status` (should be none) |
0 commit comments