Skip to content

Commit e6ee1ae

Browse files
physicsrobclaude
andcommitted
Strip dead-pointer worked examples from CLAUDE.md
Eight 'Worked example' blocks across the Doctrine, Testing, and Debugging sections all anchored to artifacts that no longer exist in this repo: `docs/postmortems/phase_e_xfail.md` and `…/angle_210_overlay_reserve.md` (both deleted with `docs/postmortems/` in Step E), `torchwright/doom/stages/wall.py` (deleted), the Phase E (3, 2, 20) xfail (test deleted), `_ABOVE_BONUS` and SORTED stage code (deleted), and `_VIS_C_TOL` in deleted source. Each was a fragment of a teaching story whose supporting artifacts now live elsewhere — the pointers in CLAUDE.md sent readers to dead links. Cuts: - Doctrine intro: rewrote 'The DOOM renderer project has a recurring failure mode…' to drop the DOOM anchor; the doctrine now stands as general compiler-work guidance. - D1, D2, D4, D5, D6, D7: deleted each rule's 'Worked example' block. The rule + Why + Tooling triplet stands on its own. - D3: kept the worked example but rewrote it to drop the Phase E anchor; the *and-of-maybes* shape teaches the rule on its own. ('Likely X near Y under Z' replaces the Phase E xfail reason.) - Testing § 'When full-suite tests fail but `-k` passes': dropped the trailing 'Worked example: docs/postmortems/angle_210_…' line and scrubbed `tests/doom/` to 'the full suite'. - Debugging § 'FP nondeterminism at tolerance boundaries': dropped the trailing 'Worked example: _VIS_C_TOL = 0.01 in torchwright/doom/… See docs/postmortems/angle_210_…' block. The teaching power lost is real but contained — the deleted postmortems and incident threads remain reachable via git history. What's gained: no broken pointers in the most-cited section of CLAUDE.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent be97c6b commit e6ee1ae

1 file changed

Lines changed: 11 additions & 62 deletions

File tree

CLAUDE.md

Lines changed: 11 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -165,16 +165,14 @@ Tests calling `compile_game()` are expensive (~17s to compile, ~2s per
165165
## When full-suite tests fail but `-k` passes
166166

167167
A test that passes under `make test FILE=... ARGS="-k foo"` but fails when
168-
the full `tests/doom/` suite runs is almost always cross-test GPU state —
169-
cuBLAS algorithm cache biased by prior allocations, tensor-cache warmup,
170-
or scheduler nondeterminism — not a logic bug in the failing test. The
168+
the full suite runs is almost always cross-test GPU state — cuBLAS
169+
algorithm cache biased by prior allocations, tensor-cache warmup, or
170+
scheduler nondeterminism — not a logic bug in the failing test. The
171171
diagnostic signature is an allocator-sensitive compute path or a
172172
tolerance-boundary flake (see *FP nondeterminism at tolerance boundaries*
173173
under *Debugging compiled graphs*). Investigate the ops on the failing
174174
codepath, not the test.
175175

176-
Worked example: `docs/postmortems/angle_210_overlay_reserve.md` §2.
177-
178176
# Numerical noise
179177

180178
Every approximate op in `torchwright/ops/` is measured against its exact-math
@@ -479,10 +477,6 @@ changes). Full-suite-only test regressions (passes under `-k`,
479477
fails in the full suite) are the most common way this bites; see
480478
*When full-suite tests fail but `-k` passes* under *Testing*.
481479

482-
Worked example: `_VIS_C_TOL = 0.01` in
483-
`torchwright/doom/stages/wall.py`, widened from the default
484-
`0.005`. See `docs/postmortems/angle_210_overlay_reserve.md` §2.
485-
486480
## Triage sequence for wrong output
487481

488482
1. **`compiled(inputs, debug=True)`** — does the self-consistency
@@ -524,11 +518,10 @@ implementation.
524518

525519
# Doctrine
526520

527-
The DOOM renderer project has a recurring failure mode: ship a
528-
99%-working thing, build on top, and have the 1% bite later. The
529-
rules below exist to defeat that pattern. They constrain how to
530-
investigate, what to ship, what to defer, and what to write in
531-
xfail reasons.
521+
The doctrine below exists to defeat a recurring failure mode in
522+
compiler work: ship a 99%-working thing, build on top, and have
523+
the 1% bite later. The rules below constrain how to investigate,
524+
what to ship, what to defer, and what to write in xfail reasons.
532525

533526
## D1 — Suspected-compiler-bug protocol
534527

@@ -544,14 +537,6 @@ stated compiler invariant.
544537
next user. Every "I packed it differently and the bug went away"
545538
fix is one we'll re-encounter, harder to debug, somewhere else.
546539

547-
**Worked example.** Phase E (commit `c2d5a7a`) attempted three
548-
rounds of routing around suspected residual-column overlap by
549-
reshaping user code (separate output → packed payload →
550-
packed-but-narrow-extract). None resolved the root cause; the bug
551-
surfaced again as the (3, 2, 20) xfail. Eventually fixed by a
552-
root-cause precision tightening (commit `2e6f5da`) — see
553-
`docs/postmortems/phase_e_xfail.md` for the full arc.
554-
555540
**Escalation.** Inform the user immediately with the specific
556541
trigger that fired and ask for guidance. Do not proceed with
557542
workarounds unilaterally.
@@ -572,15 +557,6 @@ look like understanding.
572557
tomorrow's assumed explanation, and the real bug grows another
573558
layer of camouflage.
574559

575-
**Worked example.** The Phase E xfail was shipped with the reason
576-
*"likely due to compile-side precision loss in the per-wall
577-
is_renderable gate at geometry that lands near the
578-
attention-edge-of-view."* That explanation was a guess wearing the
579-
costume of an investigation — the actual root cause (fp32 precision
580-
compounding driven by an overly-loose declared output range on
581-
`piecewise_linear_2d`) sat undiscovered until someone eventually ran
582-
the oracle probe. See `docs/postmortems/phase_e_xfail.md`.
583-
584560
**Tooling.** `torchwright/debug/probe.py` runs a compiled module
585561
side-by-side with the recursive graph oracle and reports the first
586562
node whose compiled value diverges. Use it as the first step on
@@ -601,10 +577,10 @@ missing, add it.
601577
**Why.** Compressing the cause to one sentence is the diagnostic.
602578
If the sentence won't compress, the cause isn't known yet.
603579

604-
**Worked example.** The Phase E xfail reason wraps three hedged
605-
conjunctions into one sentence ("likely … near … under …"). That
606-
*and-of-maybes* structure is the warning signwhen only an
607-
and-of-maybes will fit, the sentence is hiding ignorance.
580+
**Worked example.** "Likely X near Y under Z" — three hedged
581+
conjunctions in one sentence. That *and-of-maybes* structure is
582+
the warning sign: when only an and-of-maybes will fit, the
583+
sentence is hiding ignorance.
608584

609585
## D4 — Foundation rule
610586

@@ -617,15 +593,6 @@ cost of going back. Downstream changes pile up against the
617593
unfixed anomaly and turn what would have been a local fix into a
618594
re-architecture.
619595

620-
**Worked example.** The Phase E xfail was shipped to unblock
621-
downstream phases on the theory that the real cause could be
622-
chased later. By the time someone went back to root-cause it,
623-
the SORTED above-threshold primitive had acquired more callers —
624-
the fix landed cleanly (commit `2e6f5da`) but only because the
625-
root cause turned out to be in `piecewise_linear_2d`'s declared
626-
range, not in SORTED itself. Had it been in SORTED, every
627-
downstream user would have needed re-validation.
628-
629596
## D5 — xfail hygiene
630597

631598
**No `xfail` without a precisely documented root cause.** Two
@@ -645,13 +612,6 @@ evidence and no follow-up.
645612
trap. The next contributor reads the reason, takes it as an
646613
explanation, and stops looking.
647614

648-
**Worked example.** The Phase E xfail shipped with the
649-
unacceptable form (see D2). It was eventually resolved by a
650-
root-cause fix (commit `2e6f5da`) rather than by rewriting the
651-
xfail reason — but the interim cost was a trap reason sitting in
652-
the test file that anyone reading it would have taken as
653-
explanation.
654-
655615
**Tooling.** `torchwright/debug/probe.py` is what you use to
656616
convert form 2 into form 1.
657617

@@ -668,12 +628,6 @@ layer; this rule applies to behavior bugs.)
668628
and easily broken by unrelated changes. Smallest repros are
669629
fast, direct, and survive refactors.
670630

671-
**Worked example.** Phase E's (3, 2, 20) regression surfaced as a
672-
render test (slow, system-level). The smallest repro was a
673-
SORTED-stage call to `attend_argmin_above_integer` with the
674-
specific `indicators_above` input that fails to concentrate — a
675-
stage-level unit test, not a render test.
676-
677631
**Tooling.** `torchwright/debug/probe.py` to identify which
678632
layer / which node / which inputs reproduce the bug; `make
679633
test-local FILE=...` to iterate fast against the resulting unit
@@ -691,11 +645,6 @@ assumptions. If `compare`'s bound moves from 1e-3 to 5e-3
691645
silently, every downstream stage that budgeted against 1e-3 is
692646
now over-budget without anyone knowing.
693647

694-
**Worked example.** Phase E raised `_ABOVE_BONUS` from 100 to
695-
1000 to give the SORTED softmax more headroom. That changes the
696-
piecewise softmax's effective working range and may change its
697-
measured error bound. Neither was re-measured at the time.
698-
699648
**Tooling.** `docs/op_noise_data.json` is the canonical source;
700649
`docs/numerical_noise.md` and per-op docstring footers are
701650
generated from it via `make measure-noise`. See the

0 commit comments

Comments
 (0)