skills/planning/SKILL.md

name, description

name	description
planning	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:

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

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

# 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:

// 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):

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