Specs and Planning Templates

Ambiguity in → invented requirements out. Fill one of these before a large agent session. See Specs Over Prompts and Writing Effective Specs.

New project brief

Use before scaffolding. Forces problem, users, constraints, and non-goals so the agent doesn't invent a product.

# Project brief — <Name>

## Problem
<Who hurts, how often, what they do today.>

## Users
- Primary: `<role>` — success looks like: `<…>`
- Secondary: `<…>`

## Proposed solution (one paragraph)
<What we will build — not a feature list.>

## Constraints
- Timeline: `<date / weeks>`
- Team: `<N engineers + agent usage>`
- Stack preferences / mandates: `<…>`
- Compliance / data residency: `<…>`

## Non-goals
- `<explicitly out of v1>`

## Success metrics
- `<measurable outcome for v1>`

## Open questions
- [ ] `<question>` — owner `<name>` — decide by `<date>`

MVP spec

Use for the first shippable slice. Every acceptance criterion must be falsifiable. Pair with MVP Build.

# MVP spec — <Product>

## Goal
<One sentence: what ships and to whom.>

## In scope
- `<capability>`
- `<capability>`

## Out of scope
- `<explicit cut>`

## User flows
1. `<happy path steps>`
2. `<critical edge / failure path>`

## Acceptance criteria
- [ ] `<observable behavior>`
- [ ] `<observable behavior>`
- [ ] `<error / empty state behavior>`

## Data model (sketch)
- `<Entity>`: fields `<…>`; relations `<…>`

## Tech constraints
- Stack: `<…>`
- Hosting: `<…>`
- Must integrate with: `<…>` / must not: `<…>`

## Verification
- Manual: `<smoke script>`
- Automated: `<minimum test bar>`

Feature spec

Use for any non-trivial change into an existing codebase. Name blast radius and files the agent may touch.

# Feature spec — <Title>

Status: `<draft | approved>` · Owner: `<name>` · Spec path: `docs/specs/<file>`

## Problem
<Current behavior and why it is insufficient.>

## Goal
<User-visible outcome in one sentence.>

## Non-goals
- `<…>`

## Acceptance criteria
- [ ] `<…>`
- [ ] `<…>`

## UX / API contract
- UI: `<screens / empty / error states>`
- API: `<method path>` request `<shape>` → response `<shape>` · errors `<codes>`

## Blast radius
- May edit: `<paths / packages>`
- Must not edit: `<paths>`
- Migrations: `<none | expand-only | …>`

## Dependencies & risks
- Depends on: `<ADR / service / feature flag>`
- Risk: `<…>` — mitigation: `<…>`

## Verification
- Tests to add/update: `<…>`
- Manual checks: `<…>`

Bug report

Use before "fix this." Agents without repro invent causes. Prefer failing test or scripted repro.

# Bug — <Short title>

Severity: `<S1–S4>` · Environment: `<prod / staging / local>` · First seen: `<date>`

## Summary
<One sentence.>

## Repro steps
1. `<…>`
2. `<…>`
3. `<…>`

## Expected
`<…>`

## Actual
`<…>` · Evidence: `<log snippet / screenshot path / trace id>`

## Scope
- Suspected area: `<path / service>`
- User impact: `<who / how many>`

## Constraints for the fix
- Do not: `<drive-by refactors, API breaks>`
- Must include: regression test that fails without the fix

## Related
- Issue / PR: `<…>`

Refactor plan

Use for behavior-preserving change. If behavior changes, write a feature spec instead. Pair with Legacy Refactor.

# Refactor plan — <Title>

## Motivation
<Pain: build time, coupling, duplicated logic — with evidence.>

## Invariants (must not change)
- External API: `<unchanged contracts>`
- Observable behavior: `<list or "all existing tests pass">`
- Data: `<no migration | migration plan>`

## Target design
<End state in 5–10 lines or link to ARCHITECTURE section.>

## Steps (each independently mergeable)
1. `<step>` — verify: `<tests / checks>`
2. `<step>` — verify: `<…>`
3. `<step>` — verify: `<…>`

## Blast radius
- Touch: `<paths>`
- Do not touch: `<paths>`

## Rollback
`<revert PR / feature flag / dual-run>`

## Done when
- [ ] All listed invariants hold
- [ ] No net new public surface unless listed

Task breakdown

Use after a spec is approved. Each task should fit one focused agent session with a clear verify step.

# Task breakdown — <Spec title>

Spec: `docs/specs/<file>` · Owner: `<name>`

| ID | Task | Depends on | Owner (human/agent) | Verify |
|---|---|---|---|---|
| T1 | `<…>` | — | agent | `<test / command>` |
| T2 | `<…>` | T1 | agent | `<…>` |
| T3 | `<…>` | T1 | human | `<review gate>` |

## Parallelism
- Can run together: `<T2 ∥ T4 if…>`
- Must be serial: `<…>`

## Out of this breakdown
- `<explicitly deferred>`

Sprint plan

Use when a team runs agents on a cadence. Make agent capacity and human review load explicit.

# Sprint plan — <Team> — <dates>

## Goal
<One outcome for the sprint, not a laundry list.>

## Capacity
- Humans (review / decide): `<N person-days>`
- Agent implementation budget: `<rough sessions or story points>`
- Hard deadline: `<date>` — reason: `<…>`

## Committed work
| Item | Spec / link | Owner | Reviewer | Done = |
|---|---|---|---|---|
| `<…>` | `docs/specs/…` | `<…>` | `<…>` | `<AC or checklist>` |

## Explicit cuts
- `<item>` — why cut: `<…>`

## Risks
- `<risk>` — trigger: `<…>` — response: `<…>`

## Rituals
- Spec freeze: `<date>`
- Mid-sprint recovery buffer: `<hours reserved for agent mess>`

Related

• Specs Over Prompts — why specs beat chat
• Writing Effective Specs — quality bar
• Spec Examples — worked examples
• Keeping Specs Alive — avoid stale specs
• Idea to Spec — playbook that uses these
• Templates index