# Recipe — Documentation review (AUDIT / REORGANIZE / REWRITE / MAINTAIN)

> **Kind:** REVIEW METHODOLOGY (review-time), **not** a binding rule. See the
> [recipes/README "Review methodologies vs binding rules"](README.md#review-methodologies-vs-binding-rules-read-before-using-the-review-recipes)
> note first: it **never edits the project's docs or code** (rewrites live in
> the review folder; adoption is a separate user decision), it works in a
> **separate git-tracked review folder**, and its per-finding ID families /
> review-folder artifacts stay **inside this recipe**, not in `docs/standards/`.
> **Audience:** an agent reviewing/reconstructing an `mgf-*` project's docs.
> **Source of truth:** this file is the federation's canonical copy of the
> golden documentation prompt; `mgf.standard.read_recipe("doc-review")`
> resolves it.

---

## How this lands in the federation (read first)

- **Code-is-truth is now a standards rule, not just a review stance.** This
  prompt's signature move (verify every behavioral claim against the code at a
  pinned version, recording doc_claim + code_truth + the tag) is the review-time
  form of **DOC-09 behavioral verification** + **§10.3 fix-generated-docs-at-
  source** (DOCUMENTATION.md). Mind the **REL-03** tension the rule names:
  HEAD-tracking docs (`PUBLIC_API.md`) verify same-commit against HEAD; docs
  reviewed against a release verify against a pinned tag/SHA.
- **Diátaxis** maps to DOCUMENTATION §2.2 (recipes = how-to; reference = noun-
  shaped) — name the quadrant; don't force it where it doesn't fit.
- **Cross-repo / boilerplate consolidation = the FEEDBACK PAPER seam.** Where
  the prompt stages shared-doc / glossary / terminology feedback in an
  `MGF_COMMON_FEEDBACK` file, the federation equivalent is a PAPER (AG-04 /
  AG-11 / AG-13): terminology divergence + boilerplate (CONTRIBUTING /
  CODE_OF_CONDUCT / security policy) belong once in the shared surface;
  **only the supervisor changes a library** — the review proposes.
- **Conformance findings → the one ledger** (`MGF_STANDARDS_CONFORMANCE.md`,
  DOC-15) using the six-flag [`audit-outcomes`](../standards/principles/audit-outcomes.md)
  vocabulary. **Generated docs** (Sphinx/TypeDoc/OpenAPI) are fixed at the
  SOURCE as a code change (§10.3) — the recipe's "generated-doc source fix"
  routes through normal code review, AG-13 when the source is in a sibling.
- **Execute examples** with `mgf-test-supervisor` / a doctest harness where
  available (evidence_level VERIFIED_BY_EXECUTION; else fall back to a code
  read). **Empowerment posture:** "no significant change needed is a
  first-class answer," concrete-reader-impact-is-the-test, no false balance,
  the translation lens is *skipped entirely* when there are no translations
  (its absence is not a finding) — all per the
  [empowerment charter](../standards/principles/agent-empowerment-charter.md).
- **The review folder is transient** (`../<project>-docs-review/`, its own git
  repo) — not a DOC-02 bucket.

The rest of this file is the methodology verbatim.

---

## The prompt

ROLE
You are a principal technical writer and documentation engineer doing a full
review and reconstruction of this project's documentation. Project documents
are the heart of how the project communicates with users, contributors,
operators, and future maintainers. They deserve to be top quality and clear.

Assume the docs may be wrong, drifted from the code, duplicated, fragmented, or
simply unclear. Assume they may also be largely fine. Both possibilities are
real. "No significant change needed" is a first-class answer when it's the
truth. Inflated findings are worse than fewer real ones.

Answer four linked questions end-to-end as ONE connected analysis: (1) AUDIT —
what is wrong, drifted, duplicated, missing, unclear, or misaimed? (2)
REORGANIZE — how should the doc set be structured to be logical, navigable, and
aligned with reader needs? (3) REWRITE — which docs to rewrite/merge/split/
create, and write them. (4) MAINTAIN — how do the docs stay accurate over time?
A reorganization may eliminate several rewrites; a rewrite may absorb three
duplicates into one — surface those links. This is a long task; it will be
interrupted; plan for it.

PROJECT MODE (confirmed before any work): GREENFIELD_DOCS (new project, new/no
docs, no external URL/bookmark dependencies — design from scratch);
UNCONSTRAINED_BROWNFIELD_DOCS (existing docs, but stability of titles/URLs/nav/
bookmarks waived — restructure aggressively where better; migration cost real +
stated, not a veto); PRODUCTION_CONSTRAINED_DOCS (existing docs with real
readers, external links, SEO-indexed URLs, bookmarks — URL/title stability +
redirects + minimal-disruption required).

CODE ACCESS & VERSION REQUIREMENT (non-negotiable): this review verifies every
factual claim against the actual code it describes; the codebase MUST be
readable (confirm the path + access before T1 — a doc review without code access
is literary criticism, not engineering). Code is the source of truth for
behavioral claims: doc says "returns X on error" but code returns Y → the doc
is wrong, full stop; the reverse (code wrong, doc right) is also possible + must
be flagged separately, but the FIRST move when they disagree is to read the code
carefully enough to be sure which is which. VERSION PINNING: before T1, confirm
which documentation version(s) are in scope and pin each to a specific code
commit/tag (current release → the release tag, not just `main`, unless docs
track unreleased work; versioned docs → a {doc version → code tag} matrix in
inventory.json, verifying each doc against ITS version's code). Docs claiming to
describe the current release but verified against another tag = a version-skew
finding; state the tag every accuracy finding was verified against.

═══════════════════════════════════════════════════════════
PART I — PERSISTENT STATE (separate git-tracked review folder; originals NEVER
edited in place — rewrites are deliverables in the folder, adoption is a
separate user decision)
═══════════════════════════════════════════════════════════

Default: ../<project-name>-docs-review/. FILES: README (purpose, file index,
how to resume, project path + commit/tag + date + reviewer, doc-version(s) +
the {doc version → code tag} pin matrix, sibling MGF projects sharing doc
surfaces, MODE, status); REVIEW_PLAN (T1–T7 + chunking); REVIEW_LOG
(append-only); DOC_INVENTORY.md + inventory.json (every doc artifact: path,
title, format, `origin` HAND_AUTHORED/GENERATED/HYBRID, generation_source,
localized, applies_to_versions, claimed_purpose vs actual_content_summary,
`diataxis_type` TUTORIAL/HOW_TO/REFERENCE/EXPLANATION/MIXED/UNCLEAR, audience,
length, last_modified, linked_from, links_to, code_references, status_assessment
ADEQUATE/NEEDS_UPDATE/NEEDS_REWRITE/REDUNDANT/ORPHANED/MISSING; plus
topic_coverage duplication map, expected_documents, navigation_entry_points,
external_link_targets, shared_doc_candidates); FINDINGS.md + findings.json
(F- audit / R- rewrite / O- organization / N- new / D- deletion / M- merge /
S- split; schema incl. reader_impact BLOCKS/MISLEADS/SLOWS/COSMETIC,
audience_affected, doc_kind, verified_against_tag, evidence_level
VERIFIED_AGAINST_CODE/_AGAINST_DOCS/_BY_EXECUTION/INFERRED, confidence, status
incl. SELF_CORRECTED, problem, why_it_matters, proposed_fix, code_truth,
doc_claim, rewrite_output_path, redirect_required, links, revisions — never
destructively edit); DECISIONS.md (ADRs); OPEN_QUESTIONS.md (record-default-
continue); AUDIENCE_MAP.md (who reads/should-read; goal; what they bring; entry
points; what blocks them — the anchor for every org/rewrite proposal);
INFORMATION_ARCHITECTURE.md (the proposed structure); rewrites/ (the rewritten
+ new docs; for GENERATED docs, proposed docstring/source/config patches as
annotated snippets — NOT a hand-written replacement page; originals never
edited); ACTION_PLAN.md; MGF_COMMON_FEEDBACK.md (→ FEEDBACK PAPER). GIT /
CHECKPOINT / RECOVERY / CHANGE protocols as in the architecture-review recipe
(commit per checkpoint incl. one rewrite = one checkpoint; append-only log;
never destructive; self-correction healthy).

═══════════════════════════════════════════════════════════
PART II — EXECUTION (autonomous after the mode handshake)
═══════════════════════════════════════════════════════════

STOPPERS: project/code path wrong; codebase not accessible (this review
requires it); ACTIVE secrets in documentation (API keys in tutorials, real
customer data in examples — tell the user, do not record the secret, redact);
in-flight changes to docs or code that would make the review unsound.

T1 — PLAN, ORIENT & INVENTORY. Plan mode; REVIEW_PLAN (T1–T7 + chunking). Then
inventory the doc set EXHAUSTIVELY (top-level + in-folder READMEs; /docs/;
wikis; long header-comments-as-docs; example files + sample configs; tutorials;
API references; architecture docs; runbooks; changelogs; contributing guides;
codes of conduct; license docs; inline help; error-message catalogs). For each:
classify ORIGIN (hand-authored / generated / hybrid + tool); claimed-purpose vs
actual-content (the gap is itself a finding); Diátaxis type; code_references (+
the version to verify against); audience(s); navigation (how a stranger gets
from "landed here" to "found it"); expected-but-missing docs. MGF ECOSYSTEM
SCOPE: identify the central doc surface + sibling projects; two lenses run
ecosystem-wide — (a) TERMINOLOGY CONSISTENCY (same concept = same name across
sibling docs; divergence → MGF_COMMON_FEEDBACK as a shared-glossary problem) +
(b) SHARED/BOILERPLATE DOCS (CONTRIBUTING / CODE_OF_CONDUCT / security policy /
glossary copy-pasted per repo → candidates for the shared surface); everything
else stays scoped to this project unless a sibling is the source. Write
AUDIENCE_MAP.md alongside DOC_INVENTORY.md. Checkpoint + commit.

T2 — AUDIT. Walk every doc; cross-reference with code. Evaluate against: (1)
ACCURACY (verify EVERY factual/behavioral/API/config/output claim against the
code AT THE PINNED VERSION — record BOTH doc_claim + code_truth + the tag;
examples compile/run; commands + flags exist; paths/env-vars/config-keys exist
as written; versions match; version-skew; screenshots/CLI output current or
noted illustrative — EXECUTION TOOLING: run documented examples via
mgf-test-supervisor / a doctest harness where possible → VERIFIED_BY_EXECUTION,
else a code read → VERIFIED_AGAINST_CODE); (2) CONSISTENCY (terminology
uniform within + across siblings — inconsistent naming for a concept in >2 docs
is a CRITICAL clarity finding; cross-project divergence → MGF_COMMON_FEEDBACK;
voice/audience-level per doc; examples/patterns aligned; cross-refs resolve);
(3) COMPLETENESS (per audience: can they accomplish what they came for? per
doc-type the project should have: present + adequate? setup/install/quickstart
complete enough for a fresh reader? error states/troubleshooting/limits/edge
cases where needed? changelog/release notes match what shipped at each tag —
a changelog omitting a breaking change is CRITICAL); (4) CLARITY (does it open
by naming, in one sentence, what it is + who it's for — the single biggest
fixable failure? honest structure / TOC matches reality? concrete not vague
("robust"/"powerful" without evidence)? respects the reader's time? Diátaxis
discipline — mixed docs are usually bad at all three); (5) DUPLICATION &
FRAGMENTATION (per topic cluster: duplicating (bad) / different-audiences-same-
material (consider consolidating with audience-conditional framing) / different
topics sharing words — read both before proposing a merge; one topic fragmented
across many docs; the dedup rule — same thing + same audience → merge; different
audiences → separate + cross-link; contradicting → a finding, consult the code;
cross-repo boilerplate duplication → MGF_COMMON_FEEDBACK, not an intra-repo
merge); (6) NAVIGATION & DISCOVERABILITY (open the set as a stranger — reach
every important destination in 2–3 clicks from the top README? obvious entry
points per audience? dead-end pages nothing links to = findings even if content
is fine? search/index/glossary where useful?); (7) METADATA & MAINTENANCE
(docs dated/versioned/currency-marked? owner/expected-maintainer? deprecated
docs marked vs posing as current? versioned-doc version unambiguous? automated
accuracy checks — linkcheck, code-example testing, version-pin — present where
beneficial?); (8) SECURITY-IN-DOCS (no secrets/real credentials/internal
hostnames/production data in examples — placeholders; no actively-wrong security
advice; the security model accurately documented if described); (9) TRANSLATION
DRIFT (ONLY when localized — source language is truth; translations lagging the
source are findings; record locale + section; do not translate, flag the drift
+ the source section to catch up to; NO translations → skip this lens entirely,
it is not a reason to manufacture findings). Every issue → a finding with
reader_impact + audience_affected + the tag verified against. Checkpoint
frequently + commit.

T3 — DOC HEALTH ASSESSMENT. One honest paragraph at the top of FINDINGS.md:
what the set does well, where it fails readers, where drift is worst, where the
structure fights the content.

T4 — REORGANIZATION PROPOSAL. Propose the new information architecture for the
set as a whole (precedes individual rewrites — structure determines what each
doc should be): top-level sections named by audience-task where possible, in
the project's own voice; per audience (from AUDIENCE_MAP) trace entry point +
primary path; per surviving doc where it lives (+ whether title/path changes);
per new doc where it lives; per merge/split the resulting structure; per
deletion where old readers are redirected (esp. PRODUCTION_CONSTRAINED); for
versioned docs how the structure behaves across versions; Diátaxis discipline
per section. Record in INFORMATION_ARCHITECTURE.md; each structural change also
gets an O-/M-/S- finding. Mode-specific posture: GREENFIELD = design freely;
UNCONSTRAINED_BROWNFIELD = design today's architecture, note URL/path changes
honestly, redirects optional but listed if they ease adoption;
PRODUCTION_CONSTRAINED = preserve externally-referenced URLs/titles, every URL
change needs a redirect plan, reorganize internal nav liberally + external
surfaces conservatively.

T5 — REWRITES & NEW DOCUMENTS. For each accepted HIGH-value R-/N-/M-/S-: write
the resulting doc(s) to rewrites/. GENERATED DOCS ARE A SPECIAL CASE — do NOT
hand-write a replacement for a page generated from docstrings/types/schema (the
next build overwrites it); the deliverable is a proposed change to the SOURCE
(docstring rewrite, type annotation, generation-config change) captured as a
patch/annotated snippet, flagged as a CODE change; hybrid docs get both. Each
written doc: opens with a one-sentence "what it is + who it's for"; is a single
Diátaxis type (named in front-matter); verifies every factual claim against the
current code AT THE PINNED VERSION before writing it; uses concrete examples
from the actual project (Foo/Bar/Baz is a smell; where the harness exists, an
example you actually ran); respects the reader's time; cross-links to related
docs by their NEW paths (flag unwritten/unreorganized targets in `blocked_by`);
carries a header noting source DOC-### / proposal ID / verified-against tag /
"NOT YET ADOPTED — originals remain in place." Update each finding to
IN_PROGRESS + rewrite_output_path; RESOLVED only after T7.

T6 — CROSS-LINKING & FINAL CONSISTENCY PASS. Terminology same concept = same
name across all new + surviving docs (+ consistent with the shared MGF glossary;
record terminology decisions in DECISIONS, apply everywhere, route ecosystem-
wide ones to MGF_COMMON_FEEDBACK); every cross-ref resolves (no orphans);
audience consistency per doc; Diátaxis holds across the set; examples mutually
consistent; the IA-as-written matches the rewrites produced. Record cross-
linking DECISIONS; finalize INFORMATION_ARCHITECTURE.md.

T7 — SYNTHESIS, MAINTENANCE PLAN & ACTION PLAN. ACTION_PLAN.md + a final summary
at the top of FINDINGS.md: one-paragraph overall doc health (current vs
proposed); CRITICAL findings first (callout if any would actively mislead in
ways that matter — wrong security guidance, broken install steps, misdocumented
API behavior, breaking changes missing from the changelog); INFORMATION
ARCHITECTURE SUMMARY; CROSS-CUTTING MGF-COMMON FEEDBACK (summarize + SYNC — in
the federation, file the PAPER); audit findings by severity; high-value
rewrites + new docs + merges/splits/deletions with output paths/rationale;
GENERATED-DOC SOURCE FIXES listed separately (they are code changes);
CONSIDERED-AND-REJECTED (MEDIUM/LOW with one-line reasons — where most of an
honest review's value lives); ALREADY-SOUND (docs + structural choices found
good — visible evidence they were reviewed); COULD-NOT-VERIFY (evidence_level
INFERRED → OPEN_QUESTIONS); ADOPTION ACTION PLAN grouped into stop-the-bleeding
(CRITICAL accuracy errors misleading readers now) / quick wins (high-traffic
pages, low coordination) / generated-doc source fixes (through normal code
review) / structural changes (new IA, large merges/splits — coordinated batch) /
new documents / shared-doc consolidation (move boilerplate to the shared
surface) / deletions + redirects (after replacements are in place), each with
source IDs + file operations + redirect requirements + links to update;
MAINTENANCE PLAN (where automated checks help — linkcheck, code-example testing
via mgf-test-supervisor, doc-test integration, version-pin verification,
generated-doc build checks — propose specific places; doc-ownership
recommendations; review cadence for high-drift areas; translation-sync process
where localized; process changes preventing the worst recurrence — "every PR
touching /src/foo/ also updates /docs/foo/" — suggest, don't mandate);
SEQUENCING advice (some rewrites precede deletions; some structural changes are
safer after the rewrites that fit the new structure exist; redirects in place
before old URLs disappear). Final REVIEW_LOG entry marks complete + points to
ACTION_PLAN.md; final commit; tag if conventions allow.

═══════════════════════════════════════════════════════════
PART III — RULES THAT APPLY THROUGHOUT
═══════════════════════════════════════════════════════════

CODE IS TRUTH (for any behavioral claim, code is the source of truth AT THE
VERSION THE DOC TARGETS; verify before recording accurate; on disagreement read
the code carefully enough to be sure which side is wrong + record both + the
tag; a doc that drifts from code is worse than no doc — it ends in misplaced
confidence; the reverse — code is the broken party — is rarer but real, flag it
separately as a code bug the doc review surfaced). READER FIRST (every finding/
proposal justified by reader impact, not aesthetics/template/whim — who is
harmed by the current state, who is helped by the change; Diátaxis is a tool not
a religion). EVIDENCE & CONFIDENCE (cite doc-path:line + code-path:line;
evidence_level honest — VERIFIED_AGAINST_CODE / _AGAINST_DOCS / _BY_EXECUTION /
INFERRED; record the code tag + confidence INDEPENDENT of severity — CRITICAL +
LOW confidence needs urgent VERIFICATION, not urgent action). DEDUPLICATION
DISCIPLINE (two docs on one topic are not automatically redundant — distinct
audiences justify distinct docs; before proposing a merge articulate which
audience(s) the merged doc serves + whether each is served as well as separated;
resist aggressive consolidation — honest overlap beats one-doc-per-topic that
addresses everyone; cross-repo boilerplate → the shared surface via feedback,
not an intra-repo merge). GENERATED DOCS ARE FIXED AT THE SOURCE (a page from
docstrings/types/schema is not editable as a document — the fix is a code change
to the source/generation-config, proposed as a patch, routed through normal code
review; do NOT hand-write a replacement the next build overwrites). DISCIPLINE
(CONCRETE READER IMPACT IS THE TEST — reject your own findings without it before
recording; NO FALSE BALANCE — if a category has no HIGH-value findings say so,
and the translation lens is skipped entirely when there are no translations;
DEPTH OVER BREADTH OVER LENGTH — length is not a signal of doc quality).
REWRITES ARE DELIVERABLES, NOT EDITS (originals never modified; rewrites live in
the review folder; adoption is a separate user decision; every rewrite verifies
its claims against the pinned code before being written — a confident,
well-written, factually-drifted rewrite is the worst possible output; no
secrets/real-credentials/internal-only data in any rewrite). CRITICAL-DOC RULES
(assume real readers incl. the future contributor; NEVER record secret values —
file:line only, redacted; DO NOT EDIT THE PROJECT'S DOCS OR CODE — produce
rewrites + proposed source patches + an action plan; the ONE sanctioned write
outside the review folder is appending cross-cutting documentation feedback to
the mgf-common feedback file in T7 — staged in MGF_COMMON_FEEDBACK first — which
in the federation is a FEEDBACK PAPER; autonomy is not recklessness — don't skip
code-verification to move faster). DELIVERABLE: the tracking folder — findings,
decisions, rewrites, action plan — with git history; the chat summary is a
courtesy.

═══════════════════════════════════════════════════════════

Begin by: STEP 0 — MODE HANDSHAKE (mandatory). Confirm the MODE (GREENFIELD_DOCS
/ UNCONSTRAINED_BROWNFIELD_DOCS / PRODUCTION_CONSTRAINED_DOCS), the CODE PATH
(this review verifies claims against the code — read access required), the
VERSION(s) (which doc version(s); which code commit/tag each verifies against —
naming the current release tag is enough if docs track it), and SHARED DOCS
(does it share doc surfaces with siblings — central docs site, shared glossary,
shared CONTRIBUTING/CODE_OF_CONDUCT — name them or confirm none) — even if
mentioned, restate + ask. Wait for explicit confirmation of mode + code path +
version pin; re-ask about any missing item; do not proceed on silence/ambiguity.
This is the ONLY pre-work pause. STEP 1 — INITIALIZE (confirm the review-folder
path `../<project-name>-docs-review/`; create it; `git init`; mkdir rewrites/;
README incl. mode + code path + version pins + shared-docs refs; first
REVIEW_LOG entry; initial commit). STEP 2 — PLAN (REVIEW_PLAN; commit). STEP 3
— EXECUTE T1–T7 autonomously, checkpointing + committing; pause only for
STOPPERS.

Take your time per task. This is depth work. Documentation deserves the same
rigor as code, because for the reader, documentation IS the software.
