GSD roadmaps are designed to evolve. Scope changes, priorities shift, and urgent work emerges. Phase management commands let you adjust your roadmap without rebuilding everything.
Overview
Three commands control roadmap structure:
| Command | Purpose | When to Use |
|---|
/gsd:add-phase | Append to end | Scope grows after initial planning |
/gsd:insert-phase | Insert urgent work | Critical fix needed between phases |
/gsd:remove-phase | Delete and renumber | Descoping a feature |
Adding Phases
Use /gsd:add-phase to append new work to the end of your current milestone.
Basic usage
/gsd:add-phase "Add export to PDF feature"
- Calculate next phase number (ignores decimals)
- Generate slug from description
- Create phase directory
- Update
ROADMAP.md
- Track change in
STATE.md
Example
# ROADMAP.md (before)
## Milestone: v1.0
- [x] Phase 01: User authentication
- [x] Phase 02: Profile management
- [ ] Phase 03: Social features
- [ ] Phase 04: Notification system
/gsd:add-phase "Analytics dashboard"
# ROADMAP.md (after)
## Milestone: v1.0
- [x] Phase 01: User authentication
- [x] Phase 02: Profile management
- [ ] Phase 03: Social features
- [ ] Phase 04: Notification system
- [ ] Phase 05: Analytics dashboard # Added
Phase numbers are always integers. The system ignores any decimal phases when calculating the next number.
Inserting Phases
Use /gsd:insert-phase when urgent work must happen between existing phases.
Why decimal numbering?
Renumbering all phases after an insertion would invalidate:
- Git commits referencing phase numbers
- Discussion in issues/PRs
- Documentation links
- Your mental model
Decimal phases (e.g., 3.1, 3.2) preserve the logical sequence while accommodating urgent insertions.
Basic usage
/gsd:insert-phase 3 "Fix critical auth bug"
Multiple insertions
If phase 3.1 already exists:
/gsd:insert-phase 3 "Another urgent fix"
Example
# ROADMAP.md (before)
- [x] Phase 03: Social features
- [ ] Phase 04: Notification system
/gsd:insert-phase 3 "Fix OAuth token expiration"
# ROADMAP.md (after)
- [x] Phase 03: Social features
- [ ] Phase 3.1: Fix OAuth token expiration # Inserted
- [ ] Phase 04: Notification system
Only insert phases for truly urgent work that can’t wait. Excessive insertions make roadmaps harder to follow.
Removing Phases
Use /gsd:remove-phase to delete unstarted future work and renumber everything after it.
Why renumber?
Removing a phase leaves a gap (Phase 1, 2, 4, 5…). Renumbering maintains clean linear sequence:
Git history preserves the old numbers, so nothing is lost.
Basic usage
GSD will:
- Verify phase 7 hasn’t started
- Delete
.planning/phases/07-phase-name/
- Renumber phases 8+ to 7+
- Update
ROADMAP.md
- Commit with message explaining the change
Example
# ROADMAP.md (before)
- [x] Phase 01: User auth
- [x] Phase 02: Profiles
- [x] Phase 03: Social features
- [ ] Phase 04: Notifications
- [ ] Phase 05: Analytics # Removing this
- [ ] Phase 06: Admin panel
- [ ] Phase 07: API v2
# ROADMAP.md (after)
- [x] Phase 01: User auth
- [x] Phase 02: Profiles
- [x] Phase 03: Social features
- [ ] Phase 04: Notifications
- [ ] Phase 05: Admin panel # Was 06, renumbered
- [ ] Phase 06: API v2 # Was 07, renumbered
Safety check
GSD verifies the phase is in pending status. You cannot remove phases that are in_progress or completed.
Deletion
The phase directory is deleted from disk.
Renumbering
All subsequent phases are renumbered. Directories, file names, and ROADMAP.md entries are updated.
Git commit
Changes are committed with a message documenting the removal. Git history preserves old numbers.
Validation Rules
Add phase
- ✅ Roadmap must exist
- ✅ Description must be provided
- ✅ Current milestone must be active
Insert phase
- ✅ Target phase must exist
- ✅ Target phase must be an integer (not 3.1)
- ✅ Description must be provided
Remove phase
- ✅ Phase must exist
- ✅ Phase must be
pending (not started)
- ✅ Phase cannot be the last remaining phase
Roadmap Evolution Tracking
All phase management operations update STATE.md with evolution history:
## Roadmap Evolution
- 2024-03-15: Added Phase 05 "Analytics dashboard"
- 2024-03-16: Inserted Phase 3.1 "Fix OAuth token expiration" after Phase 03
- 2024-03-17: Removed Phase 06 "Social sharing" (descoped)
Best Practices
Adding Phases
Inserting Phases
Removing Phases
Do:
- Add phases when scope grows organically
- Keep descriptions clear and specific
- Discuss with team before expanding scope
Don’t:
- Add phases to avoid proper planning
- Create phases for work better suited to
/gsd:quick
- Add so many phases that the milestone becomes unwieldy
When to add:
- User feedback reveals must-have feature
- Technical discovery shows additional work needed
- Stakeholder requests aligned with milestone goals
Do:
- Insert only truly urgent work
- Keep insertions rare (preserves roadmap clarity)
- Document why the insertion was necessary
Don’t:
- Insert phases for “nice to have” work
- Use insertions to avoid waiting for next phase
- Create long chains (3.1, 3.2, 3.3, 3.4…)
When to insert:
- Critical production bug discovered
- Security vulnerability needs immediate fix
- Blocker preventing next phase from starting
Do:
- Remove descoped work cleanly
- Understand that renumbering is safe
- Commit removals with clear messages
Don’t:
- Remove phases you might need later (consider deferring to next milestone instead)
- Remove phases to “clean up” completed work (they’re your history)
- Remove last phase without adding replacement
When to remove:
- Feature no longer needed
- Work duplicates another phase
- Milestone scope being trimmed
Common Patterns
Urgent fix during execution
# You're executing phase 5
/gsd:execute-phase 5
# Production breaks - OAuth tokens expiring early
# This must be fixed before phase 6 (which depends on auth)
/gsd:insert-phase 5 "Fix OAuth token expiration"
/gsd:discuss-phase 5.1
/gsd:plan-phase 5.1
/gsd:execute-phase 5.1
# Now resume planned work
/gsd:execute-phase 6
Scope creep management
# Stakeholder: "Can we add real-time notifications?"
# Option 1: Add to current milestone (if time allows)
/gsd:add-phase "Real-time notification system"
# Option 2: Defer to next milestone (recommended)
/gsd:add-todo "Real-time notifications for v2.0"
Descoping to meet deadline
# Milestone has 12 phases, deadline approaching
# Phases 10-12 are nice-to-have
/gsd:remove-phase 10 # Renumbers 11-12 to 10-11
/gsd:remove-phase 10 # Renumbers 11 to 10
/gsd:remove-phase 10 # Removes last phase
# Now milestone is achievable with 9 phases
Integration with Other Commands
After adding phases
/gsd:add-phase "New feature"
# Normal workflow
/gsd:discuss-phase 8
/gsd:plan-phase 8
/gsd:execute-phase 8
After inserting phases
/gsd:insert-phase 4 "Critical fix"
# Complete the inserted phase first
/gsd:plan-phase 4.1
/gsd:execute-phase 4.1
# Then resume planned phases
/gsd:execute-phase 5
After removing phases
/gsd:remove-phase 7
# Continue with renumbered phases
/gsd:execute-phase 7 # This is the old phase 8
Phase Numbering Reference
Integer phases
- Sequential: 1, 2, 3, 4, 5…
- Represent planned work from roadmap
- Created during
/gsd:new-project or /gsd:add-phase
Decimal phases
- Format:
{integer}.{decimal} (e.g., 3.1, 3.2)
- Represent urgent insertions
- Created with
/gsd:insert-phase
- Not counted when calculating “next phase number”
Example roadmap
Phase 01: Foundation
Phase 02: Core features
Phase 03: User system
Phase 3.1: Fix auth bug # Inserted
Phase 3.2: Fix token refresh # Inserted
Phase 04: Social features
Phase 4.1: Fix privacy leak # Inserted
Phase 05: Notifications
Phase 06: Analytics
/gsd:add-phase creates Phase 07, not 06 (ignores decimals). 