Scoping larger changes.

From bug to feature CORE

The first four lessons have trained a single motion: one bug, one directed edit, one diff. That motion is the atom of Module 3. This lesson is where you learn to assemble atoms into molecules — the kind of change that is too big for a single prompt but still small enough to finish inside a two-hour session.

Feature-sized changes — “add a --dry-run flag,” “add a search box to this page,” “let the user export their data to CSV” — have a structure that single bug fixes do not. They touch multiple files. They usually have multiple parts that have to work together. They often can be broken into a sequence where each step is valuable and each step is easy to verify. That structure is the thing you are going to learn to see.

The skill has an old name: it is the ability to slice a feature. Working programmers slice features every day. You are learning to do it in partnership with an agent — which is a little different from doing it alone, because you are optimizing for what an agent can do well on each slice, and because the ordering decisions carry more weight when every slice lands in an hour instead of a day.

The scoping method CORE

Before you write a single prompt on a feature-sized change, you write a scoping doc. It is usually 200–400 words. It has five parts.

1. The goal, in one sentence. Not “add a search box” — that is the feature name, not the goal. Goal: “From the main page, a user can type into a search box and see a filtered list of only the items whose title or description matches the query, with no full page reload.” The goal is the thing you will check the final behavior against.

2. The surface area. Which files or components you think this change will touch. Three or four bullets. You do not need to be exhaustive; you need to be concrete enough that you’ll recognize surprises when the agent proposes to touch something else. “Main page component, the item list component, the API call in api/items.js, a new state variable in the app’s top-level state. Probably no backend changes — the filtering can happen in the client.” If the agent later proposes a backend change, you’ll notice — because the surface-area note did not mention one.

3. The slices. The sequence of bounded changes that add up to the feature. Each slice is one directed edit. Three to six slices is typical for a feature that fits in a two-to-four-hour session. Each slice should have a verifiable end state — something you can run or see — even if the full feature is not done until the last slice.

4. The verify signal. How you will know, at the end of each slice, that you have built what you said you would. Usually this is a test or a manual check: “slice 3 is done when I can type apple into the search box and the list filters to items with ‘apple’ in the title or description.” Write it down per slice. Vague verify signals are how tripwire 7 (weak tests) sneaks in.

5. The out-of-scope list. Things adjacent to this feature that you are explicitly choosing not to do in this plan. “Not in scope: backend search, highlighting matched terms in results, search history, keyboard shortcuts.” The out-of-scope list is how you neutralize scope creep in advance — when the agent proposes to do one of those things, you have a written-down reason to say no.

Writing the scoping doc takes fifteen to thirty minutes. On a two-hour feature it pays for itself five times over.

Directing across slices CORE

Once you have a scoping doc, the work is a sequence of directed edits. The shape is the same Module 3 motion, with three cross-slice additions.

Reset the agent between slices. Especially for slices 3+, start each slice with a clean context — paste the scoping doc at the top of the prompt so the agent always knows the goal and where this slice fits. This neutralizes tripwire 8 (session drift) across the feature; you are not relying on a three-hour rolling context to hold the plan.

Commit after every slice. Even if the slice is small. Small commits mean each slice’s diff is reviewable on its own, and the recovery path from Lesson 3.4 — revert if something is wrong — stays cheap. Feature branches that land as one massive commit are unreviewable and unrevertable; they are not what this course teaches.

Adjust the plan as you learn. The scoping doc is a first draft, not a contract. If slice 2 reveals that slice 4’s assumption was wrong, update the doc. This is not “scope creep” — it is planning honestly. The difference is whether the change is written down. If you modify the doc and note why, you are still directing. If you just drift, you are not.

When the agent’s first draft of the plan is useful CORE

Here is a small secret: you do not have to write the scoping doc alone. You can get an agent to draft one, and then edit it.

The prompt is: “Here is the feature I want to add: [paragraph]. Here is the codebase structure: [paste or describe]. Propose a scoping doc with goal, surface area, slices, verify signals, and out-of-scope list. Do not write any code yet — just the plan.”

The agent’s first draft will usually be 70% right. It will often get the surface area approximately correct, propose a reasonable slice sequence, and surface at least one out-of-scope candidate you had not thought of. It will also sometimes miss a slice, propose a scope that is too large, or assume a piece of infrastructure that does not exist.

Your job with the agent’s draft is to edit it like you would edit anyone’s first draft. Check each slice against the “stops in a working state” test. Tighten the verify signals where they are vague. Add to the out-of-scope list. Reorder when the slicing is wrong. This takes ten minutes and produces a much better doc than either you or the agent alone.

The fact that an agent can write a first-draft plan is a big deal. It means your scoping muscle is about review and revise, not just blank-page generation — which lowers the cost of the scoping step and makes the scoping doc habit much easier to keep.