from-scratch

A fix that makes the symptom stop is not the same as a fix that makes the cause impossible. This skill forces one comparison before you write code:

Is what I am about to write what I would have written from a blank page?

If yes, ship it. If no, you owe an explicit answer for why the difference exists — and the user owes a decision, not a silent choice you made for them.

Budget

Under two minutes for a normal fix. This is a thinking pass, not a document. If it turns into ceremony you will skip it next time, which defeats it.

Gate: run it, or don't

Skip entirely — a typo, formatting, renaming, a literal value or config change, a dependency bump, a missing translation, or the user asked for exactly this edit and nothing else.

Run it when any of these is true:

• the fix adds a branch, guard, retry, timeout, threshold, try/except, fallback, or special case
• this area has been fixed before (check git log on the file, or comments citing an earlier fix)
• the fix touches verification, error handling, concurrency, money, auth, or data integrity
• the same bug has reappeared in a new form
• you felt relief when a test finally passed. That feeling is the most reliable detector on this list. Relief means you were chasing green, and chasing green is how band-aids get shipped.

Step 0 — Mechanical facts, before any judgement

Run these. They produce numbers you do not control, so the triggers below cannot be felt away.

git log --oneline -40 -- <file> | grep -ciE 'fix|bug|regress|patch|defect|broke'   # prior fixes
grep -rn '<function-you-are-about-to-edit>' <src-root> | wc -l                     # caller sweep

Two or more prior fixes is a hard trigger, not an impression. If the caller sweep returns N > 1, your fix belongs where those N converge, not at the reported symptom.

Step 1 — The blank-page answer, made unfakeable

The honest version of this step cannot be "answer without looking at the implementation". By the time you are designing a fix you have already read it. That mental state is unreachable, so any answer you give from memory is a self-report — and a self-report is exactly what a band-aid needs in order to survive review. Do not police the blind answer to match your peek. Change who answers, fix the order, then check that answer against the repo. Those are different acts.

Step 1a — Commit before you build (always, ~30 seconds)

~/.claude/skills/from-scratch/commit.sh <target-file> <<'EOF'
BRIEF:  <the behaviour and the observed failure, in plain terms. NO identifiers from the current
        implementation — this is what a designer who has never seen the file would be handed.>
DESIGN: <how you would build this from an empty file, <=3 sentences>
OMITS:  <at least one thing the current implementation has that your design does NOT.
        If genuinely nothing, write exactly: nothing - identical>
EOF

Two properties do the work, and neither is introspection:

• It is written before the fix exists, so it cannot be quietly reshaped afterwards to match whatever you ended up building. The order is the mechanism.
• It is validated. OMITS may not be empty — and that is the anti-fake device. A design copied from code you just read cannot name an omission, because it is that code. A real blank-page design nearly always drops something the patched version accumulated. Being unable to fill this line is the tell, and the tool refuses rather than accepting a blank.
• The BRIEF is scanned for leaked identifiers. Code-shaped tokens (snake_case, camelCase) that also occur in the target file are refused by name, because naming the current mechanism is how you steer a fresh designer back into reinventing it. Plain English is never flagged, so the check stays quiet enough to keep switched on.

Step 1b — An answerer that cannot peek (mandatory on any hard trigger)

Spawn a subagent and give it the BRIEF only. Not the file, not your proposed fix, not your reasoning, not the diff. It runs in a separate context, so its blindness is a property of the system rather than a promise you are keeping.

Quote its DESIGN verbatim. That answer is evidence, not Step 1's answer. Blindness stops you from faking a blank-page design; it does not review this repository. Yours (Step 1a) remains a hypothesis until the check below.

Validate against the repo, then align. The blind designer has never seen this codebase. Anything it invented that this repo does not already have is unverified, not architecture.

1. Check the quoted DESIGN against the repo: architecture docs first (README, contributor docs, plans, module docs), then the code those docs describe. Cite one source. This pass is supposed to look.
2. Restate the design in that verified architecture. Drop or rewrite greenfield mechanisms the repo does not have. The restated form is Step 1's answer.
3. If the blind DESIGN conflicts with verified architecture, name the conflict in one clause. Do not adopt it to resolve the disagreement. If you believe the architecture itself is the bug class, carry the conflict into Step 2 (E2) and Step 3 as a named alternative. Default is to align; adopting a conflicting blind design requires an explicit verdict, not Step 1b.

Hard triggers (any one):

• Step 0 counted ≥2 prior fixes to this file
• this is the second or later attempt at the same bug
• any escalator in Step 2 fired
• the fix touches verification, concurrency, money, auth, or data integrity

Step 1c — The guard: enforcement that is not you

guard.sh runs as a PreToolUse hook on Edit|Write|Bash. If the file you are about to change has ≥2 fix commits and there is no fresh commitment naming it, the change is blocked with instructions. The trigger is counted from git history, so declining to run this skill does not evade it.

Bash is not an exemption, and that matters more than the Edit path: in auto mode you are told to change files with sed, heredocs and short scripts instead of the Edit tool, so an Edit|Write guard would sit watching a door nobody uses. A Bash command is gated only when it carries an unambiguous write aimed at a repeat-offender path — sed -i, tee, a redirect at that path, a copy or move onto it, or a script opening it for writing. Reads stay completely free (sed -n, grep, cat, git log, bash -n, 2>/dev/null, < file), because a guard that taxes reading gets switched off, and a switched-off guard prevents nothing.

• Fails open on every ambiguity — no jq, no git, new file, docs/config, unparseable input. A guard that can block all editing is worse than the defect it prevents.
• Kill switch: FROM_SCRATCH_OFF=1. Escape hatches are logged, so bypassing is visible.
• Every decision lands in ~/.claude/from-scratch/guard.log.
• Self-check: sh test.sh (from this directory). Guard cases need a tracked file with ≥2 fix commits as $1; without one they skip. Skill-text checks always run.
• Install (operator, once): sh ~/.claude/skills/from-scratch/install-hook.sh Idempotent, backs up settings.json first, writes atomically, and refuses to install unparseable JSON. Claude does not run it: this machine set neverModifyGlobalSettings=true after a torn read clobbered that file, and a guard against careless edits has no business being installed by one. Until it is registered, Steps 0-1b still apply — they just rely on Claude following them rather than being stopped.

Then answer the two questions

Compare your proposed fix to the aligned blank-page answer (after the architecture check), not to the raw blind DESIGN.

1. Name the difference between that aligned answer and your proposed fix, in one clause. "None" is legitimate and common — say it and move on.
2. If the difference is "none", you are done. Emit the output line (Step 4) and ship.

Step 2 — Five escalators

Any one of these being true means you are patching an instance of a class, not fixing the class. They are ordered by how often they turn out to be the real story.

E1 — Repeat offender. Two or more prior fixes to this same behavior. → Stop fixing instances. Write down the premise all of them share, and attack that. Signature: your commit message could be "fix X (again)".

E2 — The premise you never questioned. List what must be true for this bug to be possible at all. Now mark each item as imposed by the world or chosen by us. → Every "chosen by us" item is a candidate for deletion. The best fix removes the thing the bug needs in order to exist. Signature: your fix makes a hard thing work more reliably instead of making it unnecessary.

E3 — Direction of error. Your fix contains a judgement — a check, threshold, heuristic, timeout, or comparison. Ask two things:

• When it is wrong, is the failure loud (logged, retried, visible) or silent (accepted, no record)? Never take the silent side. A false refusal is annoying; a false acceptance is corruption.
• Does it answer the same way for "no" and "I can't tell"? Those need opposite responses. Split them into two return values. Signature: one boolean standing in for two distinct states.

Also: if the fix introduces a tunable — env var, constant, threshold, batch size — say what happens at 0, empty, negative, and non-numeric. An unvalidated knob is a fix that ships its own next bug, and under a stripped environment it may be silently inert as well.

E4 — Self-referential verification. Does the state you read to confirm an action get modified by that action, or by anything the action triggers? → Then success can render as failure, and each "retry" can make it worse. Verify against something the action does not touch. Signature: reading UI, cache, derived, or shared state to confirm a write you just made.

E5 — Evidence provenance. What actually convinced you this works? → A test whose fixture you invented can only confirm your model of the world, never the world. If every new test stubs a surface you wrote from imagination, you have tested your assumptions. Measure the real thing once, even crudely. Signature: no number in your reasoning came from an observation.

Step 3 — Pick a verdict, out loud

Exactly one of three. You may not leave this implicit.

1. same — the small fix is the from-scratch answer. Ship it. State it in one clause.
2. premise — the from-scratch version is smaller, or removes the bug class outright. Do that instead. Prefer this whenever its diff is comparable or smaller than the patch. Deleting the capability a bug depends on beats guarding it: one such change can retire a whole family of existing workarounds, and you should check whether it does.
3. patched-with-debt — the from-scratch version is right but genuinely out of scope now. Ship the patch and tell the user, in at most two lines: what the from-scratch version is, roughly what it costs, and what will keep breaking until then.

The hard rule: you may not choose 3 silently. Scope is the user's call. Choosing 3 without saying so is precisely the band-aid this skill exists to prevent — and a TODO comment is not telling anyone.

Never expand scope on your own either. Verdict 2 means propose and do the better fix when it is comparable in size; it does not license a refactor nobody asked for. If the from-scratch version is a large architectural change, that is verdict 3 with a clear recommendation, not a surprise rewrite.

Step 4 — Output contract

Append one line to whatever you were already going to say:

from-scratch: same — no difference
from-scratch: premise — deleted the retry loop instead of bounding it; the bug needed the loop
from-scratch: patched-with-debt — guarded the caller; from scratch this would be one validated
              constructor (~90 min, touches 6 call sites). Until then every new caller can reintroduce it.

When Step 1b ran, say in one clause what the blind designer proposed, whether it survived the architecture check, and what you aligned to:

from-scratch: same — independent designer (blind) proposed a new event bus; architecture
              (docs on the existing hit-test walk) already resolves the click that way; aligned
              to the walk. [commitment: 20260910T140233Z-...md]

from-scratch: premise — independent designer (blind) proposed writing the payload to a file
              and typing a pointer; the host-must-be-typed constraint is chosen-by-us; verdict
              premise, took the file pointer. [commitment: 20260910T140233Z-...md]

Terse is correct. This is an audit trail, not a report.

Red flags — these thoughts mean you are rationalizing

Worked example

A watchdog typed a long prompt into a terminal box, and the prompt kept arriving truncated. Four fixes shipped: chunk the send, verify the whole payload, read the screen deeper, compute a length budget from the pane geometry. Each one passed its tests. The fourth was still wrong, because pane width, font, and window height all change between measuring and typing.

The Blank-Page answer was one sentence: from scratch, you would not type a long payload into a terminal at all — you would write it to a file and type a short pointer to it.

That form survived the architecture check because "the prompt must be typed" was chosen by us, not because the blind agent is authoritative. Had the host only accepted typed input (imposed), the aligned design would have been a short payload inside that constraint.

• E1 fired: four prior fixes to one behavior.
• E2 named the premise: "the prompt must be typed" was chosen by us, not imposed.
• Verdict: premise. The payload became a fixed 291-character pointer.
• It retired all four earlier fixes, plus the truncation class entirely — and the length threshold, the deep reads, and the chunk-completeness check all became dead code.

Then the replacement verification shipped a fresh defect, caught only by review: it traded a loud false refusal for a silent corrupt submission. That is E3 — the same check failing in the opposite direction, with nobody having asked which direction was safer to be wrong in.

The lesson worth carrying: four fixes, four green test runs, one avoidable premise — and the question that would have found it on day one takes ten seconds to ask.