> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/gsd-build/get-shit-done/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
/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

```markdown theme={null}
# ROADMAP.md (before)
## Milestone: v1.0

- [x] Phase 01: User authentication
- [x] Phase 02: Profile management  
- [ ] Phase 03: Social features
- [ ] Phase 04: Notification system
```

```bash theme={null}
/gsd:add-phase "Analytics dashboard"
```

```markdown theme={null}
# 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
```

<Info>
  Phase numbers are always integers. The system ignores any decimal phases when calculating the next number.
</Info>

## 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

```bash theme={null}
/gsd:insert-phase 3 "Fix critical auth bug"
```

This inserts phase **3.1** after phase 3.

### Multiple insertions

If phase 3.1 already exists:

```bash theme={null}
/gsd:insert-phase 3 "Another urgent fix"
```

GSD creates phase **3.2** (next available decimal).

### Example

```markdown theme={null}
# ROADMAP.md (before)
- [x] Phase 03: Social features
- [ ] Phase 04: Notification system
```

```bash theme={null}
/gsd:insert-phase 3 "Fix OAuth token expiration"
```

```markdown theme={null}
# ROADMAP.md (after)  
- [x] Phase 03: Social features
- [ ] Phase 3.1: Fix OAuth token expiration  # Inserted
- [ ] Phase 04: Notification system
```

<Warning>
  Only insert phases for **truly urgent** work that can't wait. Excessive insertions make roadmaps harder to follow.
</Warning>

## 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

```bash theme={null}
/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

```markdown theme={null}
# 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
```

```bash theme={null}
/gsd:remove-phase 5
```

```markdown theme={null}
# 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
```

<Steps>
  <Step title="Safety check">
    GSD verifies the phase is in `pending` status. You cannot remove phases that are `in_progress` or `completed`.
  </Step>

  <Step title="Deletion">
    The phase directory is deleted from disk.
  </Step>

  <Step title="Renumbering">
    All subsequent phases are renumbered. Directories, file names, and ROADMAP.md entries are updated.
  </Step>

  <Step title="Git commit">
    Changes are committed with a message documenting the removal. Git history preserves old numbers.
  </Step>
</Steps>

## 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:

```markdown theme={null}
## 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

<Tabs>
  <Tab title="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
  </Tab>

  <Tab title="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
  </Tab>

  <Tab title="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
  </Tab>
</Tabs>

## Common Patterns

### Urgent fix during execution

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
/gsd:add-phase "New feature"

# Normal workflow
/gsd:discuss-phase 8
/gsd:plan-phase 8
/gsd:execute-phase 8
```

### After inserting phases

```bash theme={null}
/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

```bash theme={null}
/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).