CLAUDE.md: inherited design is a hypothesis, not terrain - #1054
Merged
Conversation
90%+ of this code was designed by Claude sessions running models many generations old. The project is pre-v1 with no external consumers, so a decision found in the tree carries no authority from seniority — it is an earlier session's hypothesis and is fair game to question. The tell: writing "X must be true because the design does Y". Ask whether Y is a law (semantics, a physical constant, an external contract) or a decision, and price the alternative before designing around it. Bought 2026-08-28 (ouroboros#127 / DMG): a real seam bug was found, fixed and verified, and reported as unlocking the AOT multiplier for DMG. On being challenged, measurement showed DMG is 818 compiled lines against 2,470 interpreted — including the 128-function opcode dispatch — so the fix makes it run and cannot make it faster. A full investigation cycle had treated that design as terrain, and the alternative was already implemented elsewhere in the same tree for another purpose.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Standing note, added to every repo in the ecosystem.
90%+ of this code was designed by Claude sessions running models many generations old. New models keep arriving that are substantially stronger, the ecosystem is pre-v1, and there are no external consumers to break — so a decision found in the tree carries no authority from seniority. It is an earlier session's hypothesis and is fair game to question.
The tell: writing, or thinking, "X must be true because the design does Y." Stop and ask whether Y is a law (language semantics, a physical constant, an external contract) or a decision. If it is a decision, price the alternative before designing around it.
Bought 2026-08-28 (ouroboros#127 / DMG). A real bug in the AOT's load_file seam was found, minimised to six lines, fixed, and verified at 100/0 on the differential — and reported as "unlocking the AOT multiplier for DMG". Then the design itself was questioned. Measured: DMG is 3,288 lines, 818 compiled against 2,470 interpreted, including the 837-line, 128-function opcode dispatch. Every emulated instruction dispatches into interpreted code, so the fix makes DMG run and cannot make it meaningfully faster.
An entire investigation cycle had treated "loaded modules are interpreted" as terrain — including rejecting the alternative as "unbuildable" — when the capability to do it the other way already existed elsewhere in the same tree (
obs_gate_resolve_static_loads, used by the #915 observer gate).Docs-only.
🤖 Generated with Claude Code