msd-core/get-shit-done/workflows/create-roadmap.md

Define the phases of implementation. Each phase is a coherent chunk of work that delivers value. Phases map to requirements — every v1 requirement must belong to exactly one phase.

The roadmap provides structure, not detailed tasks. But it ensures no requirements are orphaned and validates coverage before planning begins.

<required_reading> Read these files NOW:

1. ~/.claude/get-shit-done/templates/roadmap.md
2. ~/.claude/get-shit-done/templates/state.md
3. ~/.claude/get-shit-done/templates/requirements.md
4. .planning/PROJECT.md
5. .planning/REQUIREMENTS.md
6. .planning/research/SUMMARY.md (if exists) </required_reading>

Load and parse REQUIREMENTS.md:

cat .planning/REQUIREMENTS.md

Extract:

• All v1 requirement IDs (AUTH-01, CONT-02, etc.)
• Requirement categories (Authentication, Content, Social, etc.)
• Total count of v1 requirements

Requirements loaded:

Categories: [N]
- Authentication: [X] requirements
- Content: [Y] requirements
- Social: [Z] requirements
...

Total v1 requirements: [N]

All requirements must map to exactly one phase.

Track requirement IDs — will verify coverage after phase identification.

```bash cat .planning/PROJECT.md 2>/dev/null || echo "No brief found" ```

If no brief exists: Ask: "No brief found. Want to create one first, or proceed with roadmap?"

If proceeding without brief, gather quick context:

• What are we building?
• What's the rough scope?

Check for project research:

[ -d .planning/research ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"

If RESEARCH_EXISTS:

Read .planning/research/SUMMARY.md and extract:

• Suggested phase structure from "Implications for Roadmap" section
• Research flags for each suggested phase
• Key findings that inform phase ordering

Research found. Using findings to inform roadmap:

Suggested phases from research:
1. [Phase from research] — [rationale]
2. [Phase from research] — [rationale]
3. [Phase from research] — [rationale]

Research confidence: [HIGH/MEDIUM/LOW]

Proceeding with research-informed phase identification...

If NO_RESEARCH:

Continue without research context. Phase identification will rely on PROJECT.md only.

Note: Research is optional. Roadmap can be created without it, but research-informed roadmaps tend to have better phase structure and fewer surprises.

Derive phases from requirements. Each phase covers a coherent set of requirements.

Primary input: REQUIREMENTS.md

• Group requirements by natural delivery boundaries
• Each phase should complete one or more requirement categories
• Dependencies between requirements inform phase ordering

Secondary inputs:

• Research SUMMARY.md (if exists): suggested phases, architecture patterns

Phase identification process:

1. Group requirements by category (Authentication, Content, Social, etc.)
2. Identify dependencies between categories (Social needs Content, Content needs Auth)
3. Create phases that complete entire categories where possible
4. Split large categories across phases if needed (e.g., basic auth vs. advanced auth)
5. Assign every v1 requirement to exactly one phase

For each phase, record:

• Phase name and goal
• Which requirement IDs it covers (e.g., AUTH-01, AUTH-02, AUTH-03)
• Dependencies on other phases

Check depth setting:

cat .planning/config.json 2>/dev/null | grep depth

<depth_guidance> Depth controls compression tolerance, not artificial inflation.

Depth	Typical Phases	Typical Plans/Phase	Tasks/Plan
Quick	3-5	1-3	2-3
Standard	5-8	3-5	2-3
Comprehensive	8-12	5-10	2-3

Key principle: Derive phases from actual work. Depth determines how aggressively you combine things, not a target to hit.

• Comprehensive auth system = 8 phases (because auth genuinely has 8 concerns)
• Comprehensive "add favicon" = 1 phase (because that's all it is)

For comprehensive depth:

• Don't compress multiple features into single phases
• Each major capability gets its own phase
• Let small things stay small—don't pad to hit a number
• If you're tempted to combine two things, make them separate phases instead

For quick depth:

• Combine related work aggressively
• Focus on critical path only
• Defer nice-to-haves to future milestones </depth_guidance>

Phase Numbering System:

Calculate starting phase number:

# Find highest existing phase number from phases/ directory
ls -d .planning/phases/[0-9]*-* 2>/dev/null | sort -V | tail -1 | grep -oE '[0-9]+' | head -1

• If phases/ is empty or doesn't exist: start at Phase 1
• If phases exist from previous milestone: continue from last + 1
• Example: v1.0 had phases 1-4, v1.1 starts at Phase 5

Use integer phases (1, 2, 3) for planned milestone work.

Use decimal phases (2.1, 2.2) for urgent insertions:

• Decimal phases inserted between integers (2.1 between 2 and 3)
• Mark with "(INSERTED)" in phase title
• Created when urgent work discovered after planning
• Examples: bugfixes, hotfixes, critical patches

When to use decimals:

• Urgent work that can't wait for next milestone
• Critical bugs blocking progress
• Security patches needing immediate attention
• NOT for scope creep or "nice to haves" (capture with /gsd:add-todo instead)

Phase execution order: Numeric sort: 1 → 1.1 → 1.2 → 2 → 2.1 → 3

Deriving phases:

1. List all distinct systems/features/capabilities required
2. Group related work into coherent deliverables
3. Each phase should deliver ONE complete, verifiable thing
4. If a phase delivers multiple unrelated capabilities: split it
5. If a phase can't stand alone as a complete deliverable: merge it
6. Order by dependencies

Good phases are:

• Coherent: Each delivers one complete, verifiable capability
• Sequential: Later phases build on earlier
• Independent: Can be verified and committed on its own

Common phase patterns:

• Foundation → Core Feature → Enhancement → Polish
• Setup → MVP → Iteration → Launch
• Infrastructure → Backend → Frontend → Integration

**For each phase, derive what must be TRUE when it completes.**

This catches scope gaps before planning begins. Requirements tell us what to build; success criteria tell us what users can do.

Process for each phase:

1. State the phase goal (from identify_phases)

2. Ask: "What must be TRUE for users when this phase completes?"

   • Think from user's perspective, not implementation
   • 2-5 observable behaviors per phase
   • Each should be testable/verifiable

3. Cross-check against mapped requirements:

   • Does each success criterion have at least one requirement supporting it?
   • Does each requirement contribute to at least one success criterion?

4. Flag gaps:

   • Success criterion with no supporting requirement → Add requirement or mark as out of scope
   • Requirement that supports no criterion → Question if it belongs in this phase

Example:

Phase 2: Authentication
Goal: Users can securely access their accounts

Success Criteria (what must be TRUE):
1. User can create account with email/password
2. User can log in and stay logged in across browser sessions
3. User can log out from any page
4. User can reset forgotten password

Requirements mapped: AUTH-01, AUTH-02, AUTH-03

Cross-check:
✓ Criterion 1 ← AUTH-01 (create account)
✓ Criterion 2 ← AUTH-02 (log in) — but "stay logged in" needs session persistence
✓ Criterion 3 ← AUTH-03 (log out)
✗ Criterion 4 ← No requirement covers password reset

Gap found: Password reset not in requirements.
→ Add AUTH-04: User can reset password via email
   OR mark "Password reset" as v2 scope

Present to user:

Phase success criteria derived:

Phase 1: Foundation
Goal: Project scaffolding and configuration
Success criteria:
  1. Project builds without errors
  2. Development server runs locally
  3. CI pipeline passes
Requirements: SETUP-01, SETUP-02 ✓ (all criteria covered)

Phase 2: Authentication
Goal: Users can securely access their accounts
Success criteria:
  1. User can create account with email/password
  2. User can log in and stay logged in across sessions
  3. User can log out from any page
  4. User can reset forgotten password ⚠️
Requirements: AUTH-01, AUTH-02, AUTH-03
Gap: Criterion 4 (password reset) has no requirement

Phase 3: User Profile
...

---

⚠️ 1 gap found in Phase 2

Options:
1. Add AUTH-04 for password reset
2. Mark password reset as v2 scope
3. Adjust success criteria

Resolve all gaps before proceeding.

Success criteria flow downstream:

• Written to ROADMAP.md (high-level, user-observable)
• Inform must_haves derivation in plan-phase (concrete artifacts/wiring)
• Verified by verify-phase after execution

**Verify all v1 requirements are mapped to exactly one phase.**

Compare assigned requirements against full list from load_requirements step:

Requirement Coverage:

✓ AUTH-01 → Phase 1
✓ AUTH-02 → Phase 1
✓ AUTH-03 → Phase 1
✓ AUTH-04 → Phase 1
✓ PROF-01 → Phase 2
✓ PROF-02 → Phase 2
...

Coverage: [X]/[Y] requirements mapped

If any requirements unmapped:

⚠️ Orphaned requirements (not in any phase):

- NOTF-01: User receives in-app notifications
- NOTF-02: User receives email for new followers

These v1 requirements have no phase. Options:
1. Add phase to cover them
2. Move to v2 (update REQUIREMENTS.md)
3. Assign to existing phase

Use AskUserQuestion to resolve orphaned requirements.

Do not proceed until coverage = 100%.

```bash cat .planning/config.json 2>/dev/null ``` Note: Config may not exist yet (project initialization). If missing, default to interactive mode. ``` ⚡ Auto-approved: Phase breakdown ([N] phases)

1. [Phase name] - [goal]
2. [Phase name] - [goal]
3. [Phase name] - [goal]

Proceeding to research detection...

Proceed directly to detect_research_needs step.
</if>

<if mode="interactive" OR="missing OR custom with gates.confirm_phases true">
Present the phase breakdown inline:

"Here's how I'd break this down:

1. [Phase name] - [goal]
2. [Phase name] - [goal]
3. [Phase name] - [goal]
   ...

Does this feel right? (yes / adjust)"

If "adjust": Ask what to change, revise, present again.
</step>

<step name="decision_gate">
<if mode="yolo">

⚡ Auto-approved: Create roadmap with [N] phases

Proceeding to create .planning/ROADMAP.md...

Proceed directly to create_structure step.
</if>

<if mode="interactive" OR="missing OR custom with gates.confirm_roadmap true">
Use AskUserQuestion:

- header: "Ready"
- question: "Ready to create the roadmap, or would you like me to ask more questions?"
- options:
  - "Create roadmap" - I have enough context
  - "Ask more questions" - There are details to clarify
  - "Let me add context" - I want to provide more information

Loop until "Create roadmap" selected.
</step>

<step name="create_structure">
```bash
mkdir -p .planning/phases

Use template from `~/.claude/get-shit-done/templates/roadmap.md`.

Initial roadmaps use integer phases (1, 2, 3...). Decimal phases added later via /gsd:insert-phase command (if it exists).

Write to .planning/ROADMAP.md with:

• Phase list with names and one-line descriptions
• Dependencies (what must complete before what)
• Requirement mappings (which REQ-IDs each phase covers):

  ### Phase 1: Authentication
  **Goal**: Secure user authentication
  **Depends on**: Nothing (first phase)
  **Requirements**: AUTH-01, AUTH-02, AUTH-03, AUTH-04
  

• Status tracking (all start as "not started")

Create phase directories:

mkdir -p .planning/phases/01-{phase-name}
mkdir -p .planning/phases/02-{phase-name}
# etc.

Update REQUIREMENTS.md traceability section with phase mappings:

Read current REQUIREMENTS.md and update the Traceability table:

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| AUTH-01 | Phase 1 | Pending |
| AUTH-02 | Phase 1 | Pending |
| AUTH-03 | Phase 1 | Pending |
| AUTH-04 | Phase 1 | Pending |
| PROF-01 | Phase 2 | Pending |
...

**Coverage:**
- v1 requirements: [X] total
- Mapped to phases: [X]
- Unmapped: 0 ✓

Write updated REQUIREMENTS.md.

Create or update STATE.md — the project's living memory.

[ -f .planning/STATE.md ] && echo "STATE_EXISTS" || echo "NEW_STATE"

If STATE_EXISTS: Update Current Position and keep Accumulated Context. If NEW_STATE: Create fresh using template from ~/.claude/get-shit-done/templates/state.md.

Write to .planning/STATE.md:

# Project State

## Project Reference

See: .planning/PROJECT.md (updated [today's date])

**Core value:** [Copy Core Value from PROJECT.md]
**Current focus:** Phase 1 — [First phase name]

## Current Position

Phase: 1 of [N] ([First phase name])
Plan: Not started
Status: Ready to plan
Last activity: [today's date] — Project initialized

Progress: ░░░░░░░░░░ 0%

## Performance Metrics

**Velocity:**
- Total plans completed: 0
- Average duration: —
- Total execution time: 0 hours

**By Phase:**

| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| — | — | — | — |

**Recent Trend:**
- Last 5 plans: —
- Trend: —

## Accumulated Context

### Decisions

Decisions are logged in PROJECT.md Key Decisions table.
Recent decisions affecting current work:

(None yet)

### Pending Todos

None yet.

### Blockers/Concerns

None yet.

## Session Continuity

Last session: [today's date and time]
Stopped at: Project initialization complete
Resume file: None

Key points:

• Project Reference points to PROJECT.md for full context
• Claude reads PROJECT.md directly for requirements, constraints, decisions
• This file will be read first in every future operation
• This file will be updated after every execution

Commit roadmap with requirement mappings:

git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
git add .planning/phases/
git commit -m "$(cat <<'EOF'
docs: create roadmap ([N] phases, [X] requirements)

[One-liner from PROJECT.md]

Phases:
1. [phase-name]: [requirements covered]
2. [phase-name]: [requirements covered]
3. [phase-name]: [requirements covered]

All v1 requirements mapped to phases.
EOF
)"

Confirm: "Committed: docs: create roadmap ([N] phases, [X] requirements)"

``` Project initialized: - Brief: .planning/PROJECT.md - Roadmap: .planning/ROADMAP.md - State: .planning/STATE.md - Committed as: docs: initialize [project] ([N] phases)

---

▶ Next Up

Phase 1: [Name] — [Goal from ROADMAP.md]

/gsd:discuss-phase 1 — gather context and clarify approach

<sub>/clear first → fresh context window</sub>

---

Also available:

• /gsd:plan-phase 1 — skip discussion, plan directly
• Review roadmap

---

</step>

</process>

<phase_naming>
Use `XX-kebab-case-name` format:
- `01-foundation`
- `02-authentication`
- `03-core-features`
- `04-polish`

Numbers ensure ordering. Names describe content.
</phase_naming>

<anti_patterns>
- Don't add time estimates
- Don't create Gantt charts
- Don't add resource allocation
- Don't include risk matrices
- Don't impose arbitrary phase counts (let the work determine the count)

Phases are buckets of work, not project management artifacts.
</anti_patterns>

<success_criteria>
Roadmap is complete when:
- [ ] REQUIREMENTS.md loaded and parsed
- [ ] All v1 requirements mapped to exactly one phase (100% coverage)
- [ ] **Success criteria derived** for each phase (2-5 observable behaviors)
- [ ] **Success criteria cross-checked** against requirements (no gaps)
- [ ] `.planning/ROADMAP.md` exists with requirement mappings and success criteria
- [ ] `.planning/STATE.md` exists (project memory initialized)
- [ ] REQUIREMENTS.md traceability section updated
- [ ] Phases defined with clear names (count derived from requirements, not imposed)
- [ ] **Research flags assigned** (Likely/Unlikely for each phase)
- [ ] **Research topics listed** for Likely phases
- [ ] Phase directories created
- [ ] Dependencies noted if any
- [ ] Status tracking in place
</success_criteria>