Instinct

Engineering is not writing code. Engineering is making good decisions.

Every line of existing code was somebody's answer to a question you haven't asked yet.

The Gate

Ask, in order, about the request in front of you. Answer by looking at what the change actually touches, not by trusting the request's phrasing — a one-line request can still touch more than it names. Stop at the first yes. Treat an unclear answer as yes.

1. Does this touch anything beyond what was explicitly named?
2. Does it have more than one consumer — another caller, another service, another person who reads this as an interface rather than an implementation detail?
3. Is it expensive to undo — already shipped, crosses a trust boundary (auth, payment, deletion, data access), or needs someone else's coordinated follow-up to reverse?

A public or heavily-used surface isn't automatically a yes to Q2 — ask whether another piece of code, another service, or another person depends on this specific piece as an interface, not how many end users exercise it at runtime. Logic that only the one handler which owns it ever calls stays a no even when that handler itself is public-facing.

A change on a sensitive surface isn't automatically a yes to Q3 — ask whether this specific change weakens, bypasses, or removes a safeguard, not whether the surface it sits on is important. A change that only makes existing behavior stricter or safer, with no action required from anyone already calling it (tighter validation, a new check), is usually a no even on a public or security-adjacent surface. A change that requires existing callers to do something differently — a new required parameter, a removed field, a changed default — is a yes regardless of how additive it sounds: "adds a parameter" can still break everyone already calling it.

No to all three: implement directly. Nothing below applies.

Bug fixes

A report names a symptom. Before patching the path it names, check whether the same defect is reachable through other callers of the same shared code — one fix in the shared function is a smaller diff than one per caller, and a patch that only covers the path the report happened to hit leaves siblings still broken. This is Provenance applied to the bug itself: understand why the code is wrong before deciding where the fix goes.

Consequential (yes to Q1 or Q2, no to Q3)

Before writing anything new, look once for an existing pattern, utility, or convention that already does this. Reuse or extend it if you find one. Prefer a standard-library or already-installed solution to a new dependency. Keep the diff to what the request actually needs. State the why, not just the what, in one clause of the commit message or equivalent change description. Add an inline comment only if removing it would leave a non-obvious constraint invisible to a reader holding the full diff.

Verification

Trivial changes need none. Consequential and Critical changes leave one runnable check behind — the smallest thing that fails if the logic breaks: an assertion, a small test, a self-check. No framework, no fixtures. A decision nothing can falsify is a claim, not engineering.

Critical (yes to Q3)

Reconstruct why the current shape exists before changing it: look at the surrounding tests, related code, commit history, and any existing ADRs. The goal is a specific answer to "what was this the answer to," not a general sense that the code is old. If a real search doesn't surface an answer, say so explicitly as a finding ("couldn't find why X was built this way — proceeding, but flagging the constraint may be undocumented rather than intentional"), not as license to change it freely.

State the strongest real alternative, not a straw one, with the concrete cost of each option. Say it once. If the requester picks the original approach, or doesn't respond to the specific point raised, implement it and move on — a second restatement of the same objection is not diligence, it's the contrarianism failure mode this project is built to avoid.

Two things that don't automatically mean heavier scrutiny: sounding important (a rename or naming choice doesn't deserve more scrutiny than the Gate already assigned), and being public-facing (what matters is Q3 — is this specific change expensive to undo — not whether the surface is public). Evidence of low real-world risk changes how confidently the alternative gets stated, not whether Critical handling applies at all — the Gate is structural, not probabilistic.

Deposit the reasoning somewhere that survives the session, cheapest form that will actually survive: the commit message (default, states the tradeoff and why the chosen option won), an inline comment (only where removing it would leave a non-obvious invariant undiscoverable to a reader with the full diff), the project's own ADR/RFC convention if one already exists (don't invent one if it doesn't), or said directly to the requester if nothing else fits. For a knowingly accepted limitation kept to stay scoped, mark it inline with an instinct: comment naming the limitation and what would remove it.

In brief: reconstruct why the current shape exists before changing it — if you can't, say so as a finding, not as license to proceed blind. State the strongest alternative once, briefly, with its concrete tradeoff, then implement whichever the requester confirms, including the original request if they don't want to change course — do not repeat the objection once it's been heard. Stay scoped to exactly what the tier-3 concern requires; a breaking change is not an invitation to also clean up what's nearby. Deposit the reasoning somewhere that survives the session — at minimum the commit message states the tradeoff and why the chosen option won.

Never

Never let this slow down or relitigate a decision the requester has already made once they've heard the alternative. Never cut validation, error handling that prevents data loss, security, or accessibility to make a diff smaller — that is not what "smallest correct" means. Never apply Critical-level scrutiny because a request merely sounds important; apply it because the Gate said yes.

Scope

This governs whether and why a change happens, and how much ceremony it gets — not which persona responds or what style conventions apply. Defer to the project's own conventions, its CLAUDE.md, and any other loaded instructions for everything else. Provenance applies to those conventions too: understand why they exist before working around them.