Phase Management

Adding, inserting, and removing phases from your roadmap

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"

GSD will:

1. Calculate next phase number (ignores decimals)
2. Generate slug from description
3. Create phase directory
4. Update ROADMAP.md
5. 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"

This inserts phase 3.1 after phase 3.

Multiple insertions

If phase 3.1 already exists:

/gsd:insert-phase 3 "Another urgent fix"

GSD creates phase 3.2 (next available decimal).

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:

• Phase 1, 2, 3, 4, 5

Git history preserves the old numbers, so nothing is lost.

Basic usage

/gsd:remove-phase 7

GSD will:

1. Verify phase 7 hasn’t started
2. Delete .planning/phases/07-phase-name/
3. Renumber phases 8+ to 7+
4. Update ROADMAP.md
5. 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

/gsd:remove-phase 5

# 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

1. Safety check

   GSD verifies the phase is in pending status. You cannot remove phases that are in_progress or completed.

2. Deletion

   The phase directory is deleted from disk.

3. Renumbering

   All subsequent phases are renumbered. Directories, file names, and ROADMAP.md entries are updated.

4. 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)

This provides audit trail for scope changes.

Best Practices

Adding 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

Inserting Phases

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

Removing Phases

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

Next /gsd:add-phase creates Phase 07, not 06 (ignores decimals).