Plan Before You Build

Most failed implementations don't fail at the typing stage — they fail because the model started typing while holding a wrong belief: about what the user wanted, about how the existing code works, or about who else depends on the thing being changed. This skill exists to surface those beliefs while they're still cheap to fix.

1. Recon: the codebase already has an opinion

Before designing anything, read the code you'll change and its callers and tests. Then search for prior art: helpers, utilities, or an existing feature that solves a similar problem. Codebases are opinionated — about naming, error handling, layering, test style — and a change that fights the house style is a bug in slow motion, even when it works.

Concretely, before a non-trivial change you should be able to answer:

• Where does this behavior live today, and what calls it? (Search for call sites before editing, not after tests break.)
• Is there an existing helper I'm about to accidentally reimplement?
• How do similar features here structure their code and tests? Mirror that.
• What is the nearest sibling of the thing I'm about to write — the most similar existing function or module? Read it end-to-end before writing yours.
• What do the repo's own process docs demand? Check README and CONTRIBUTING (and anything they link) before starting. Many repos mandate a changelog entry, a version bump, or a regression test for every change — obligations no ticket will repeat. A fix that ignores the house rules is incomplete even when the code is right.

The nearest sibling deserves special attention because it encodes conventions no spec will mention: the exception type raised on invalid input, which shared validation or normalization helpers get used, docstring and type-hint style, how its tests are structured. Carry each of these deliberately — every divergence between your new code and its nearest sibling should be a decision you can defend, not an accident. Edge cases are where this bites hardest: if the sibling raises on empty or malformed input, yours almost certainly should too. Inventing a third behavior — and then writing a test that enshrines it — turns a convention miss into a permanent bug.

Delegate broad "how does X work around here" sweeps to an Explore subagent (see fable-delegation) so recon doesn't flood your context with file dumps.

2. Interrogate the request

Restate the user's goal in one sentence — the goal, not the literal instruction. If you can't, you don't understand the task yet.

Then split what you know into three piles:

• Stated requirements — explicit, non-negotiable.
• Assumptions you're making — defaults you chose to fill gaps. Choose sensible ones and state them in your plan and final report rather than asking about each.
• Genuine forks — decisions with materially different outcomes the user would care about (data loss, external behavior, cost, backwards compatibility). These are the only things worth a question. One good question beats five clarifying ones.

3. Verify assumptions against reality

Every assumption that survives unverified becomes a bug. Before committing to a design, check the shaky ones against the actual repo: grep for the symbol, read the function, run the command, check the schema. Special skepticism for:

• API shapes and library behavior recalled from memory (training data is stale)
• "This function is only called from one place"
• "The tests cover this"
• "This config/flag/file still exists"

4. Consequential choices deserve a second candidate

When a design decision is expensive to reverse — schema, public API, architecture, dependency choice — sketch two or three approaches before picking. Compare on: blast radius, reversibility, fit with existing patterns, and whether it can be built in independently verifiable steps. Then pick one and write down why.

The note is not bureaucracy. When you hit friction mid-implementation, it lets you ask the key question: was this friction predicted, or is it evidence the choice was wrong? Predicted friction → push through. Surprise friction → stop and reconsider before sunk cost decides for you.

For routine choices, skip this — one obvious approach, taken quickly, is correct.

5. Decompose into verifiable steps

Order the work so the project compiles and tests pass at as many intermediate points as possible. A plan whose steps can only be verified "at the end" is a plan to debug everything simultaneously. Prefer: extend the seam → add the new path behind it → wire in → remove the old path. Each step is a checkpoint you can retreat to.

Define done before starting: which command will you run, what output proves it works, which behavior will you observe. If you can't name the verification, the task is underspecified — go back to step 2.

6. Keep scope tight

Fix what was asked. When you notice adjacent problems — dead code, a latent bug, missing tests elsewhere — note them in your report or flag them as a separate task; don't fold them silently into the diff. A reviewer who finds unrequested changes must now question every line. Silent scope growth reads as loss of control, even when each change is good.