Project Scoping - Wupxy Docs

Scoping is the step most likely to be skipped and most likely to cause failure. A well-scoped brief produces faster, more verifiable output. A vague brief produces confident-looking output that solves the wrong problem.

The scoping document

Every non-trivial task should have a brief before implementation starts. Keep it short — the goal is clarity, not documentation overhead.

## Task: [short name]

**Outcome:** What the world looks like when this is done.

**In scope:**
- [specific thing 1]
- [specific thing 2]

**Out of scope:**
- [thing that might seem related but is not included]

**Done when:**
- [ ] [verifiable condition 1]
- [ ] [verifiable condition 2]

**Validation method:** [how to confirm it's done: test command, visual check, diff review]

**Risk:** [anything that could go wrong or needs attention]

Outcome vs. output

The outcome is what changes. The output is what gets produced. Always scope to the outcome.

Weak scope (output)	Strong scope (outcome)
“Write a component"	"Users can submit the form without the page refreshing"
"Fix the bug"	"The sidebar renders correctly at 768px viewport width"
"Add a new page"	"The docs navigation shows the Tools tab with three sub-pages”

Scope signals that indicate a problem

Before handing off, check for these red flags:

The scope has no done criteria

If you can’t write at least one verifiable done condition, the scope is still a goal, not a task. Break it into tasks with checkable conditions.

The scope has more than 3 main outcomes

Tasks with many outcomes tend to produce partial work on all of them instead of complete work on any one. Split into sequential tasks.

The scope references files or modules without checking they exist

File paths go stale. Confirm the target files are where expected before the brief is finalized.

The done criteria are subjective

“Looks good” or “feels right” are not checkable. Replace with observable states: “test passes”, “console shows no errors”, “component matches the design spec”.

Scoping for AI agents

When the implementer is an AI agent (Claude Code, Codex), add two additional constraints to the brief: Boundary statement: Explicit list of what the agent should not touch. AI agents tend to over-reach when scope is ambiguous — they’ll refactor adjacent code, fix unrelated issues, and expand the surface area of the change. Verification method: The specific command or output the agent should use to confirm its work. Agents need a concrete signal, not a human judgment.

**Agent boundary:** Touch only these files: [list]. Do not refactor adjacent code.

**Agent verification:** Run `[test command]` and return the output. Work is done when the output shows [expected state].

Sizing a task

Use this heuristic to decide when to split:

Scope size	Indicator	Action
Small	1 file, 1 outcome, done in under 30 min	Hand off directly
Medium	2-3 files, 1-2 outcomes, done in 1-2h	Brief + single agent run
Large	Multiple files, 3+ outcomes, 3h+	Split into sequential tasks with checkpoints
Epic	Multiple sessions, architectural change	Break into medium tasks, scope each separately

Delivery Checklist

Use the delivery checklist before pushing a completed task.

​The scoping document

​Outcome vs. output

​Scope signals that indicate a problem

​Scoping for AI agents