Scoping Doc — Template

Module 3, Lesson 3.5 deliverable · one doc per feature · concept

How to use this template. Copy this page into your working repo (scoping-doc.md at the repo root is a good place). Fill it out before you write a single prompt for a feature-sized change. Target 200–400 words total. If you are going over, the feature is probably too big for one scoping doc — split it.

You can also ask the agent to produce a first draft of the doc. The prompt is in Lesson 3.5, Block 4. Edit the draft yourself; that is where the real scoping happens.

Each time you complete a feature, save the doc — frozen alongside the code — as part of your capstone log.

Scoping doc — [feature name]

Author

Date

Target session length (hours)

Agent / tool

Section 01 Goal — in one sentence

What will be true at the end that is not true now. Verifiable. Not the feature name; the behavior.

Section 02 Surface area — which files / components this change probably touches

Three or four bullets. Be concrete enough that you will recognize surprises.

If the agent later proposes to touch a file not listed here, it is a scope-creep cue. Either add it here (with reason) or push back.

Section 03 Slices — the sequence of bounded changes that add up to the feature

Scaffold → path-through → polish is the default pattern. Each slice leaves the system in a working state. 3–6 slices is typical.

Slice 01 — scaffold What this slice does:

Verify signal:

Slice 02 — path-through What this slice does:

Verify signal:

Slice 03 What this slice does:

Verify signal:

Slice 04 — polish (if needed) What this slice does:

Verify signal:

Slice 05 — optional What this slice does:

Verify signal:

Section 04 End-to-end verify — how I will know the whole feature is done

The goal from section 1, but operationalized. “Here is what I will run and what I expect to see.”

Section 05 Out of scope — explicitly not in this plan

At least two items. These are the things you will say “no, not this plan” to if the agent suggests them mid-flight.

Section 06 Tripwires I am watching for on this feature

From your tripwire catalog. Which two are most likely to bite on this particular work, and what will you do differently?

Tripwire

How I will neutralize it

Tripwire

How I will neutralize it

Mid-flight rule

You may — and often should — update this doc as you learn during execution. If slice 2 reveals that slice 4 needs a different surface area, update the doc and note why. That is not scope creep; that is honest planning.

The rule is: if the plan changed, it changed on paper. A scoping doc that silently stops matching the work is worse than no scoping doc at all.

Worked example (reference only)

Feature: --dry-run flag on the Module 3 starter repo (tidy.py).

Goal. Running tidy.py --dry-run <dir> prints what the script would do — which files it would move to which subfolders — without actually moving any files.

Surface area. tidy.py (argparse / main), tests/test_tidy.py (new tests). Probably no other files.

Slices.

Slice 1 (scaffold). Add --dry-run flag parsing to the CLI. Thread it as a boolean through sort_files. No behavior change yet. Verify: python tidy.py --dry-run ~/tidy-sandbox still runs and moves files — the flag is parsed but unused.
Slice 2 (path-through). In sort_files, skip the actual shutil.move when dry_run=True. Return the would-be-moved list. Verify: with --dry-run set, no files move; without it, files move as before.
Slice 3 (polish). Print “Would move X → Y” lines instead of “Moved X → Y” when in dry-run mode. Verify: output is visually distinct and accurate.
Slice 4 (tests). Add tests for the no-move invariant under --dry-run, and for the output text. Verify: all tests pass.

End-to-end verify. In a fresh sandbox with 6 files, python tidy.py --dry-run ~/tidy-sandbox prints 6 “Would move” lines and no files move; then python tidy.py ~/tidy-sandbox (no flag) moves all 6 as before.

Out of scope. Color in the output. JSON output mode. Confirmation prompt before moving. A --verbose flag.

Tripwires. (3 — illegible goal) not a risk, goal is concrete. (7 — weak tests) ensure the tests actually check “no files moved,” not just “no error raised.” (8 — session drift) start each slice with a fresh Cowork/Claude Code session and paste this doc at the top.

Checklist before you start coding

I wrote this doc (or edited the agent’s draft). Each slice has a concrete verify signal. Every slice leaves the system in a working state. The out-of-scope list has at least two real items. I have the diff-review checklist ready for each slice. I will commit after every slice. I will start a fresh agent session between slices and re-paste the doc.

When the last box is checked, start slice 1.