skills/planning/SKILL.md

---
name: planning
description: Decompose work into small, verifiable, ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable units.
---

# Planning and Task Breakdown

## Overview

Good task breakdown is the difference between reliable delivery and a tangled mess. Every task should be small enough to implement, test, and verify in a single focused session.

**Input:** A spec (load `spec-driven-dev` skill) or clear requirements.

**Output:** A prioritized, ordered list of tasks with acceptance criteria and verification steps.

## When to Use

- You have a spec and need to break it into implementable units
- A task feels too large or vague to start
- You need to communicate scope to Mathias
- The implementation order isn't obvious
- You want to identify parallelization opportunities

**When NOT to use:** Single-file changes with obvious scope.

## The Planning Process

### Step 1: Read-Only Discovery

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

- Read the spec and relevant code
- Identify existing patterns, conventions, and infrastructure
- Map dependencies between components
- Note risks and unknowns

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

### Step 2: Map the Dependency Graph

Visualize what depends on what:

```
Database schema / migrations
    │
    ├── Domain types (pure Go structs + interfaces)
    │       │
    │       ├── Service layer (business logic)
    │       │       │
    │       │       └── HTTP handlers
    │       │
    │       └── Store implementations (postgres, in-memory)
    │
    └── Seed data / test fixtures
```

**Build foundations first.** You can't test a handler before the service exists. You can't write a service before the domain types are defined.

### Step 3: Slice Vertically

Build one complete feature path at a time, not one layer at a time.

**Bad (horizontal slicing):**
```
Task 1: Write all database migrations
Task 2: Write all store implementations
Task 3: Write all service methods
Task 4: Write all handlers
```
No working software until Task 4. If Task 1 is wrong, you discover it late.

**Good (vertical slicing):**
```
Task 1: User can create an account (migration + store + service + handler for create)
Task 2: User can log in (auth store + service + handler)
Task 3: User can view their invoices (query + service + handler + response type)
```
Each task delivers working, testable functionality. If Task 1 reveals a design issue, Tasks 2+ can adapt.

### Step 4: Write Tasks

Each task follows this structure:

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

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

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

**Verification:**
- [ ] Tests pass: `go test -run TestFeatureName ./...`
- [ ] Build: `go build ./...`
- [ ] Manual check: [description if needed]

**Dependencies:** Task [N-1], Task [N-2] (or "None")

**Files likely touched:**
- `internal/domain/user.go`
- `internal/store/user_store.go`
- `internal/service/user_service.go`

**Estimated scope:** [XS/S/M/L]
```

### Step 5: Order and Add Checkpoints

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

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

- [ ] `go test ./...` passes
- [ ] `go build ./...` succeeds
- [ ] Core user flow works end-to-end (can register and log in)
- [ ] Mathias reviews before continuing
```

## Task Sizing Guidelines

| Size | Files | Scope | Example |
|------|-------|-------|---------|
| **XS** | 1 | Single function or type | Add a validation rule to User |
| **S** | 1–2 | One endpoint or store method | Add GetByEmail to UserStore |
| **M** | 3–5 | One feature slice | User registration (domain + store + service + handler) |
| **L** | 5–8 | Multi-component feature | Search with filtering, pagination, and sorting |
| **XL** | 8+ | **Too large — break it down** | — |

**Break any XL task into smaller tasks.** An agent performs best on XS, S, and M tasks.

**Break a task down further when:**
- It would take more than 2–3 hours of focused work
- The acceptance criteria have more than 4 bullet points
- It touches two independent subsystems (auth AND billing in the same task)
- You find yourself writing "and" in the task title

## Plan Document Template

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

## Overview
[One paragraph: what we're building and the key technical decisions]

## Architecture Decisions
- [Decision 1 and rationale]
- [Decision 2 and rationale]

## Dependency Graph
[Diagram or list showing what depends on what]

## Task List

### Phase 1: Foundation

- [ ] **Task 1:** [Title] — [Scope: XS/S/M]
  - AC: [criteria]
  - Verify: `go test -run TestX ./...`
  - Files: [list]

- [ ] **Task 2:** [Title] — [Scope: XS/S/M]
  ...

### Checkpoint: Foundation Complete
- [ ] `go test ./...` passes
- [ ] Build clean
- [ ] Foundation behavior works end-to-end

### Phase 2: Core Features

- [ ] **Task 3:** [Title] — [Scope: S/M]
  ...

### Checkpoint: Core Features Complete
- [ ] User-facing scenarios work
- [ ] Mathias reviews before Phase 3

### Phase 3: Polish and Edge Cases

- [ ] **Task 5:** Handle [edge case]
- [ ] **Task 6:** [Performance/error handling]

### Checkpoint: Complete
- [ ] All acceptance criteria from the spec are met
- [ ] `go test -race ./...` passes
- [ ] govulncheck passes
- [ ] Ready for review

## Risks and Mitigations

| Risk | Impact | Mitigation |
|------|--------|-----------|
| [External API behavior unknown] | High | Spike task first |
| [Data volume may be larger than expected] | Medium | Add pagination before shipping |

## Open Questions
- [Question requiring Mathias's input]
```

## Parallelization

When working in parallel (multiple sessions or agents):

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

## Go-Specific Planning Notes

### Database First, Then Domain

If the feature requires a schema change:
1. Write and apply migration first
2. Generate sqlc code (`task generate` or `sqlc generate`)
3. Then write domain types and service

### Interface Contracts Before Parallel Work

If two tasks depend on a shared interface:
```go
// Define this first, in its own task
type InvoiceStore interface {
    Save(ctx context.Context, inv Invoice) error
    GetByID(ctx context.Context, id InvoiceID) (Invoice, error)
}
```

Then write the postgres implementation and the service in parallel.

### Spike Tasks for Unknowns

If a risk involves an unknown (new API, unfamiliar library, performance unknown):

```markdown
## Task 0 (Spike): Validate Bankgirot API integration

**Description:** Verify we can submit an ISO 20022 message to Bankgirot sandbox.
**Timebox:** 2 hours
**Output:** Working code or decision to change approach
**Not:** Production-quality code — throw it away after learning
```

Spikes are timeboxed explorations. The code is thrown away. The learning is kept.

## Verification Before Starting

Before beginning implementation:

- [ ] 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
- [ ] Mathias has reviewed and approved the plan

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "I'll figure it out as I go" | That's how you end up with rework. 10 minutes of planning saves hours. |
| "The tasks are obvious" | Write them down. Explicit tasks surface hidden dependencies. |
| "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. |

## Cross-References

- Requires: `spec-driven-dev` skill output
- During implementation: load `tdd` skill per task
- For large refactoring tasks: load `refactoring` skill
- For architecture decisions: load `solid` skill