b4r7x Nuke Docs
The hygiene lens flags "docs that lie"; this skill convicts and repairs them (map: references/family-map.md — lying code routes to nuke-debug, never edited here). Docs rot because nobody executes them: the README's install command references a script deleted in March, the env-var table misses half the variables the code reads. The protocol is mechanical — extract every testable claim, verify each by running or tracing it, fix the doc — which is exactly why cheap workers with a schema do it well.
Arguments
[mode] — light (default) | full | plan (preflight, print, STOP).
[scope] — a docs path (README.md, docs/) | default: every doc file in the repo (README*, docs/, CONTRIBUTING, code-adjacent *.md guides; changelogs and ADRs are historical record — excluded).
--ask — pause at the preflight plan for confirmation; default is no gate — the plan prints and the run starts (references/preflight.md).
Modes
Tier vocabulary and platform mechanics: references/model-tiers.md.
| light (default) | full | |
|---|---|---|
| Claim extractors | clerk | worker |
| Verifiers | worker | worker |
| Claim types verified | commands, paths, env vars, scripts, ports | + API examples compiled/run, config samples parsed, links resolved |
| Fixers | worker | worker |
| Validator — one tier above fixers | session | top |
| Fix cycles | cap 2 | cap 3 |
Mandates
- Execute or trace, never eyeball. A command claim is verified by running it (or
--help/--dry-runwhen running is destructive); a path claim bytest -f; an env-var claim by grepping the code that reads it; an API example by compiling/running it (full). "Looks right" is not a verdict. - Fix the doc, never the code. A doc-code conflict where the CODE looks wrong becomes a reported finding with a nuke-debug or nuke-audit recommendation — this skill's writes touch documentation files only.
- Destructive commands are never executed. Install-to-system, deploy, publish, delete claims are verified by tracing (script exists, flags valid per --help) and marked
traced, not executed. - Every verdict carries evidence — the command output, the grep hit, the failing path — verbatim.
- Don't rewrite voice. This skill fixes truth, not style; wording changes beyond the lying span are out of scope (the user has humanizer-class skills for style).
- No
git add/git commit/git stash. Working tree left for review.
Artifacts
run_dir = .nuke/<YYYY-MM-DD>-<HHmmss>-docs-<slug>/ — fresh per run; on collision append -2, -3, ….
| File | Role |
|---|---|
plan.md |
Doc inventory, claim-type counts, wave, tiers |
claims.md |
Every C-### claim: quote, location, type, verdict, evidence |
report.md |
Scorecard: true / drifted-fixed / code-suspect / unverifiable |
Pipeline
Phase 0 preflight (plan → apply) → Phase 1 claim extraction → Phase 2 verification wave → Phase 3 fix + validate (cap 2/3) → Phase 4 report (STOP)
Phase 0 — Preflight
Read references/preflight.md and follow its plan-then-apply gate. Docs specifics: resolve the doc inventory (files + estimated claim count from a quick scan); resolve the repo's gates table (references/stack-adapters.md) — doc claims about tests/builds are verified against it. Print the plan block and apply it (gate only with --ask).
Phase 1 — Claim extraction
Extractors (≤5 doc files each) pull every testable claim into claims.md as C-###: the verbatim quoted span, file:line, and type — command | path | env-var | port/url | script | api-example | config-sample | link | behavior (doc describes what code does). Prose opinions, marketing, and philosophy are not claims — skipped, not judged.
Phase 2 — Verification wave
Verifiers (claims batched by type, ≤15 each) verdict every claim per Mandates 1 and 3: true · drifted (doc wrong, reality clear — carries the correct value with evidence) · code-suspect (doc plausibly right, code looks wrong — Mandate 2) · unverifiable (needs credentials/external service — reason stated). Behavior claims are verified by tracing the cited feature to code with file:line + quote, exactly like a finding trace.
Phase 3 — Fix + validate
Fixers rewrite every drifted span — minimal edit, the lying value corrected, voice untouched (Mandate 5). A fresh validator one tier above re-verifies each fixed claim the same way it was verified originally and hunts new lies the edits introduced. Cap per mode; cap hit → honest open list.
Phase 4 — Report (STOP)
Scorecard: claims by verdict; every code-suspect listed with its evidence and the recommended follow-up (nuke-debug for one behavior, nuke-audit when drift is systemic); every unverifiable with what would unlock it. Run stats + artifact paths; calibration line appended to .nuke/calibration.log (format in references/preflight.md). STOP — never start fixing code.