Scoping and initialization

Skill 01: Scoping & Project Initialization

Purpose: Turn a vague request into a bounded, buildable project with a clear first target. Use when: You are starting anything new, a tool, a feature, a script, a research task, and the end state is fuzzy. Don't use when: The task is already fully specified and you only need to execute (go to implementation-strategy). If the requirements are unclear but the project is already chosen, go to requirements-and-success-criteria.

---

Why this matters

Most low-quality work is not caused by bad coding. It is caused by building the wrong thing, building too much, or building with no idea of when to stop. A weak model or a junior engineer, handed "build me a X," will often start typing immediately, and produce something that technically runs but solves the wrong problem.

Scoping is the cheapest possible place to prevent that. Ten minutes of scoping saves hours of rework. The goal of this skill is to convert an ambiguous ask into one sentence you can build against and a smallest-first version you can finish.

The core principle

You cannot build well what you cannot state in one sentence. If you cannot write the one-sentence version, you do not understand the task yet, and you must not start building. Ambiguity does not disappear when you ignore it; it turns into rework later, at a higher price.

---

The initialization process

Work through these steps in order. Do not skip ahead to setup or code.

Step 1: Restate the request in your own words

Write one paragraph: "As I understand it, the goal is to ___, so that ___. It is done when ___." This forces you to expose your assumptions. If you cannot fill in all three blanks, you have found your first questions.

Step 2: Identify the "job to be done"

Ask: what is the user actually trying to accomplish? The request is a proposed solution; the job is the underlying need. Someone who asks for "a script to rename files" may actually need "a reliable way to organize a photo archive." Solve the job, not just the literal words, but do not silently expand the job either (that is scope creep, see below).

Step 3: Classify the project

Knowing the type of thing you are building sets the right defaults:

Type	Optimize for	First target
Throwaway script / one-off	Speed, correctness on the real input	Working output on the actual data, once
Reusable tool / CLI	Clear interface, good errors, docs	One command working end-to-end
Service / long-running system	Reliability, observability, safety	One request handled correctly, restartable
Library	API clarity, stability, tests	One public function, tested
Research / analysis	Correctness, reproducibility, honesty	One question answered with evidence
Automation / pipeline	Idempotency, failure recovery	One item processed end-to-end

Pick the closest row. It tells you what "good" means before you write anything.

Step 4, Draw the boundary: in / out / later

Write three explicit lists. This single artifact prevents most scope creep.

IN SCOPE (this version must do):
- ...

OUT OF SCOPE (this version will NOT do):
- ...

LATER / MAYBE (good ideas, deliberately deferred):
- ...

Anything not in the IN list is not your problem right now. When you feel the urge to add something, put it in LATER, not IN.

Step 5: Define the smallest useful version (the "walking skeleton")

Identify the thinnest possible slice that is actually usable and demonstrates the whole path working. Not a component in isolation, a complete, tiny end-to-end result. Examples:

• Web app → one page that loads real data and renders it.
• CLI tool → one command that takes real input and prints real output.
• Data pipeline → one record read from source, transformed, written to destination.
• Research → one sub-question answered with one real source.

This is your first milestone. Everything else is added on top of a thing that already works.

Step 6: Surface the unknowns and risks

List what you do not yet know and what could sink the project. Mark each as:

• Blocking: must resolve before building (e.g. "do we even have access to the data?").
• Shapes design: resolve early, it changes the architecture (e.g. "must this handle 10 or 10 million records?").
• Deferrable: can decide later (e.g. "exact color of the button").

Resolve blocking unknowns first. For deep treatment, see risk-identification-and-mitigation.

Step 7: Set up the workspace (minimally)

Only now do you touch tooling. Create the smallest environment that lets you run and verify the walking skeleton:

• A place for the code/work to live.
• A way to run it (even a single command).
• A way to verify it (even a manual check).
• Version control initialized if the work is non-trivial.

Do not scaffold folders, config, and abstractions "for later." Later can scaffold for itself. Setup should serve the walking skeleton and nothing more.

---

Output template: the project brief

Produce this short brief before building. It is your contract with yourself. Keep it to one screen.

PROJECT BRIEF
=============
One-sentence goal: ___
Job to be done:     ___
Project type:       ___ (script / tool / service / library / research / pipeline)

Definition of done (this version):
- [ ] ___
- [ ] ___

In scope:      ___
Out of scope:  ___
Later/maybe:   ___

Walking skeleton (first milestone): ___
Blocking unknowns to resolve first: ___

---

Worked example

Request: "I need something to keep track of my API costs."

Bad start: Immediately create a database schema, a web dashboard, user login, and charts.

Scoped start:

• One-sentence goal: Show me how much I spent on each API this month.
• Job to be done: Avoid surprise bills; know where the money goes.
• Type: Reusable tool (CLI first).
• In scope: Read usage from the provider's export, sum by API, print a table. Out of scope: Live dashboard, alerts, multi-user, historical trends. Later: alerts when a threshold is crossed.
• Walking skeleton: Read one CSV export, print total cost. Then group by API.
• Blocking unknown: Is cost data even available in the export, or only request counts? → Check this first.

The scoped version is finishable today and can be verified against a real bill. The bad start is a week of work that might solve the wrong problem.

---

Common failure modes

Failure	What it looks like	Fix
Skipping straight to code	Typing before the one-sentence goal exists	Write the brief first. No brief, no build.
Scope creep	"While I'm here, I'll also add…"	New ideas go in LATER, never IN.
Gold-plating	Building for imagined future scale/needs	Build for the IN list only.
Boiling the ocean	Trying to build everything before anything works	Ship the walking skeleton first.
Solving the literal words	Missing the real job behind the request	Ask "what are they actually trying to do?"
Analysis paralysis	Endless scoping, never building	Timebox scoping. A good-enough brief beats a perfect one.

Red flags: stop and re-scope

• You cannot write the one-sentence goal.
• Your "first version" has more than ~5 must-haves.
• You are building infrastructure before anything works end-to-end.
• You have added things the user never asked for.
• You do not know how you will verify the result.

Definition of done for this skill

• A one-sentence goal exists and is unambiguous.
• Project type is classified; "good" is defined accordingly.
• In / out / later lists are written.
• A walking skeleton (smallest end-to-end version) is identified.
• Blocking unknowns are listed and being resolved first.
• Workspace is set up only enough to run and verify the skeleton.

See also

• requirements-and-success-criteria, turn the brief into precise, testable requirements.
• planning-and-decomposition, break the scoped project into ordered steps.
• risk-identification-and-mitigation, handle the unknowns you surfaced.