What's the recommended GSD workflow for re-slicing a roadmap?

[siraj-samsudeen]

Situation

After executing Phase 1, I realized that phases were too big. My Phase 1 tried to deliver auth + navigation + projects + tasks + deploy all at once. I want to break it into thinner slices (e.g., Phase 1 = just auth + app shell, Phase 2 = projects, Phase 3 = tasks, etc.).

I've already reset to a clean state post phase 1 (post-discussion, pre-research) using tag + soft reset to preserve history. I do have valuable context in phase 1 that i want to preserve.

Question

What's the recommended GSD workflow for restructuring an existing roadmap into thinner phases?

Claude Code is suggesting the following:

• /gsd:remove-phase + /gsd:add-phase — works but tedious for restructuring multiple phases
• /gsd:new-milestone — seems too heavy, I'm not starting a new milestone, just re-slicing the same one
• Edit ROADMAP.md directly — pragmatic but bypasses GSD tracking

Is there a recommended pattern for this? Some specific questions:

1. Should I edit ROADMAP.md directly and then run the normal discuss → research → plan → execute pipeline for each new phase? Or is there a command I'm missing?

2. What happens to existing discussion context? I have 01-CONTEXT.md and 01-DISCUSSION-LOG.md from the original (too-big) Phase 1. Some decisions (auth flow, sidebar layout) still apply to the thinner Phase 1. Others (project list design, task panel) would move to later phases. Should I split the context file, or just re-run /gsd:discuss-phase for each new phase?

3. Phase numbering — if I re-slice Phase 1 into three phases, do the old Phases 2-6 need renumbering? Or should I use decimal numbering (1.1, 1.2, 1.3) to avoid disrupting the existing roadmap structure?

4. Requirements mapping — the existing ROADMAP.md maps requirement IDs to phases. When I re-slice, should I update those mappings first in ROADMAP.md and then let the pipeline flow, or does a GSD command handle re-mapping?

Context

• GSD version: 1.32.0
• Project: greenfield Convex + React app
• Current state: 6-phase roadmap exists, Phase 1 discussion complete, everything else (research, plans, execution) was reset after a failed attempt

[trek-e]

Great questions. Here's the recommended approach for re-slicing a roadmap:

1. Edit ROADMAP.md directly

Yes, edit ROADMAP.md directly. This is the pragmatic and correct approach. GSD tracks state via STATE.md and the phase directory structure — the roadmap is a planning document, not a state machine. After editing:

# Create the new phase directories
/gsd-add-phase 02 projects
/gsd-add-phase 03 tasks
# etc.

Then run the normal pipeline (discuss → research → plan → execute) for each new phase.

2. Existing discussion context

Keep your 01-CONTEXT.md for the thinner Phase 1 — just remove decisions that now belong to later phases. Don't re-run /gsd-discuss-phase for Phase 1 if the remaining decisions are still valid. For new phases (02, 03, etc.), run /gsd-discuss-phase fresh.

3. Phase numbering

Renumber cleanly. GSD supports /gsd-insert-phase for inserting between existing phases, but since you're restructuring everything, clean sequential numbers (01, 02, 03...) are simpler. Your old phases 2-6 content wasn't executed yet, so there's no state to preserve.

4. Requirements mapping

Update the phase_req_ids mappings in ROADMAP.md when you edit it. The planner reads these mappings to scope what each phase covers. Get the mapping right in ROADMAP.md first, then let the pipeline flow.

Summary workflow

1. Edit ROADMAP.md — re-slice phases, update phase_req_ids
2. Keep 01-CONTEXT.md, trim decisions that moved to later phases
3. /gsd-add-phase for each new phase directory
4. Run the normal pipeline per phase

For the commands reference, see COMMANDS.md.

[MicheleBe]

thanks for the explanation. it would be nice to have also a command to help the redesign of the roadmap. I had the same situation, ambitious project and usually gsd try to do it in 10 phases. if you ask him before the ROADMAP is written it can good react and it slices the project nicely, I try several times to slice the roadmap manually, but sometimes i don't get right the dependencies.