docs: audit everything, consolidate 18 skills into 2, resync the mdBook

[taddyb]

Audits every .claude/skills/ package (9,371 lines), all 32 docs/ files, README.md, .claude/references/, and CLAUDE.md — then acts on what it found. Full report: docs/2026-07-30-docs-and-skills-audit.md.

Method: five parallel auditors, each required to verify every concrete claim against the repo rather than assess plausibility. Every path ls'd, every config key checked against src/config.rs, every cargo test --test X checked against tests/, every CLI flag grepped, every #[test] counted, every number cross-checked against the dated findings doc that owns it. Where docs disagreed, metrics were recomputed from .ddrs/runs/*/ rather than picking a side.

What was wrong

A config key that does not exist. kan_head.disaggregation.use_precip was documented in CLAUDE.md, src/config.rs's own comment, and config/sources/conus-hourly.yaml. It was removed in 334f0fe. Because CLAUDE.md is in context on every turn, this propagated faster than any one doc could be corrected.

Two documented entry-point commands hard-error. ddrs init exits 2; ddrs run --workflow eval demands a --from-run flag that exists nowhere in src/. Both were the documented first step in docs/setup.md and README.

The baseline number came from the wrong network. 0.689 / 0.723 appeared in 13 of 18 skills as the CONUS bar. It is a global MERIT number over 5,224 gauges; the CONUS bar is 0.6781 / 0.7172 on 2,365. That makes the widely-quoted +0.026 delta a cross-population subtraction (correct: +0.037). A separate population error in the 07-07/07-16 findings docs flips a verdict — hourly-lstm's "+0.022 NSE gain from routing" becomes −0.051 when the baseline is scored on the same gauges.

One doc invalidated six skills at once. The 2026-07-06 leakance NO-GO retired the "Phase B is required" framing; all six research skills still asserted it, three still carried executable instructions for the closed campaign. That duplication is why the staleness was uniform.

Gates that cannot fail. cargo test --test sp8_gradcheck -- --ignored runs zero tests and exits 0 (nothing in that file is #[ignore]). Same for --lib training::checkpoint and --lib data::store::zarr::tests::…. mc_routes_linear_chain never existed. Test counts were also wrong — 16 not 8, 8 not 6.

What changed

Skills: 18 → 2. 9,371 → 2,359 lines.

• ddrs-dev — build/code/run/debug, with references/{build-and-env, config, testing, traps, research-status}.md
• ddrs-eval-plots — evaluate output, rewritten around .ddrs/runs/<id>/; the dead output/saved_models_*/ layout is gone

Dropped the H5/H6 plot references (both plot instruments the v2 audit refuted) and rescued two orphaned parity files. Editorial rules: don't duplicate CLAUDE.md; lead with the discriminating test, not the narrative; one authoritative numbers table with a do-not-use list; assert "all pass" instead of brittle counts. Each SKILL.md opens with a TOC indexing into its references.

The mdBook, 13 chapters. It was a 2026-06-08 snapshot — leakance, the disaggregation head, nnse-kge/kge, ddrs sources/import/status/gc, managed adjacency, the global stores, and --backend cpu were all invisible to it. Beyond the dead commands: outputs.md opened with "there is no global results directory" (everything lands under .ddrs/runs/<id>/); setup.md claimed the CPU path needs no CUDA (burn-cuda/cudarc are non-optional, so a CPU-only reader fails at cargo build); seven "MLP head" mentions violated invariant 5; p_spatial was called an exponent; perf.md had the Rust defaults inverted and PersistentScratch at 33 handles instead of 39, understating memory ~18%; DDRS_FORCE_GRAPHS=1 does not actually exercise graph capture.

CLAUDE.md and README.md corrected for all of the above, plus the disaggregation head and experiment.loss.kind — neither of which appeared in any user-facing doc.

Verification

mdbook build is clean. Zero MLP references outside the documented mlp: serde alias. Every remaining ddrs init mention is in a "this is dead" context. Every rewritten ddrs-eval-plots template was executed end-to-end against a real run, reproducing the committed parameter_convergence_stats.json values exactly.

Notes for review

• One src/ change, comment-only (src/cuda_graph/scratch.rs docstring). Tier C gate run in full anyway: cargo check --lib clean, cargo test --lib 243 passed / 0 failed, cargo test all binaries ok, compare_ddr_sandbox ABSOLUTE MATCH (max abs 1.525879e-5 m³/s).
• nse-batch / optimizer: adadelta are documented with an explicit "arrives with PR feat(training): optimizer micro-batching (gradient accumulation) with exact valid-count weighting #31" caveat; they do not exist on master.
• .claude/references/ is left in place. It is a strict subset of docs/ and its newer mtime is a 2026-06-10 back-port, not newer knowledge — but deleting it means updating ~25 inbound links including one in src/sparse/mod.rs. Recommended as a follow-up in the report.

The V9 verdict is retracted

The last commit fixes the two source-side defects the audit found, and the second one is worth a reviewer's attention.

.claude/ARCHITECTURE.md recorded "V9 (graph vs no-graph bit-match): GREEN", evidenced by DDRS_FORCE_GRAPHS=1 compare_ddr_sandbox. That env var only selects the CUDA backend — and is read with .is_ok(), so DDRS_FORCE_GRAPHS=0 triggers it too. Capture requires all three of use_cuda_graphs && sparse_solver == Cuda && backend_is_cuda (src/routing/mmc.rs:289-294). The sandbox builds from Config::default() (src/sandbox.rs:88-89) = use_cuda_graphs: false + SparseSolver::Cpu, and fixtures/sandbox/config.csv sets neither toggle — it carries only geometry, ranges, and dt.

So the run that certified V9 exercised the CUDA backend with the CPU sparse solver and no capture. Corroborating: this PR's verification run reports max abs 1.525879e-5 m³/s, matching the 1.5e-5 in the historical V9 entry to the digit — that entry's run was this same CPU-solver path.

The ABSOLUTE MATCH is real and still certifies the backend. It does not certify the property V9 names. The CUDA-graph capture path currently has no gate. Both architecture docs now say UNVERIFIED with the reason; closing it needs a sandbox config that sets both toggles.

Also fixed: scratch.rs's docstring claimed 32 handles and all-n-sized buffers. Actual is 39 handles, of which 37 are n-sized and 2 nnz-sized — understating memory ~18% (~525 KB / ~44 MB → ~740 KB / ~51 MB). The inline "24 saved-state" is 23, now tied explicitly to mmc_op::NUM_SAVED_STATE.

🤖 Generated with Claude Code