Plan

Planning and Task Breakdown

Decompose work into small, verifiable tasks with explicit acceptance criteria — each small enough to implement, test, and verify in one focused session.

Use when: a spec needs breaking into implementable units; a task feels too large or vague to start; work could be parallelized across agents/sessions; scope must be communicated to a human; implementation order isn't obvious. NOT for: single-file changes with obvious scope, or specs that already contain well-defined tasks.

Step 0: Required Reading (blocking, before any breakdown)

Planning is read-only — the output is a plan document, never code.

1. references/SKILL.md — doc index; route to every reference relevant to the request.
2. references/development/conventions.md — any plan whose tasks touch code must respect it.
3. references/development/architecture.md — the layer map and the content-collection contract; a task that changes the schema changes every case study.

Skipping Step 0 is a planning failure — restart here. Docs drift: grep any file/route/ flag a doc names before building on it.

No references/SKILL.md? The reference layer isn't set up here — skip Step 0 and plan from the codebase itself. Say so at the top of the run. Don't invent a reference doc, and don't halt over its absence. /setup builds it, in either mode.

Step 1: Break the Request Down

Slice vertically — each task delivers one complete, testable path, not one layer:

• Bad (horizontal): Task 1 entire schema → Task 2 all endpoints → Task 3 all UI → Task 4 connect.
• Good (vertical): Task 1 user can register (schema + API + UI) → Task 2 user can log in → Task 3 user can create an item → each slice works and is testable on its own.

Split until every task passes "Small Enough" (below).

Step 2: Define What Each Task Is

Answer "this task is for what?" before planning how:

• Categorize: bug fix / feature / refactor / data / ops / doc.
• Define the underlying thing. "Fix this bug" is not a definition — a bug task states observed behavior, expected behavior, and suspected cause. Cause unknown → diagnosis is its own first task; the fix is a later task.
• Expand hidden multiplicity. One user sentence often hides several tasks: a "bug" needing a store + API + UI change is a plan of tasks, not a task. Never compress a multi-task problem into one task to keep the list short.

Can't categorize and define it in two sentences → not understood yet; go back to Step 0/1.

Step 3: Build the Logic Map

Two relations, stated for every task:

Dependencies — what must exist before what; build bottom-up:

Content schema (src/content.config.ts)
    │
    ├── Content entries (src/content/projects/*.mdx)
    │       │
    │       └── Page / route (src/pages, src/pages/project/[...slug].astro)
    │               │
    │               └── Layout (src/layouts/BaseLayout.astro)
    │                       │
    │                       └── Component (src/components)
    │                               │
    │                               └── Design tokens (src/styles/global.css)
    │
    └── Assets (src/assets/images — optimised; public/ — served raw)

Not every plan spans all layers — a UI-only task starts mid-graph; whatever layers the plan touches, build the lower one first.

Conflicts — dependency-free tasks can still collide. Check every pair for shared: file, store/state, API contract, DB table, doc. Shared surface → order them, or pin the shared contract first.

The logic map is what proves N subtasks won't step on each other. "No dependencies, no shared surfaces" is a claim — verify it against the codebase, don't assume it.

Step 4: Schedule — Sequential or Parallel

• Sequential (default): dependency chains, shared-state changes, DB migrations, any pair with a conflict edge.
• Parallel (only when the map proves no conflict): independent vertical slices, tests for already-implemented behavior, documentation.
• Contract-first parallel: tasks sharing an API/store contract may parallelize only AFTER a task pins the contract down.

Order the sequential spine: dependencies satisfied → each task leaves the system in a working state → high-risk/high-unknown tasks early (fail fast) → checkpoint after every 2–3 tasks (tests pass, build clean, flow works end-to-end, human review before proceeding).

Step 5: Expectations and Review Checks

Written before building, per task:

• Expectation — observable behavior that didn't exist before ("user taps X and sees Y"), not implementation ("add function Z").
• Acceptance criteria — ≤3 specific, testable conditions.
• Review check — how the builder verifies: command to run, flow to drive, value to observe. This makes "does the build match our goal?" answerable during the build.

Step 6: Reuse Review — Compare Plan Against Codebase

Walk every task: does the codebase already do this? Search existing components, composables, stores, endpoints, utilities — route through references/SKILL.md and the feature docs, which record what's already built.

• Plan needs A, B, C and feature A exists → the plan includes existing A (naming where it lives) and builds only B and C.
• Partial coverage → the task becomes "extend X", not "build X".
• Record results in the plan's Reuse table. Duplication costs tokens twice — build and upkeep. New code proposed without naming what was searched = incomplete plan.

"Small Enough" — the Definition

All six must hold; fail any one → break it down further:

1. ≤5 files touched (M size or below)
2. One subsystem — not two independent ones (e.g. auth AND billing)
3. ≤3 acceptance criteria describe it completely
4. One focused session — ~≤2 h agent work, survives no session boundary
5. One working state — ends with the system building and behaving; one commit's worth
6. No "and" in the title — that's two tasks

Agents perform best on S and M. L must be justified; XL is never a task, only a phase.

Task Template

## Task [N]: [Short descriptive title — no "and"]

**Category:** [bug fix | feature | refactor | data | ops | doc]

**Description:** One paragraph: what this task is for (the "what" from Step 2).

**Expectation:** Observable behavior after this task that didn't exist before.

**Acceptance criteria:**
- [ ] [Specific, testable condition]
- [ ] [Specific, testable condition]

**Review check (how the builder verifies):**
- [ ] Tests pass: [command]
- [ ] Build succeeds: [command]
- [ ] Manual check: [flow to drive, value to observe]

**Dependencies:** [Task numbers, or "None"]

**Shared surfaces:** [files/stores/contracts shared with other tasks, or "None"]

**Reuses:** [existing component/store/endpoint this builds on, or "None — searched: <terms>"]

**Files likely touched:**
- `src/path/to/file`

**Estimated scope:** [XS | S | M | L]

Output: One Plan Doc Under references/

The plan is a single file in references/, named by comparing the work to what's already in the codebase:

• references/build-<slug>.md — builds or adds a new feature/capability the codebase doesn't have yet.
• references/refact-<slug>.md — refactors or updates existing code — adds no new concept, or only a minimal one. Covers restructuring AND most bug fixes (a fix corrects existing behavior; it doesn't introduce a new concept).
• references/<slug>.md (no prefix) — doesn't clearly fit either bucket.

The task checklist lives inside the plan doc — no separate todo file. Downstream tooling (/build, later sessions) reads this doc directly by path. After writing it:

1. Keep its Status line current (PLANNED → IN PROGRESS → SHIPPED).

Plan Document Template

# Implementation Plan: [Feature/Project Name]

**Status:** PLANNED (not started) <!-- → IN PROGRESS → SHIPPED -->

## Overview
[One paragraph summary of what we're building, and what kind of work it is]

## References Read (Step 0)
- [reference docs consulted, per references/SKILL.md routing]

## Architecture Decisions
- [Key decision 1 and rationale]
- [Key decision 2 and rationale]

## Reuse (Step 6)
| Plan needs | Already exists? | Where | Action |
|---|---|---|---|
| [capability] | Yes / Partial / No | [file/doc] | Reuse / Extend / Build |

## Logic Map (Step 3)
[Dependency graph + conflict notes: which tasks share files/stores/contracts]

## Execution Schedule (Step 4)
- Sequential spine: [task order]
- Parallelizable: [task groups proven conflict-free, or "none"]

## Task List

### Phase 1: Foundation
- [ ] Task 1: ...
- [ ] Task 2: ...

### Checkpoint: Foundation
- [ ] Tests pass, builds clean

### Phase 2: Core Features
- [ ] Task 3: ...
- [ ] Task 4: ...

### Checkpoint: Core Features
- [ ] End-to-end flow works

### Phase 3: Polish
- [ ] Task 5: ...

### Checkpoint: Complete
- [ ] All acceptance criteria met
- [ ] Ready for review

## Risks and Mitigations
| Risk | Impact | Mitigation |
|------|--------|------------|
| [Risk] | [High/Med/Low] | [Strategy] |

## Open Questions
- [Question needing human input]

Verification (before implementation starts)

• Step 0 reading done; references listed in the plan
• Every task has a category and a defined "what" (Step 2)
• Every task has an expectation, acceptance criteria, and a review check (Step 5)
• Logic map covers all dependencies AND shared surfaces (Step 3)
• Schedule marks sequential vs parallel, with justification (Step 4)
• Reuse table filled — every "Build" row states what was searched (Step 6)
• Every task passes the "small enough" definition
• Checkpoints exist between major phases
• The human has reviewed and approved the plan

See Also

Acceptance criteria are per-task ("did we build the right thing?") and sit on top of the project-wide Definition of Done, the standing bar every task clears before it counts as done. See references/SKILL.md § Standing rules where that exists; with no reference layer, the standing bar is whatever the codebase's own tests and build already enforce.

Last Updated: 2026-08-18