From f34fd45a1844155f99cb87e86f423f256826788d Mon Sep 17 00:00:00 2001
From: Lex Christopherson <lex@glittercowboy.com>
Date: Mon, 5 Jan 2026 12:15:48 -0600
Subject: [PATCH] feat(08-01): clarify create-milestone.md file locations with
 explicit instructions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Added "File to update: .planning/ROADMAP.md" directive to update_roadmap step
- Structured update process as numbered steps (1. Milestones section, 2. Phase details, 3. Progress table)
- Verified complete-milestone.md archival logic already correct
- Pattern established: active milestone → ROADMAP.md, shipped milestone → milestones/vX.Y-ROADMAP.md
---
 get-shit-done/workflows/create-milestone.md | 26 ++++++++++++++-------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/get-shit-done/workflows/create-milestone.md b/get-shit-done/workflows/create-milestone.md
index 921552e62..e9b9e58a3 100644
--- a/get-shit-done/workflows/create-milestone.md
+++ b/get-shit-done/workflows/create-milestone.md
@@ -195,18 +195,28 @@ If "adjust": Ask what to change, revise, present again.
 </step>
 
 <step name="update_roadmap">
-Update `.planning/ROADMAP.md` with new milestone:
+Write new milestone details to `.planning/ROADMAP.md`.
 
-**Add to Milestones section (if exists):**
+**File to update:** `.planning/ROADMAP.md`
+
+The main ROADMAP.md file holds full phase details for the active milestone. Archive files in `milestones/` are created only when a milestone ships (via `/gsd:complete-milestone`).
+
+**Process:**
+
+**1. Update Milestones section:**
+
+Add the new milestone to the milestones list. Completed milestones show as links to their archive files, new milestone shows as in-progress.
 
 ```markdown
 ## Milestones
 
-- ✅ **v1.0 [Previous]** - Phases 1-9 (shipped YYYY-MM-DD)
+- ✅ **v1.0 [Previous]** - [link to milestones/v1.0-ROADMAP.md] (Phases 1-9, shipped YYYY-MM-DD)
 - 🚧 **v[X.Y] [Name]** - Phases [N]-[M] (in progress)
 ```
 
-**Add to Phases section:**
+**2. Add full phase details:**
+
+Write complete phase sections for all phases in this milestone. Each phase gets full details including goal, dependencies, research assessment, and plan placeholders.
 
 ```markdown
 ### 🚧 v[X.Y] [Name] (In Progress)
@@ -222,7 +232,6 @@ Update `.planning/ROADMAP.md` with new milestone:
 **Plans**: TBD
 
 Plans:
-
 - [ ] [N]-01: TBD (run /gsd:plan-phase [N] to break down)
 
 #### Phase [N+1]: [Name]
@@ -233,15 +242,14 @@ Plans:
 **Plans**: TBD
 
 Plans:
-
 - [ ] [N+1]-01: TBD
 
-[... continue for all phases ...]
+[... continue for all phases in this milestone ...]
 ```
 
-**Update Progress table:**
+**3. Update Progress table:**
 
-Add new phases with milestone column:
+Add rows for all new phases with milestone attribution.
 
 ```markdown
 | Phase         | Milestone | Plans | Status      | Completed |