Planning and decomposition

Skill 03: High-Quality Planning & Decomposition

Purpose: Break a project into an ordered sequence of small, verifiable steps that each leave the work in a better, still-working state. Use when: You have clear requirements and the work is more than a few minutes of effort. Don't use when: The task is a single trivial change (just do it). For open-ended "what should we even build" problems, scope first with scoping-and-initialization.

---

Why this matters

A plan is how you make a big, scary task into a series of small, boring ones. Weak models and junior engineers fail on large tasks not because any single step is hard, but because they hold the whole thing in their head at once, lose track, and produce a tangled half-finished mess. A written plan externalizes the work so you can execute one small piece at a time and always know where you are.

Good decomposition also front-loads the risky and the unknown, so you discover problems while they are cheap to fix instead of at the end.

The core principle

Every step should end with something you can verify, and the system should work after each step: not only at the end. You are not slicing the project into "layers to assemble later"; you are slicing it into thin, complete increments, each of which is a small working improvement over the last.

---

The decomposition process

Step 1: Start from the walking skeleton

Your first task is always: make the thinnest end-to-end version work (from scoping-and-initialization). Not "set up the database," not "build all the models", a complete, tiny path from input to output. This de-risks the whole architecture immediately.

Step 2: Slice vertically, not horizontally

• Horizontal (bad): "Build all the data models," then "build all the logic," then "build all the UI." Nothing works until the very end; integration problems appear all at once.
• Vertical (good): "Make feature A work end-to-end," then "make feature B work end-to-end." Each slice is demonstrable and testable on its own.

Prefer vertical slices. Each should be independently valuable and verifiable.

Step 3: Right-size each task

A good task is:

• Small: completable in one focused sitting; if you can't hold it in your head, split it.
• Single-purpose: it does one thing. "Add X and refactor Y and fix Z" is three tasks.
• Verifiable: it ends with a check you can run (a test, a command, a manual observation).
• Ordered: its prerequisites come before it.

Rule of thumb: if a task's description needs the word "and," consider splitting it.

Step 4: Order by dependency and risk

Two ordering forces:

1. Dependencies: you cannot do B before A if B needs A. Draw the arrows.
2. Risk: do the scariest, most uncertain thing as early as dependencies allow. If something might make the whole approach impossible ("can this library even do X?"), find out on day one with a tiny spike, not on day ten.

When dependencies allow a choice, do the risky thing first.

Step 5: Mark verification points

For each task, write how you will know it worked before you start it. This is the task's own acceptance check. It prevents the "I think it's done" trap and connects to self-verification.

Step 6: Keep the plan visible and alive

Write the plan down as a checklist. Work the list top to bottom. As you learn, update the plan: cross off done items, add discovered ones, re-order if reality demands. A plan is a living tool, not a one-time prediction. A stale plan is worse than none.

---

Task template

TASK: <verb-first, one sentence>
Depends on: <prior tasks or "nothing">
Why now:    <dependency / risk reason>
Done when:  <the check that proves it, test, command output, observation>
Risk:       <low / medium / high, and what could go wrong>

Plan template

GOAL: <one sentence from the brief>

MILESTONE 1, Walking skeleton: <thinnest end-to-end thing that works>
  [ ] T1: ...  (done when: ...)
  [ ] T2: ...  (done when: ...)

MILESTONE 2: <next vertical slice>
  [ ] T3: ...  (done when: ...)

RISKS / SPIKES (do early):
  [ ] S1: prove <uncertain thing> works with a 30-minute experiment

DEFERRED (not now): ...

---

Decision aid: how deep should the plan be?

Situation	Planning depth
Trivial change, understood fully	No written plan; just do it.
Small task, one sitting, low risk	3–5 line checklist.
Medium task, several steps or some unknowns	Full plan with milestones + verification points.
Large / unfamiliar / high-risk / multi-session	Full plan plus early spikes for each major unknown; revisit the plan at each milestone.

Match effort to stakes. Over-planning a tiny task is as wasteful as under-planning a big one.

---

Worked example

Goal: A CLI that summarizes API costs from a CSV export (from Skill 01's example).

Bad plan (horizontal):

1. Build full CSV parser for all formats.
2. Build cost model for every provider.
3. Build reporting/formatting layer.
4. Wire it all together. ← everything breaks here, at the end.

Good plan (vertical, risk-first):

• Spike (risk-first): Confirm the export actually contains cost, not just counts. (30 min, if it doesn't, the whole project changes.)
• Milestone 1, skeleton: Read one hard-coded CSV, print the grand total. (Done when: total matches a hand-calculation on a 3-row file.)
• Milestone 2: Group by API and print a per-API table. (Done when: sums per API match the sample.)
• Milestone 3: Accept the filename as an argument; handle "file not found" and empty file cleanly. (Done when: all three inputs behave per the acceptance sheet.)
• Deferred: thresholds/alerts, multiple months.

After every milestone, the tool runs and does something correct. You are never more than one small step from a working state.

---

Common failure modes

Failure	Fix
Horizontal layering	Slice vertically; each slice works end-to-end.
Giant vague tasks ("build the backend")	Split until each task is one sitting, one purpose.
Leaving the risky part for last	Spike unknowns first, while they're cheap.
No verification per step	Every task states "done when …".
Plan never updated	Treat the plan as living; revise as you learn.
Planning forever, never building	Timebox planning; a good plan executed beats a perfect plan unwritten.
Building integration only at the end	Integrate from the first milestone (skeleton).

Red flags: stop and re-plan

• A task can't be checked when it's "done."
• You're building layer 3 and nothing has run end-to-end yet.
• The biggest unknown is scheduled for last.
• You've lost track of what's done and what's left (the plan isn't written down).
• A single "task" would take more than a focused sitting.

Definition of done for this skill

• The plan starts with a walking skeleton.
• Work is sliced vertically into small, single-purpose, ordered tasks.
• Each task has a "done when" verification check.
• Risky/unknown items are scheduled early as spikes.
• The plan is written down as a living checklist.

See also

• scoping-and-initialization, source of the goal and the skeleton.
• implementation-strategy, how to execute the plan well.
• long-horizon-project-management, planning across many sessions.
• risk-identification-and-mitigation, choosing what to spike first.