vlasovsmm/claude-docs-standard/documentation-full-refresh

Full Documentation Refresh

Verify every factual claim in the project's documentation against the actual code, fix confirmed drift, and fill gaps. Two stances that don't contradict: edits are surgical — replace the wrong sentence, leave correct prose alone, never rewrite a whole doc. Verification is skeptical — assume the docs have already drifted from the code, and prove each claim by reading the source. CONFIRMED is an outcome you earn by reading deeply, not the starting position; a pass that confirms almost everything is a pass that didn't read deeply enough.

This is heavier than documentation-update (which sweeps after a single known change). Use this when the docs may have drifted broadly and need a from-scratch re-verification of the whole project.

Documentation in scope

Discover the actual set in THIS project — don't assume specific filenames:

• every *.md under .claude/skills/project-knowledge/references/ (the count and names

vary per project), plus that skill's SKILL.md

• root CLAUDE.md and README.md
• every *.env.example (root and any subdir, e.g. backend/, dashboard/) and any

config.*.example the project ships

ls these locations first and treat what you find as the scope, not this list.

Out of scope: the .claude/ methodology files (skills, agents, commands other than the project-knowledge skill above) — they describe the workflow system, not this project.

Phase 0: Prepare

1. If on the default branch, create a branch: git checkout -b docs/full-refresh.
2. Run git status and note which files are already modified or untracked before

you start. The final commit stages only the docs you change, by explicit path, so unrelated work-in-progress stays out of the commit.

1. Build the drift signal from git history — the strongest hint of where the docs have

fallen behind. Find the last broad docs-refresh commit (git log --oneline -- <docs dir>), then list what changed in the code since: git log --since=<that date> --name-only --pretty=format: -- <code dirs> | sort | uniq -c | sort -rn | head -40, and skim recent feat/fix commit subjects. The most-changed files per area plus those subjects are the per-area "drift hints" you hand each agent in Phase 1.

Checkpoint: Branch created; pre-existing dirty files noted; git drift signal captured.

Phase 1: Verify (parallel agents)

Split the codebase into verification areas and spawn one read-only general-purpose agent per area. Not `Explore` — Explore reads excerpts, and excerpt-reading is exactly what makes this pass shallow: it confirms a few visible lines and misses the rest of a 30–60 KB module. Each area agent must read its assigned source files IN FULL.

Each agent works code-first and in both directions:

1. First write the ground truth — read the assigned source top to bottom and list

what the code ACTUALLY does now (every route, public function/signature, status value, config key, enum).

1. Then check doc→code: is each claim in the owned doc sections still true?
2. Then check code→doc: what does the code do that the docs never mention — new

endpoints, flows, statuses, config keys, renamed/removed behavior? This reverse direction is what a confirm-by-default pass misses; hunt it deliberately.

Stance: assume drift. Classify each finding DRIFT (doc says X, code does Y), UNDOCUMENTED (code does Z, doc silent), STALE (doc describes removed/old behavior), or CONFIRMED (verified true — record these too, so coverage is provable). Hand each agent its area's git drift-hints from Phase 0.

Build the split, each area's doc-section ownership, and the agent prompt from the area map in verification-areas.md. Build that split from THIS project's real structure each run — the file's example is illustrative, not a fixed map.

Agents run in parallel — they are read-only, so this is safe. Each writes its findings to work/doc-refresh/findings-<area>.md and returns a short summary; if the harness blocks the agent's file write, it returns the full findings in its final message — capture that.

Checkpoint: Every doc section is owned by exactly one agent; each agent read its sources in full and reported both directions; all findings captured.

Phase 2: Consolidate

1. Read every findings report.
2. Merge into one change set, grouped by target doc file.
3. Resolve cross-doc conflicts to one source of truth — a fact living in three docs

gets one agreed value; the code-owning agent's value wins.

1. Classify each change: CORRECTION (DRIFT), ADDITION (UNDOCUMENTED — code behavior the

docs omit), DELETION (STALE), NO-OP (CONFIRMED). Give DELETIONs extra scrutiny in Phase 4 — removing a true detail is worse than leaving it.

1. **Read the code yourself for anything low-confidence, ambiguous, OR where two agents

disagree.** Agent conflict is a signal, not noise — settle it by reading the source, not by averaging. (Real case: two agents split on whether a "dual-read" decrypt applied to a given table; the truth was layer-specific and only reading the read path resolved it.) Re-read the source behind any high-impact claim before rewriting prose around it.

Checkpoint: One consolidated change set; conflicts resolved by reading code; deletions flagged.

Phase 3: Apply edits

Before touching any .md, determine its GENRE with the documentation-writing skill and open that genre's guide in its references/: law, reference, instruction, analysis, agent. Do not invent your own structure — the genre guide sets it.

Edit one file at a time — the reference docs cross-reference each other, so concurrent edits risk inconsistent links. Order: project.md first (other docs lean on it), then the other references/*.md (deployment, patterns, architecture, and any others this project has), then the project-knowledge SKILL.md, then README.md, CLAUDE.md, and the *.env.example files last.

Rules:

• Replace the specific wrong sentence or line; leave correct prose untouched.
• New sections match the house style of the doc — operational prose, scannable,

no code blocks duplicating source, every number verified against code.

• Every edit traces to a Phase 2 change-set entry. No "while I'm here" changes.

Checkpoint: All change-set entries applied; correct prose untouched.

Phase 4: Review

1. Spawn the documentation-reviewer agent on the changed docs (parallel,

read-only). It judges doc quality: concise, operational, no bloat, no duplication.

1. Cross-document consistency pass: grep every corrected value across all docs —

expect zero stale hits; counts and names identical everywhere; cross-references between docs still resolve.

1. Apply review fixes, up to two rounds.

Checkpoint: Reviewer verdict addressed; consistency grep is clean.

Phase 5: Verify end-to-end

1. ls every path in any updated file map — confirm each one exists.
2. Spot-check 8-10 of the riskiest corrected claims against file:line in the code.
3. git diff the in-scope docs only — confirm no methodology file and no source

file slipped into the change set.

Checkpoint: All file-map paths exist; spot-checks pass; diff is docs-only.

Phase 6: Commit

Stage the changed docs by explicit path — not git add -A, which would sweep up unrelated work-in-progress. One commit:

git add <each changed doc by full path>
git commit -m "docs: full verification refresh — <one-line summary of fixes>"

Then either delete the work/doc-refresh/ scratch folder or keep it as an audit trail of what was verified — the per-area findings are useful evidence if the depth of the pass is ever questioned. This is a docs-only change — no deploy.

Checkpoint: Only in-scope docs committed; scratch folder removed or kept as audit trail.

Final Check

• [ ] Phases 0-6 completed, each with its checkpoint
• [ ] Each area agent read its sources in full (not excerpts) and reported BOTH

directions — doc→code and code→doc

• [ ] Every doc claim verified against code, not assumed — CONFIRMED claims recorded too
• [ ] DRIFT fixed, UNDOCUMENTED code behavior added, STALE detail removed, correct prose left alone
• [ ] Agent conflicts resolved by reading the source, not by averaging
• [ ] documentation-reviewer run and findings addressed
• [ ] Consistency grep returns zero stale values
• [ ] Commit contains only in-scope docs, staged by explicit path