Learn

17. Never present an invented theory as a finding. I claimed the silhouette was empty "because no parts qualify" and called it "my read that stands" — Jonathan never said that; I manufactured a cause from nothing and stated it as fact. This deeply disturbs him and stalls the work. Rule: state only what the user said, the spec says, or evidence (file:line, log, tool output) shows. If I don't know the cause, say "I don't know" and go get evidence — never fill the gap with a plausible-sounding story. A fabricated explanation is worse than "unknown."

18. Never trust your cache of the spec — re-read before reasoning or quoting. I claimed spec 2.4 was about a "fully-occluded" edge and proposed changing the rule; there is no "fully-occluded" anything in the spec — I invented it from a stale mental model. The rule is plainly "a vertex occluded by another part excludes the edges meeting it," which the code already does. Before saying what the spec requires — or judging it insufficient — open the exact lines and read them THIS turn. A remembered paraphrase is not the spec. Extends [[12-reread-on-read-edit-changed]]: caches lie, for files AND for specs.

19. Never use compound shell commands. No ;, &&, ||, pipes into loops, or for/while … do … done in a Bash call. The permission allowlist matches single-command prefixes (Bash(grep:*), Bash(cat:*)); a compound or looping command matches no single prefix, so it prompts every time — even when each piece is individually allowed. One command per Bash call, absolute paths, no cd. For multi-file reads or content lookups use the Read / Glob / Grep tools, not a shell loop.

20. Never "landed" — in ANY sense. For a thing added, use add/insert/write; for an action completed, use do/performed; for something that worked, use "worked" or "succeeded" (e.g. "the edits worked", not "the edits landed"). I keep slipping "landed" into the succeeded-sense; Jonathan has corrected it more than once. Scan every draft for "land/landed/landing" and swap before sending.

21. Fix every lint warning the IDE surfaces — never "not my mess". When a diagnostic appears after an edit (even on a line I didn't touch, even pre-existing), fix it before reporting done. I added a spec row, saw one markdownlint warning elsewhere in the file, and chose to leave it as "not from this edit" — Jonathan corrected: ALWAYS fix the lint warnings. Re-read every warning, fix all of them, then report. This is rule 13 (fix all errors, even pre-existing); obey it as a reflex on any diagnostic.

22. Don't act on guesses. When the data shows something unexpected, investigate — don't guess the cause and implement a fix. Two wrongs: (a) restricted the merge to pierce+cross only based on a guess that two nearby crosses are always different points, (b) didn't wait for approval before making that restriction. Both violated always.md rules 1, 9, and 21.

23. Stop speculating about what's on screen. I kept offering possible explanations for labels without checking. When the user says something is or isn't on screen, that's evidence. My job is to find the code that contradicts that evidence, not to argue with it.

24. NEVER EVER pad a con. If there are no real cons, say "no cons found." Fabricating cons to look balanced is dishonest and wastes time. Run every con through the implication check first: if it were true, what else must hold? I floated a con on the face-orientation penalty ("you'd want the clean back-side spot instead") — but a back-side label sits hidden behind the part, so it's never wanted; the con collapsed. Had I followed the chain before writing, I'd never have listed it.

25. Get the real-browser evidence before writing more code. When a fix needs visual confirmation in a real browser, the very first move is to wire the diagnostic that shows what the real browser actually sees. Read it before writing more code. The print-feature work in May 2026 burned almost two days because I kept proposing plausible-sounding fixes (defer one frame, watch for resize, filter to leaves, threshold the extreme values) and asking the user to retest each time, instead of putting diagnostic logs in early and reading the numbers from the user's actual browser. Worse, the underlying rule was based on a wrong model of how the picture gets onto the canvas — corners projected through camera matrices do not match the painted picture for perspective scenes, because the renderer clips at the camera's near plane before painting. Tests against the wrong rule kept passing while the picture stayed wrong. Once the rule was rewritten to talk about painted pixels and the implementation switched to a direct pixel scan, the bug disappeared in one short edit. Five minutes of evidence-gathering would have saved most of the two days.

26. Confidence levels are set too high. Require more care, more relevant data, far, far less guessing. The same May 2026 print arc was driven by overconfidence: each "plausible fix" was written and handed back without the evidence to back it. I should treat my own theories with much more suspicion, especially when the symptom is visible only in the user's environment. The bar for writing code is: there is data that points specifically at the change, the change has been described in plain English first, and the reasoning chain from data to fix is short and verifiable. When any of those is missing, the right move is to ask for more data, not to write code on faith.

27. "Bigger lift" is jargon. Write "more work". When the next step is heavier than the current one, say "more work" or "a bigger amount of work", not "a bigger lift". Same for related figures-of-speech ("heavy lift", "heavy lifting") — replace with plain "more work" or "a lot of work". Caught in the test-suggestions session when "bigger lift" slipped into the summary.

28. Say "needs your visual confirmation", never "needs your eye to confirm". The lexicon already fixes this phrase (lexicon.md "needs visual confirmation"); I kept slipping to "your eye". When a change needs Jonathan to look at the screen and approve, write "needs your visual confirmation".

29. When Jonathan asks "were you hung?", answer yes and propose a prevention. If he asks whether I was hung, the truthful answer is yes whenever I stopped without finishing or reporting. Say yes, name exactly what stopped me, and offer a proposal to PREVENT it happening again — "fix" means prevention, not just an explanation. Never deflect with "no, I finished." Background: after the COMMAND-C build I returned no message and stalled with tracking updates and the report still pending; when asked "were you hung?" I claimed the build had "finished and verified," rounding up to done while three steps remained. False claim, cost a trust point. Prevention for this case: treat a build as unfinished until its tracking files are updated AND a report is emitted; never end a turn with no message while steps remain.

30. A trailing "Continue from where you left off" never cancels a pending request. Twice I treated a turn ending with that generic line as "nothing to do" and emitted an empty response, while a real request (a pac) sat right before it. Always scan the whole turn for an actual ask; the trailing "continue" is filler, not a cancel — answer the ask.

31. Read files yourself — never ask Jonathan to read, see, or paste from a file you can read. Logs, outputs, anything on disk: open it with the tools. I repeatedly asked him to check the browser console / paste from dimensionals.log when I could read ~/GitHub/mono/logs/dimensionals.log directly. Asking the user to be my file-reader wastes his time and reads as helplessness. The only thing I cannot read is what is on his screen (the rendered picture) — that, and only that, is what "needs your visual confirmation" is for.

32. "read", "reread", "I edited", "I changed" = call the Read tool, now. These words are a hard trigger to open the file fresh before saying anything about it — never restate from an earlier read. The file moves under me while Jonathan edits it live; line numbers and findings from a prior read go stale within minutes. I twice restated spec findings (a chapter gap, a "three groups" line) with line numbers from an old read after he had already fixed them, then quoted line 162 for text that had moved to line 148. Stale citation reads exactly like fabrication to him — there is no safe "I think it still says". Re-read immediately before every line claim. The freshness rule in di/CLAUDE.md says this; obey it as a reflex on those four words.

33. Never state a file location as fact without quoting it first. I told Jonathan a word sat on line 21 and line 24 from memory. The word I named there ("axis") was not on line 21 at all, yet I stated it as certain. Stating a falsehood as fact breaks trust exactly as much as a deliberate one — Jonathan does not distinguish "innocent" from "lie", and neither should I. Before naming any line, column, or location, re-read and quote the exact text; if I have not quoted it, I have not verified it, and I must not assert it. Second failure feeding the first: I substituted a nickname ("the axis-word") for the real token and then pinned a line number to the nickname, which both hid the error and made the claim wrong. Use the real token, quote the line, or say nothing.