Rigor Docs Review

rigor-docs-review — user-facing docs review battery

Reviews Rigor's user-facing documentation — docs/manual/ (operational reference) and docs/handbook/ (type-model walkthrough) — from multiple expert lenses run as independent-context subagents, records each to a note, and applies only the necessary, axis-preserving fixes. This skill is the methodology freeze; the personas are re-pointed at whatever chapter/scope each run targets.

The full design rationale (what ports from the chibirigor book battery, what drops, what inverts, why L0 is new) is docs/notes/20260610-user-docs-review-battery-design.md. Read it once; do not restate it here.

The one load-bearing constraint: this is software documentation, not a book. Prose depth is not a virtue. A book battery rewards narrative richness and woven-in background; here the reference job is correctness and necessary clarity, and background thinness is not a defect. This is why L3 is inverted (a bloat detector, not a depth booster) and why no lens is allowed to recommend padding.

When to use / not

• Use: a manual/handbook chapter reached a stopping point; pre-release doc pass; "does the doc still match the implementation?"; the user says "review the docs / 査読して / 校閲して".
• Do NOT use: a single-line fix or an obvious typo — the lens-launch overhead is not worth it.

The five layers

Run order is L0 → L1 → L2 → L3 → L4 (機械 → 真 → 伝 → 簡 → 整). A full cycle runs at milestones; day-to-day, run only the layer in question (see "Which layer to run"). Parallel within a layer, sequential across — a later layer reads the text the earlier layer's fixes already corrected, because polishing an incorrect claim, or tidying prose a reader can't follow, is wasted work.

L0 機械 — the permanent gate (already built)

L0 is not an LLM lens — it is the spec/docs/ harness, run with make docs-check:

• handbook_snippets_spec.rb — extracts ```ruby blocks carrying assert_type / dump_type, runs them through the analyzer, fails on assert.type-mismatch (a prose claim the engine no longer produces).
• manual_drift_spec.rb — CLI subcommands (CLI::HANDLERS), config keys (Configuration::DEFAULTS), rule ids (CheckRules::ALL_RULES), and rule documentation_url anchors (ADR-65) cross-referenced against docs/manual/.
• link_integrity_spec.rb — every relative markdown link in the docs resolves.

The LLM battery runs only when L0 is green. Start every cycle with make docs-check; a mechanical failure is cheaper to fix than an LLM lens is to run, and a red L0 usually means a fix landed with a stale doc. (Known un-covered gap: CLI flag drift — flags lack a clean registry, so it stays an LLM L1 concern, not a mechanical check.)

The common contract (pass to EVERY lens)

• Do not break the docs' declared axes (both READMEs state them, so hand them over as the review criterion, don't invent new ones):
  • Reader: the handbook targets a Ruby programmer with no static-typing background; each "Coming from X" appendix declares its own reader.
  • Split: type model → handbook, operation → manual (both READMEs cross-declare it).
  • Handbook non-goals: readable cover-to-cover in a few hours; edge cases belong in the spec corpus; it does not teach Ruby; plugin authoring belongs in examples/.
  • Terminology: bare "interface" is banned — first use is always structural interface or RBS interface.
  • Spec binds: if the handbook contradicts the spec corpus on analyzer behaviour, the handbook is what's wrong.
• Severity-label every finding (ERROR / MISLEADING / FRICTION / nitpick). A few nitpicks at the end, not sprinkled.
• This is software docs, not a book. No lens may recommend adding prose for depth's sake, "more rigour," or narrative flourish. Reference density (tables, annotated code) is the goal.
• Read the shipping docs only. Do not read internal docs/notes/ review memos as source.
• Output: the subagent's final message is a per-lens table (quoted location / problem / proposed fix) + a short overall verdict, and it writes the same to its note (below).

L1 真 — semantic fidelity

• Persona: a reviewer who reads both Rigor's implementation and the docs and checks that every claim the L0 harness can't mechanically verify is true — cache-invalidation conditions, diagnostic firing conditions, severity-profile mappings ("balanced maps X to :info"), plugin behaviour. Handbook claims are checked against the spec corpus (spec binds); manual claims against the implementation + actual CLI behaviour. Has read access to lib/rigor/ and may run the CLI (read-only). An intentional simplification is not a fidelity gap — flag only accidental inaccuracy (the doc asserts ¬X where the engine does X). Distinguish the two in the report.
• Type-theory sub-lens (only for appendix-type-theory.md and the cross-checker appendices): a reviewer at TAPL-teaching level checks the formal claims; honest simplifications are not faulted.
• Note: docs/notes/YYYYMMDD-docs-review-fidelity.md.