---
name: planning-and-task-breakdown
description:
  Breaks work into ordered tasks. Use when you have a spec or clear requirements
  and need to break work into implementable tasks. Use when a task feels too
  large to start, when you need to estimate scope, or when parallel work is
  possible.
---

# Planning and Task Breakdown

> **Scope note.** This skill is a generic planning discipline — it
> teaches how to slice and order work into verifiable units, independent
> of any particular ticket hierarchy. The word "task" below refers to a
> generic unit of work, not specifically to a Mandrel ticket. Under
> Mandrel's 3-tier hierarchy (Epic → Feature → Story), these units map
> onto acceptance/verification bullets inlined on the Story body, or
> onto sequential sibling Stories. The principles — vertical slicing,
> dependency ordering, sizing caps, explicit acceptance and
> verification — apply uniformly.

## Policy Capsule

- Enter Plan Mode before writing any code: read the spec + relevant codebase, map dependencies, list risks. Planning output is a plan document, not implementation.
- Slice work **vertically** — one user-visible path per task — not horizontally (all DB, then all API, then all UI).
- Every task carries: a one-paragraph description, explicit acceptance criteria, a verification step (test/build/manual check), declared dependencies, files-likely-touched, and an estimated scope (XS–L).
- Cap individual tasks at scope **M** (3–5 files) where possible and never start an **XL** task — break it down further. Triggers for further decomposition: >2 hours of agent work, >3 acceptance bullets, two independent subsystems touched, or "and" in the title.
- Order tasks by dependency graph (foundations first) and by risk (high-risk tasks early to fail fast).
- Insert explicit checkpoints every 2–3 tasks: tests pass, build clean, end-to-end flow works, human review before proceeding.
- Distinguish parallelization classes — safe (independent slices, docs), must-be-sequential (migrations, shared state), and needs-coordination (shared API contract — define the contract first).
- Capture risks + mitigations and any open questions for human input as first-class plan sections.
- Do not start implementation until every task has acceptance criteria, a verification step, ordered dependencies, and human approval of the plan.

## Overview

Decompose work into small, verifiable tasks with explicit acceptance criteria.
Good task breakdown is the difference between an agent that completes work
reliably and one that produces a tangled mess. Every task should be small enough
to implement, test, and verify in a single focused session.

## When to Use

- You have a spec and need to break it into implementable units
- A task feels too large or vague to start
- Work needs to be parallelized across multiple agents or sessions
- You need to communicate scope to a human
- The implementation order isn't obvious

**When NOT to use:** Single-file changes with obvious scope, or when the spec
already contains well-defined tasks.

## The Planning Process

### Step 1: Enter Plan Mode

Before writing any code, operate in read-only mode:

- Read the spec and relevant codebase sections
- Identify existing patterns and conventions
- Map dependencies between components
- Note risks and unknowns

**Do NOT write code during planning.** The output is a plan document, not
implementation.

### Step 2: Identify the Dependency Graph

Map what depends on what:

```text
Database schema
    │
    ├── API models/types
    │       │
    │       ├── API endpoints
    │       │       │
    │       │       └── Frontend API client
    │       │               │
    │       │               └── UI components
    │       │
    │       └── Validation logic
    │
    └── Seed data / migrations
```

Implementation order follows the dependency graph bottom-up: build foundations
first.

### Step 3: Slice Vertically

Instead of building all the database, then all the API, then all the UI — build
one complete feature path at a time:

**Bad (horizontal slicing):**

```text
Task 1: Build entire database schema
Task 2: Build all API endpoints
Task 3: Build all UI components
Task 4: Connect everything
```

**Good (vertical slicing):**

```text
Task 1: User can create an account (schema + API + UI for registration)
Task 2: User can log in (auth schema + API + UI for login)
Task 3: User can create a task (task schema + API + UI for creation)
Task 4: User can view task list (query + API + UI for list view)
```

Each vertical slice delivers working, testable functionality.

### Step 4: Write Tasks

Each task follows this structure:

```markdown
## Task [N]: [Short descriptive title]

**Description:** One paragraph explaining what this task accomplishes.

**Acceptance criteria:**

- [ ] [Specific, testable condition]
- [ ] [Specific, testable condition]

**Verification:**

- [ ] Tests pass: `npm test -- --grep "feature-name"`
- [ ] Build succeeds: `npm run build`
- [ ] Manual check: [description of what to verify]

**Dependencies:** [Task numbers this depends on, or "None"]

**Files likely touched:**

- `src/path/to/file.ts`
- `tests/path/to/test.ts`

**Estimated scope:** [Small: 1-2 files | Medium: 3-5 files | Large: 5+ files]
```

### Step 5: Order and Checkpoint

Arrange tasks so that:

1. Dependencies are satisfied (build foundation first)
2. Each task leaves the system in a working state
3. Verification checkpoints occur after every 2-3 tasks
4. High-risk tasks are early (fail fast)

Add explicit checkpoints:

```markdown
## Checkpoint: After Tasks 1-3

- [ ] All tests pass
- [ ] Application builds without errors
- [ ] Core user flow works end-to-end
- [ ] Review with human before proceeding
```

## Task Sizing Guidelines

| Size   | Files | Scope                                 | Example                              |
| ------ | ----- | ------------------------------------- | ------------------------------------ |
| **XS** | 1     | Single function or config change      | Add a validation rule                |
| **S**  | 1-2   | One component or endpoint             | Add a new API endpoint               |
| **M**  | 3-5   | One feature slice                     | User registration flow               |
| **L**  | 5-8   | Multi-component feature               | Search with filtering and pagination |
| **XL** | 8+    | **Too large — break it down further** | —                                    |

If a task is L or larger, it should be broken into smaller tasks. An agent
performs best on S and M tasks.

**When to break a task down further:**

- It would take more than one focused session (roughly 2+ hours of agent work)
- You cannot describe the acceptance criteria in 3 or fewer bullet points
- It touches two or more independent subsystems (e.g., auth and billing)
- You find yourself writing "and" in the task title (a sign it is two tasks)

## Plan Document Template

```markdown
# Implementation Plan: [Feature/Project Name]

## Overview

[One paragraph summary of what we're building]

## Architecture Decisions

- [Key decision 1 and rationale]
- [Key decision 2 and rationale]

## 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: ...
- [ ] Task 6: ...

### 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]
```

## Parallelization Opportunities

When multiple agents or sessions are available:

- **Safe to parallelize:** Independent feature slices, tests for
  already-implemented features, documentation
- **Must be sequential:** Database migrations, shared state changes, dependency
  chains
- **Needs coordination:** Features that share an API contract (define the
  contract first, then parallelize)

## Common Rationalizations

| Rationalization                | Reality                                                                                      |
| ------------------------------ | -------------------------------------------------------------------------------------------- |
| "I'll figure it out as I go"   | That's how you end up with a tangled mess and rework. 10 minutes of planning saves hours.    |
| "The tasks are obvious"        | Write them down anyway. Explicit tasks surface hidden dependencies and forgotten edge cases. |
| "Planning is overhead"         | Planning is the task. Implementation without a plan is just typing.                          |
| "I can hold it all in my head" | Context windows are finite. Written plans survive session boundaries and compaction.         |

## Red Flags

- Starting implementation without a written task list
- Tasks that say "implement the feature" without acceptance criteria
- No verification steps in the plan
- All tasks are XL-sized
- No checkpoints between tasks
- Dependency order isn't considered

## Verification

Before starting implementation, confirm:

- [ ] Every task has acceptance criteria
- [ ] Every task has a verification step
- [ ] Task dependencies are identified and ordered correctly
- [ ] No task touches more than ~5 files
- [ ] Checkpoints exist between major phases
- [ ] The human has reviewed and approved the plan
