# Nuke Docs

> Use when documentation must be checked against reality and repaired — "nuke docs", "is the README still true", "fix the docs", "docs drift" — README, docs/, setup guides, API examples. Every testable claim is verified by executing or tracing it; drifted docs are fixed, lying code is reported, never silently papered over.

- Skill: `b4r7x/nuke-docs` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add b4r7x/nuke-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/b4r7x/nuke-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: b4r7x (https://skillmd.com/u/b4r7x)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/b4r7x/nuke-docs

---


# 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

1. **Execute or trace, never eyeball.** A command claim is verified by running it (or `--help`/`--dry-run` when running is destructive); a path claim by `test -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.
2. **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.
3. **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`.
4. **Every verdict carries evidence** — the command output, the grep hit, the failing path — verbatim.
5. **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).
6. **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.