Documentation Full Refresh

---
name: documentation-full-refresh
description: |
  Large-scale verification refresh of the whole project's documentation: read
  every doc and the actual code in full, check each claim against code AND surface
  code behavior the docs omit, fix drift, fill gaps. Multi-agent verification split
  by codebase area (code-first, both directions), then surgical edits, review, and
  a scoped commit.

  Use when: "обнови всю документацию", "полное обновление документации",
  "масштабное обновление документации", "апдейт документейшн фулл проджект",
  "проверь всю документацию против кода", "большой рефактор документации",
  "full documentation refresh", "verify all docs against code"

  Not for: a quick sweep after one known code change — use the
  documentation-update skill instead.
---

# 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.
3. 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).
2. Then check **doc→code**: is each claim in the owned doc sections still true?
3. 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](references/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.
4. 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.
5. **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.
2. 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.
3. 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