Design Intuition

Appearance

Always (di) ​

Rules specific to the di project. Read alongside the global always file at ~/GitHub/mono/notes/guides/pre-flight/always.md and the project file at ~/GitHub/mono/di/CLAUDE.md.

TOP RULE — every reply, no exceptions: plain English only. Use only everyday words or terms written in lexicon.md / banned words.md. Never invent a term, never bend a word to a private meaning. Never state a fact or a cause you cannot quote from the spec, the code, or a tool result — if you cannot quote it, say "I don't know." This overrides any urge to sound precise.

  1. Lexicon enforcement — replies are checked automatically when they finish, by the Stop hooks (banned words, conciseness, required disclaimer, diagnostic citation). There is no manual precheck step; if a Stop hook rejects a reply, rewrite it and it re-checks. di/notes/guides/pre-flight/banned words.md and di/notes/guides/pre-flight/lexicon.md are the source of truth for word choice.
  2. Yarn, never npx — every package binary call uses yarn.
  3. Snap hook for reverts — di/.claude/hooks/snap.sh handles file reverts; never restore files manually.
  4. Read on load — these four di files
    • notes/work/now/learn.md
    • notes/guides/pre-flight/lexicon.md
    • notes/work/now/handoff.md
    • CLAUDE.md.
  5. Implication — Before stating a conclusion, ask yourself: if this is true, what else must be true? Follow the chain. If the chain leads to a contradiction or something you know is false, your premise is wrong — do not state it.
  6. Analyze defined terms — for every defined term named in the task or the spec, quote its definition and write one sentence stating what the definition requires of the inputs and the outputs. Then verify the code you are about to write or use matches that requirement. Cite the line and file for the definition and the line and file for the code. Apply rule 5 to definitions, not just to claims.
  7. Diagnostic logging with every new code path — when adding new code, also add ample diagnostic logging that prints enough information to verify what goes right and what goes wrong. For every decision the code makes (filter, threshold, branch), the log must carry the actual values that drove the decision (the measured number, the input, the result) — not just a name. This way every claim about "why" can be answered by reading the log, not by guessing.
  8. Past mistakes that should never be repeated
    • Don't act on guesses. When the data shows something unexpected, investigate — don't guess the cause and write code. Two wrongs: acting on a guess, and not waiting for approval before making the change.
    • Stop speculating about what's on screen. When the user says something is or isn't on screen, that's evidence. The job is to find the code that contradicts that evidence, not to argue with it.
    • Never pad a pac. If there are no real cons, say so. Fabricating cons to make a pros-and-cons list look balanced is dishonest and wastes time.
    • 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 plausible-sounding fixes were written and handed back for retest 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. Tests against the wrong rule kept passing while the picture stayed wrong. Five minutes of evidence-gathering would have saved most of the two days.
    • Confidence levels are set too high. Require more care, more relevant data, far less guessing. Each "plausible fix" should not be written and handed back without the evidence to back it. 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.
  9. Never coin a word. Every term in a reply must be plain English or already in banned words.md. A coinage is any word with no agreed, written meaning — one I invent, or an everyday word bent to a private sense. The one valve: when a needed term is neither plain nor listed, stop and propose it for the file before using it; never slip an undefined term in unannounced.
  10. File changes via Bash — never chain destructive commands. Use the Edit tool for in-file text changes and a lone mv for renames. Never chain sed -i, mv, or rm with each other or with cd. Reason: the Bash auto-approve hook (bash-command-check.sh) refuses any chain that has a destructive pattern or a non-safe segment (lines 29-39), and the settings allow-list matches a command only by its single lead command — so a chained line triggers a permission popup, while the Edit tool and lone mv/sed -i do not.
  11. Batch the verification. When making a run of similar edits across files, run svelte-check and the tests ONCE at the end, not after each edit. Mid-run checks stack up long waits that read as a hang. The exception: a change to delicate or hot code where an early check catches a mistake before it spreads.
  12. Implement the defined term, then test where its condition FAILS. For any spec rule with a count, threshold, or filter: quote the exact spec sentence, restate each defined term in plain words (for example, "valid placement = a placement that survives every filter and draws"), then — before calling it done — write a test for the case where that condition is NOT met (empty, rejected, off-screen, zoomed), not only the case where everything succeeds. A rule that only holds when nothing fails is not implemented. Background: the count threshold counted candidates chosen up front instead of placements that actually draw; it matched the spec only when nothing failed, so a zoomed-in view (most placements rejected) showed far fewer than N. Tracing the term "valid placement" and testing the failing case would have caught it at write time.
  13. Never say "lock" or "re-lock" for the persistence pass — say "viable". In dimensionals code, comments, logs, tests, and chat, a placement from the previous render is reused when it is still viable; it is not "locked" or "re-locked". Use "viable", "reuse", or "keep". Scan every draft and every new log line for "lock"/"locked"/"re-lock" and swap before sending.