transition

<required_reading> **Read these files NOW:** 1. `.gsd/STATE.md` 2. `.gsd/PROJECT.md` 3. `.gsd/ROADMAP.md` 4. Current phase's plan files (`*-PLAN.md`) 5. Current phase's summary files (`*-SUMMARY.md`) </required_reading> <purpose> Mark current phase complete and advance to next. This is the natural point where progress tracking and PROJECT.md evolution happen. "Planning next phase" = "current phase is done" </purpose> <process> <step name="load_project_state" priority="first"> Before transition, read project state: ```bash cat .gsd/STATE.md 2>/dev/null cat .gsd/PROJECT.md 2>/dev/null ``` Parse current position to verify we're transitioning the right phase. Note accumulated context that may need updating after transition. </step> <step name="verify_completion"> Check current phase has all plan summaries: ```bash ls .gsd/phases/XX-current/*-PLAN.md 2>/dev/null | sort ls .gsd/phases/XX-current/*-SUMMARY.md 2>/dev/null | sort ``` **Verification logic:** - Count PLAN files - Count SUMMARY files - If counts match: all plans complete - If counts don't match: incomplete <config-check> ```bash cat .gsd/config.json 2>/dev/null ``` </config-check> **If all plans complete:** <if mode="yolo"> ``` ⚡ Auto-approved: Transition Phase [X] → Phase [X+1] Phase [X] complete — all [Y] plans finished. Proceeding to mark done and advance... ``` Proceed directly to cleanup_handoff step. </if> <if mode="interactive" OR="custom with gates.confirm_transition true"> Ask: "Phase [X] complete — all [Y] plans finished. Ready to mark done and move to Phase [X+1]?" Wait for confirmation before proceeding. </if> **If plans incomplete:** **SAFETY RAIL: always_confirm_destructive applies here.** Skipping incomplete plans is destructive — ALWAYS prompt regardless of mode. Present: ``` Phase [X] has incomplete plans: - {phase}-01-SUMMARY.md ✓ Complete - {phase}-02-SUMMARY.md ✗ Missing - {phase}-03-SUMMARY.md ✗ Missing ⚠️ Safety rail: Skipping plans requires confirmation (destructive action) Options: 1. Continue current phase (execute remaining plans) 2. Mark complete anyway (skip remaining plans) 3. Review what's left ``` Wait for user decision. </step> <step name="cleanup_handoff"> Check for lingering handoffs: ```bash ls .gsd/phases/XX-current/.continue-here*.md 2>/dev/null ``` If found, delete them — phase is complete, handoffs are stale. </step> <step name="update_roadmap"> Update the roadmap file: ```bash ROADMAP_FILE=".gsd/ROADMAP.md" ``` Update the file: - Mark current phase: `[x] Complete` - Add completion date - Update plan count to final (e.g., "3/3 plans complete") - Update Progress table - Keep next phase as `[ ] Not started` **Example:** ```markdown ## Phases - [x] Phase 1: Foundation (completed 2025-01-15) - [ ] Phase 2: Authentication ← Next - [ ] Phase 3: Core Features ## Progress | Phase | Plans Complete | Status | Completed | | ----------------- | -------------- | ----------- | ---------- | | 1. Foundation | 3/3 | Complete | 2025-01-15 | | 2. Authentication | 0/2 | Not started | - | | 3. Core Features | 0/1 | Not started | - | ``` </step> <step name="archive_prompts"> If prompts were generated for the phase, they stay in place. The `completed/` subfolder pattern from create-meta-prompts handles archival. </step> <step name="evolve_project"> Evolve PROJECT.md to reflect learnings from completed phase. **Read phase summaries:** ```bash cat .gsd/phases/XX-current/*-SUMMARY.md ``` **Assess requirement changes:** 1. **Requirements validated?** - Any Active requirements shipped in this phase? - Move to Validated with phase reference: `- ✓ [Requirement] — Phase X` 2. **Requirements invalidated?** - Any Active requirements discovered to be unnecessary or wrong? - Move to Out of Scope with reason: `- [Requirement] — [why invalidated]` 3. **Requirements emerged?** - Any new requirements discovered during building? - Add to Active: `- [ ] [New requirement]` 4. **Decisions to log?** - Extract decisions from SUMMARY.md files - Add to Key Decisions table with outcome if known 5. **"What This Is" still accurate?** - If the product has meaningfully changed, update the description - Keep it current and accurate **Update PROJECT.md:** Make the edits inline. Update "Last updated" footer: ```markdown --- _Last updated: [date] after Phase [X]_ ``` **Example evolution:** Before: ```markdown ### Active - [ ] JWT authentication - [ ] Real-time sync < 500ms - [ ] Offline mode ### Out of Scope - OAuth2 — complexity not needed for v1 ``` After (Phase 2 shipped JWT auth, discovered rate limiting needed): ```markdown ### Validated - ✓ JWT authentication — Phase 2 ### Active - [ ] Real-time sync < 500ms - [ ] Offline mode - [ ] Rate limiting on sync endpoint ### Out of Scope - OAuth2 — complexity not needed for v1 ``` **Step complete when:** - [ ] Phase summaries reviewed for learnings - [ ] Validated requirements moved from Active - [ ] Invalidated requirements moved to Out of Scope with reason - [ ] Emerged requirements added to Active - [ ] New decisions logged with rationale - [ ] "What This Is" updated if product changed - [ ] "Last updated" footer reflects this transition </step> <step name="update_current_position_after_transition"> Update Current Position section in STATE.md to reflect phase completion and transition. **Format:** ```markdown Phase: [next] of [total] ([Next phase name]) Plan: Not started Status: Ready to plan Last activity: [today] — Phase [X] complete, transitioned to Phase [X+1] Progress: [updated progress bar] ``` **Instructions:** - Increment phase number to next phase - Reset plan to "Not started" - Set status to "Ready to plan" - Update last activity to describe transition - Recalculate progress bar based on completed plans **Example — transitioning from Phase 2 to Phase 3:** Before: ```markdown ## Current Position Phase: 2 of 4 (Authentication) Plan: 2 of 2 in current phase Status: Phase complete Last activity: 2025-01-20 — Completed 02-02-PLAN.md Progress: ███████░░░ 60% ``` After: ```markdown ## Current Position Phase: 3 of 4 (Core Features) Plan: Not started Status: Ready to plan Last activity: 2025-01-20 — Phase 2 complete, transitioned to Phase 3 Progress: ███████░░░ 60% ``` **Step complete when:** - [ ] Phase number incremented to next phase - [ ] Plan status reset to "Not started" - [ ] Status shows "Ready to plan" - [ ] Last activity describes the transition - [ ] Progress bar reflects total completed plans </step> <step name="update_project_reference"> Update Project Reference section in STATE.md. ```markdown ## Project Reference See: .gsd/PROJECT.md (updated [today]) **Core value:** [Current core value from PROJECT.md] **Current focus:** [Next phase name] ``` Update the date and current focus to reflect the transition. </step> <step name="review_accumulated_context"> Review and update Accumulated Context section in STATE.md. **Decisions:** - Note recent decisions from this phase (3-5 max) - Full log lives in PROJECT.md Key Decisions table **Blockers/Concerns:** - Review blockers from completed phase - If addressed in this phase: Remove from list - If still relevant for future: Keep with "Phase X" prefix - Add any new concerns from completed phase's summaries **Example:** Before: ```markdown ### Blockers/Concerns - ⚠️ [Phase 1] Database schema not indexed for common queries - ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown ``` After (if database indexing was addressed in Phase 2): ```markdown ### Blockers/Concerns - ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown ``` **Step complete when:** - [ ] Recent decisions noted (full log in PROJECT.md) - [ ] Resolved blockers removed from list - [ ] Unresolved blockers kept with phase prefix - [ ] New concerns from completed phase added </step> <step name="update_session_continuity_after_transition"> Update Session Continuity section in STATE.md to reflect transition completion. **Format:** ```markdown Last session: [today] Stopped at: Phase [X] complete, ready to plan Phase [X+1] Resume file: None ``` **Step complete when:** - [ ] Last session timestamp updated to current date and time - [ ] Stopped at describes phase completion and next phase - [ ] Resume file confirmed as None (transitions don't use resume files) </step> <step name="offer_next_phase"> **MANDATORY: Verify milestone status before presenting next steps.** **Step 1: Read ROADMAP.md and identify phases in current milestone** Read the ROADMAP.md file and extract: 1. Current phase number (the phase just transitioned from) 2. All phase numbers in the current milestone section To find phases, look for: - Phase headers: lines starting with `### Phase` or `#### Phase` - Phase list items: lines like `- [ ] **Phase X:` or `- [x] **Phase X:` Count total phases and identify the highest phase number in the milestone. State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})." **Step 2: Route based on milestone status** | Condition | Meaning | Action | | ----------------------------- | ------------------ | ----------------- | | current phase < highest phase | More phases remain | Go to **Route A** | | current phase = highest phase | Milestone complete | Go to **Route B** | --- **Route A: More phases remain in milestone** Read ROADMAP.md to get the next phase's name and goal. **If next phase exists:** <if mode="yolo"> ``` Phase [X] marked complete. Next: Phase [X+1] — [Name] ⚡ Auto-continuing: Plan Phase [X+1] in detail ``` Exit skill and invoke SlashCommand("/plan-phase.md [X+1]") </if> <if mode="interactive" OR="custom with gates.confirm_transition true"> ``` ## ✓ Phase [X] Complete --- ## ▶ Next Up **Phase [X+1]: [Name]** — [Goal from ROADMAP.md] `/plan-phase.md [X+1]` <sub>`/clear` first → fresh context window</sub> --- **Also available:** - `/discuss-phase.md [X+1]` — gather context first - `/research-phase.md [X+1]` — investigate unknowns - Review roadmap --- ``` </if> --- **Route B: Milestone complete (all phases done)** <if mode="yolo"> ``` Phase {X} marked complete. 🎉 Milestone {version} is 100% complete — all {N} phases finished! ⚡ Auto-continuing: Complete milestone and archive ``` Exit skill and invoke SlashCommand("/complete-milestone.md {version}") </if> <if mode="interactive" OR="custom with gates.confirm_transition true"> ``` ## ✓ Phase {X}: {Phase Name} Complete 🎉 Milestone {version} is 100% complete — all {N} phases finished! --- ## ▶ Next Up **Complete Milestone {version}** — archive and prepare for next `/complete-milestone.md {version}` <sub>`/clear` first → fresh context window</sub> --- **Also available:** - Review accomplishments before archiving --- ``` </if> </step> </process> <implicit_tracking>