08 — Roadmap and backlog

When to read this: After your PRD (and ARCHITECTURE / DESIGN if applicable) are written. This chapter covers the bridge from product intent to actual work items.

Why these two artifacts exist#

The PRD says what you're building and why. The backlog tracks work items and their status. Neither tells you what to ship first. That's ROADMAP's job.

docs/PRD.md         →    what + why
docs/ROADMAP.md     →    order things ship in (2–4 phases)
docs/backlog.md     →    work items + status (tracks reality)
docs/backlog/       →    triaged specs grouped by phase

Each artifact serves a different reader:

• PRD. Read by you (when sharpening scope), agents (when checking scope), and prd-revise (when detecting drift).
• ROADMAP. Read by you (when picking what to do next) and the seed-backlog prompt (when generating items).
• backlog.md + phase files. Read by /pick-next-task, /kickoff-spec, and /ship-spec to track work mechanically.

Drafting the ROADMAP#

The kit ships a prompt at prompts/prompt-roadmap.md that you hand to Claude Code (or Cursor) after your PRD is written. The prompt instructs the agent to:

1. Verify docs/PRD.md exists and is filled in. If it still has {{PLACEHOLDER}} markers, stop.
2. Draft 2–4 phases. Typical names: P0 Setup, P1 Core, P2 Polish, P3 Stretch. Adapt to the project.
3. Each phase must be shippable on its own. Partial value, not partial implementation.
4. Order phases by dependency, not by excitement. Setup before features. Auth before authorized features. Read before write.
5. Pull non-goals verbatim from the PRD into a final "Out of scope for V1" section.

To run it, in the chat:

Read docs/PRD.md and (if it exists) docs/ARCHITECTURE.md, then follow prompts/prompt-roadmap.md to draft docs/ROADMAP.md.

The agent reads PRD (and ARCHITECTURE if present), follows the prompt's structure, and produces a draft.

What a good phase looks like#

## P1: Daily logger
 
**Acceptance criteria:**
- [ ] User can enter today's word count and submit.
- [ ] App stores entries in localStorage with a date key.
- [ ] Today's entry shows on the page after submission.
 
**Depends on:** P0
 
**Out of scope for this phase:** word goals, multi-user, cloud sync, streaks (P2).

Acceptance criteria are testable (you can check them off when met). Dependencies are explicit. Out of scope for this phase is its own line. Phase-level non-goals are different from V1-level non-goals.

What doesn't belong in the ROADMAP#

• Implementation details (file names, function names, library choices). Those live in specs, generated downstream by triage.
• Specific tasks. Tasks live in docs/backlog.md. The ROADMAP is one level coarser.
• Estimates / dates. Unless the PRD explicitly requires them.

If your ROADMAP starts looking like a Gantt chart or a sprint plan, you've gone too granular. Pull back.

Iterating on the draft#

The first draft will probably be 80% right. Common edits:

• Move a capability from P1 into P0 because it turns out to be a dependency.
• Split a phase that has too much in it (>5 acceptance criteria is a smell).
• Merge two phases that aren't actually shippable independently.

When you're happy, commit:

git add docs/ROADMAP.md && git commit -m "docs: draft ROADMAP"

Seeding the backlog#

The kit ships another prompt at prompts/prompt-seed-backlog.md. It populates the Inbox of docs/backlog.md with already-classified items.

In the chat:

Read docs/PRD.md and docs/ROADMAP.md and follow prompts/prompt-seed-backlog.md to populate the Inbox in docs/backlog.md.

The agent generates items in two flavors:

• US-### — User stories. One per user-visible capability in the PRD/ROADMAP.
• TASK-### — Tasks. One per setup/infra item implied by the stack (deps install, env vars, deploy config, CI, tokens, etc.).

There's also a BUG-### prefix for bugs, but you don't have any at seeding time. Bugs only exist once you've shipped something that can break.

Item format (must match /backlog-intake)#

The seeder produces items in the format /backlog-intake would, so /backlog-triage can consume them downstream:

### US-01: User can enter today's word count
 
**As a** writer, **I want** to log today's word count, **so that** I can build a streak record.
 
**Acceptance criteria:**
- [ ] Single numeric input visible on the home view.
- [ ] Submitting the input persists the value to localStorage with today's date as key.
- [ ] After submit, the value displays back in the same view.
 
**Priority:** P0
**Phase:** P1
**Notes:** From PRD §3 capability #1.

### TASK-02: Initialize Vite + React + Tailwind v4
 
**Description:** Scaffold the project shell with the kit's stack: Vite, React, TypeScript, Tailwind v4 with @theme inline tokens.
 
**Acceptance criteria:**
- [ ] `npm run dev` starts a working dev server.
- [ ] Tokens from DESIGN.md are wired into globals.css.
- [ ] `bash scripts/check-tokens.sh` passes on a stub component.
 
**Priority:** P0
**Phase:** P0

Sizing heuristics#

The seed prompt enforces:

• If an item would take >1 day, split it.
• If an item would take <30 minutes, fold it into a parent item.
• Aim for 5–15 items per phase. If the seed produces 25+, the agent over-decomposed.
• One concept per item. If the title needs "and", it's two items.

Inbox grouping#

The seeder groups items in the Inbox under phase headers so triage is easy:

## Inbox
 
### Phase 0 — Setup
- TASK-02: Initialize Vite + React + Tailwind v4
- TASK-03: Wire DESIGN.md tokens into globals.css
 
### Phase 1 — Daily logger
- US-01: User can enter today's word count
- US-02: App stores entry in localStorage with a date key
 
### Phase 2 — Streak
- US-03: App computes consecutive-day streak from localStorage
- US-04: Streak shown prominently above today's entry

Items aren't moved into phase files yet. That's triage's job.

If the PRD is ambiguous, the seeder lists open questions at the bottom of the Inbox under ### Open questions rather than guessing. Resolve those before triage.

Commit:

git add docs/backlog.md && git commit -m "docs: seed backlog"

Spec kinds: ui, backend, infra#

Every triaged spec gets exactly one kind: tag. The kind drives:

1. Which execution skill runs when you /kickoff-spec (or /craft-ui).
2. Which verification gate applies before the spec can ship.

The kind matters because gates aren't substitutable. A green test run doesn't prove a UI is good. A clean visual rubric doesn't prove a backend is correct. You need the right gate for the right work. The kind tag is how the kit picks.

Chapter 10: Verification gates goes deeper on why this distinction is load-bearing.

Edge cases#

• Spec touches both UI and backend. Split it. Two specs (one ui, one backend) are easier to gate correctly than one mixed spec.
• Doc-only changes. No spec needed. Edit the docs in conversation. Specs exist for code changes.
• Bug fixes. Use BUG-###, tag with the kind of code being changed. A UI bug is kind: ui and goes through visual review.
• Refactors that don't change visible behavior. kind: infra typically. They need tests to pass and a smoke check that nothing regressed.

Triaging the backlog with /backlog-triage#

/backlog-triage

The skill walks through each Inbox item and:

1. Asks (or recommends) a kind. Some items are obvious (UI items become ui); others get a recommendation with reasoning.
2. Moves the item from ## Inbox into the right phase file (docs/backlog/phase-N-*.md), creating the file if missing.
3. Tags the spec with the kind in its frontmatter or as a **kind:** line.
4. Flags architecturally loaded items. If an item's resolution requires an architectural decision that isn't in docs/ARCHITECTURE.md, the skill recommends running /architecture-review first and pauses that item rather than triaging it blind.

After triage, your folder structure looks like:

docs/
├── backlog.md                      ← Inbox now mostly empty (or completely empty)
└── backlog/
    ├── phase-0-setup.md            ← TASK-02, TASK-03, TASK-04
    ├── phase-1-logger.md           ← US-01, US-02
    └── phase-2-streak.md           ← US-03, US-04

Each phase file has the spec details, the kind tag, and acceptance criteria. The kit's recommended structure puts each spec in a section like:

## US-01: User can enter today's word count
 
**kind:** ui
**Priority:** P0
 
**As a** writer, **I want** to log today's word count, **so that** I can build a streak record.
 
**Acceptance criteria:**
- [ ] Single numeric input visible on the home view.
- [ ] Submitting the input persists the value to localStorage with today's date as key.
- [ ] After submit, the value displays back in the same view.
 
**Notes:** From PRD §3 capability #1.

Some teams put each spec in its own file under docs/specs/. Both work. The kit's commands look in docs/backlog/phase-*.md by default but can be configured.

Commit:

git add docs/ && git commit -m "docs: triage backlog into phases"

Status markers#

Every spec has a status marker:

The status appears in the phase file's table of contents and is updated by /kickoff-spec (flips to [~]), /ship-spec (flips to [x]), and you (flip to [!] if blocked, with a note explaining why).

Don't manually flip statuses to [~] or [x] if you're using the kit's commands. They manage state, including incrementing per-phase counts. Manual flips silently break the count tracking.

When you need a spec vs. when you don't#

The spec workflow is overkill for tiny changes. Run the spec → kickoff loop only when all three are true:

• Touches code (not docs/planning).
• Has a verifiable "done" (tests, visual rubric, smoke check).
• Would lose context if it sat in the queue for days.

Things that don't need a spec:

• Writing the PRD, drafting the ROADMAP, filling CLAUDE.md placeholders.
• Renaming a folder, one-line config tweaks.
• Updating dependencies. Run the update, run the tests, ship.
• Fixing a typo in a comment.

Do them in conversation. Specs aren't punishment. They're scaffolding. Don't scaffold what doesn't need scaffolding.

/backlog-intake for ad-hoc items#

/backlog-intake is the per-item version of the seed prompt. Use it when an idea arrives mid-build and needs to land in the backlog without disrupting your current work:

/backlog-intake The user mentioned wanting CSV export, eventually

The skill formats the input as a properly structured Inbox item with prefix, title, notes, and a default priority. It doesn't triage. That happens in batches via /backlog-triage.

Useful for capturing context immediately ("the user wanted X, here's why") so it doesn't get lost in chat scrollback. The Inbox accumulates these over time. You triage them in batches, typically before each phase.

Common stumbles#

Continue#

Your backlog is triaged. Next: Chapter 09: The daily loop — actually doing the work.