golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(discuss-phase): intelligent gray area analysis with scope guardrails

Browse Source 
- Analyze phase to identify gray areas by category (UI, UX, Behavior, etc.)
- Present multi-select for user to choose which areas to discuss
- Deep-dive each selected area with focused questioning loop
- Explicit scope guardrail: clarify HOW, never expand WHAT
- Capture deferred ideas without acting on them
- Downstream awareness: CONTEXT.md feeds researcher and planner agents
- Template restructured for decisions (domain, decisions, discretion, deferred)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2026-01-16 10:11:17 -06:00
parent 2144960c6c
commit a7249ebe83
3 changed files with 370 additions and 214 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
commands/gsd/discuss-phase.md
View File

@@ -1,15 +1,20 @@
--- ---
name: gsd:discuss-phase name: gsd:discuss-phase
description: Gather phase context through adaptive questioning before planning description: Gather phase context through adaptive questioning before planning
argument-hint: "[phase]" argument-hint: "<phase>"
allowed-tools: [Read, Write, Bash, Glob, Grep, AskUserQuestion]
--- ---
<objective> <objective>
Help the user articulate their vision for a phase through collaborative thinking. Extract implementation decisions that downstream agents need — researcher and planner will use CONTEXT.md to know what to investigate and what choices are locked.
Purpose: Understand HOW the user imagines this phase working — what it looks like, what's essential. You're a thinking partner helping them crystallize their vision, not an interviewer gathering technical requirements. **How it works:**
1. Analyze the phase to identify gray areas (UI, UX, behavior, etc.)
2. Present gray areas — user selects which to discuss
3. Deep-dive each selected area until satisfied
4. Create CONTEXT.md with decisions that guide research and planning
Output: {phase}-CONTEXT.md capturing the user's vision for the phase **Output:** `{phase}-CONTEXT.md` — decisions clear enough that downstream agents can act without asking the user again
</objective> </objective>
<execution_context> <execution_context>
@@ -21,7 +26,7 @@ Output: {phase}-CONTEXT.md capturing the user's vision for the phase
<context> <context>
Phase number: $ARGUMENTS (required) Phase number: $ARGUMENTS (required)
**Load project state first:** **Load project state:**
@.planning/STATE.md @.planning/STATE.md
**Load roadmap:** **Load roadmap:**
@@ -29,32 +34,39 @@ Phase number: $ARGUMENTS (required)
</context> </context>
<process> <process>
1. Validate phase number argument (error if missing or invalid) 1. Validate phase number (error if missing or not in roadmap)
2. Check if phase exists in roadmap 2. Check if CONTEXT.md exists (offer update/view/skip if yes)
3. Check if CONTEXT.md already exists (offer to update if yes) 3. **Analyze phase** — Identify domain boundary and gray areas by category
4. Follow discuss-phase.md workflow with **ALL questions using AskUserQuestion**: 4. **Present gray areas** — Multi-select AskUserQuestion: which to discuss?
- Present phase from roadmap 5. **Deep-dive each area** — Loop per area until user says "move on"
- Use AskUserQuestion: "How do you imagine this working?" with interpretation options 6. **Write CONTEXT.md** — Structured by decisions made
- Use AskUserQuestion to follow their thread — probe what excites them 7. Offer next steps (research or plan)
- Use AskUserQuestion to sharpen the core — what's essential for THIS phase
- Use AskUserQuestion for decision gate (ready / ask more / let me add context)
- Create CONTEXT.md capturing their vision
5. Offer next steps (research or plan the phase)
**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.** **CRITICAL: Scope guardrail**
- Phase boundary from ROADMAP.md is FIXED
- Discussion clarifies HOW to implement, not WHETHER to add more
- If user suggests new capabilities: "That's its own phase. I'll note it for later."
- Capture deferred ideas — don't lose them, don't act on them
User is the visionary, you are the builder: **Gray area categories (use what's relevant):**
- Ask about vision, feel, essential outcomes - **UI** — Layout, visual presentation, information density
- DON'T ask about technical risks (you figure those out) - **UX** — Interactions, flows, feedback
- DON'T ask about codebase patterns (you read the code) - **Behavior** — Runtime behavior, state changes
- DON'T ask about success metrics (too corporate) - **Empty/Edge States** — What shows in unusual situations
- DON'T interrogate about constraints they didn't mention - **Content** — What information is shown/hidden
**Do NOT ask about (downstream agents handle these):**
- Technical implementation (researcher investigates)
- Architecture choices (planner decides)
- Performance concerns (researcher/planner handle)
- Scope expansion (roadmap defines scope)
</process> </process>
<success_criteria> <success_criteria>
- Gray areas identified through intelligent analysis
- Phase validated against roadmap - User chose which areas to discuss
- Vision gathered through collaborative thinking (not interrogation) - Each selected area explored until satisfied
- CONTEXT.md captures: how it works, what's essential - Scope creep redirected to deferred ideas
- User knows next steps (research or plan the phase) - CONTEXT.md captures decisions, not vague vision
- User knows next steps
</success_criteria> </success_criteria>

155
get-shit-done/templates/context.md
View File

@@ -1,8 +1,12 @@
# Phase Context Template # Phase Context Template
Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures the user's vision for a phase. Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures implementation decisions for a phase.
**Purpose:** Document how the user imagines the phase working. This is vision context, not technical analysis. Technical details come from research. **Purpose:** Document decisions that downstream agents need. Researcher uses this to know WHAT to investigate. Planner uses this to know WHAT choices are locked vs flexible.
**Downstream consumers:**
- `gsd-phase-researcher` — Reads decisions to focus research (e.g., "card layout" → research card component patterns)
- `gsd-planner` — Reads decisions to create specific tasks (e.g., "infinite scroll" → task includes virtualization)
--- ---
@@ -12,43 +16,47 @@ Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures the user's
# Phase [X]: [Name] - Context # Phase [X]: [Name] - Context
**Gathered:** [date] **Gathered:** [date]
**Status:** [Ready for research / Ready for planning] **Status:** Ready for planning
<vision> <domain>
## How This Should Work ## Phase Boundary
[User's description of how they imagine this phase working. What happens when someone uses it? What does it look/feel like? This is the "pitch" version, not the technical spec.] [Clear statement of what this phase delivers — the scope anchor. This comes from ROADMAP.md and is fixed. Discussion clarifies implementation within this boundary.]
</vision> </domain>
<essential> <decisions>
## What Must Be Nailed ## Implementation Decisions
[The core of this phase. If we only get one thing right, what is it? What's the non-negotiable that makes this phase successful?] ### [Category discussed, e.g., UI]
- [Specific decision made]
- [Another decision if applicable]
- [Essential thing 1] ### [Category discussed, e.g., Behavior]
- [Essential thing 2] - [Specific decision made]
- [Essential thing 3 if applicable]
</essential> ### Claude's Discretion
[Areas where user explicitly said "you decide" — Claude has flexibility here during planning/implementation]
</decisions>
<specifics> <specifics>
## Specific Ideas ## Specific Ideas
[Any particular things the user has in mind. References to existing products/features they like. Specific behaviors or interactions. "I want it to work like X" or "When you click Y, it should Z."] [Any particular references, examples, or "I want it like X" moments from discussion. Product references, specific behaviors, interaction patterns.]
[If none: "No specific requirements - open to standard approaches"] [If none: "No specific requirements — open to standard approaches"]
</specifics> </specifics>
<notes> <deferred>
## Additional Context ## Deferred Ideas
[Anything else captured during the discussion that doesn't fit above. User's priorities, concerns mentioned, relevant background.] [Ideas that came up during discussion but belong in other phases. Captured here so they're not lost, but explicitly out of scope for this phase.]
[If none: "No additional notes"] [If none: "None — discussion stayed within phase scope"]
</notes> </deferred>
--- ---
@@ -58,83 +66,96 @@ Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures the user's
<good_examples> <good_examples>
```markdown ```markdown
# Phase 3: User Dashboard - Context # Phase 3: Post Feed - Context
**Gathered:** 2025-01-20 **Gathered:** 2025-01-20
**Status:** Ready for research **Status:** Ready for planning
<vision> <domain>
## How This Should Work ## Phase Boundary
When users log in, they land on a dashboard that shows them everything important at a glance. I imagine it feeling calm and organized - not overwhelming like Jira or cluttered like Notion. Display posts from followed users in a scrollable feed. Users can view posts and see engagement counts. Creating posts and interactions are separate phases.
The main thing is seeing their active projects and what needs attention. Think of it like a "what should I work on today" view. It should feel personal, not like enterprise software. </domain>
</vision> <decisions>
## Implementation Decisions
<essential> ### UI
## What Must Be Nailed - Card-based layout, not timeline or list
- Each card shows: author avatar, name, timestamp, full post content, reaction counts
- Cards have subtle shadows, rounded corners — modern feel
- Show 10 posts initially, load more on scroll
- **At-a-glance clarity** - Within 2 seconds of landing, user knows what needs their attention ### Behavior
- **Personal feel** - This is YOUR dashboard, not a team dashboard. It should feel like opening your personal notebook. - Infinite scroll, not pagination
- Pull-to-refresh on mobile
- New posts indicator at top ("3 new posts") rather than auto-inserting
</essential> ### Empty State
- Friendly illustration + "Follow people to see posts here"
- Suggest 3-5 accounts to follow based on interests
### Claude's Discretion
- Loading skeleton design
- Exact spacing and typography
- Error state handling
</decisions>
<specifics> <specifics>
## Specific Ideas ## Specific Ideas
- I like how Linear's home screen highlights what's assigned to you without noise - "I like how Twitter shows the new posts indicator without disrupting your scroll position"
- Should show projects in a card format, not a list - Cards should feel like Linear's issue cards — clean, not cluttered
- Maybe a "Today" section at the top with urgent stuff - No infinite scroll fatigue — maybe show "You're all caught up" after ~50 posts
- Dark mode is essential (already have this from Phase 2)
</specifics> </specifics>
<notes> <deferred>
## Additional Context ## Deferred Ideas
User mentioned they've abandoned several dashboards before because they felt too "corporate." The key differentiator is making it feel personal and calm. - Commenting on posts — Phase 5
- Reaction picker (not just counts) — Phase 5
- Bookmarking posts — add to backlog
Priority is clarity over features. Better to show less and make it obvious than show everything. </deferred>
</notes>
--- ---
*Phase: 03-user-dashboard* *Phase: 03-post-feed*
*Context gathered: 2025-01-20* *Context gathered: 2025-01-20*
``` ```
</good_examples> </good_examples>
<guidelines> <guidelines>
**This template captures VISION, not technical specs.** **This template captures DECISIONS for downstream agents.**
The user is the visionary. They know: The output should answer: "What does the researcher need to investigate? What choices are locked for the planner?"
- How they imagine it working
- What it should feel like
- What's essential vs nice-to-have
- References to things they like
The user does NOT know (and shouldn't be asked): **Good content:**
- Codebase patterns (Claude reads the code) - "Card-based layout, not timeline"
- Technical risks (Claude identifies during research) - "Infinite scroll with pull-to-refresh"
- Implementation constraints (Claude figures out) - "Show 10 posts initially"
- Success metrics (Claude infers from the work) - "New posts indicator rather than auto-insert"
**Content should read like:** **Bad content (too vague):**
- A founder describing their product vision - "Should feel modern and clean"
- "When you use this, it should feel like..." - "Good user experience"
- "The most important thing is..." - "Fast and responsive"
- "I don't want it to be like X, I want it to feel like Y" - "Easy to use"
**Content should NOT read like:** **Sections explained:**
- A technical specification
- Risk assessment matrix - **Domain** — The scope anchor. Copied/derived from ROADMAP.md. Fixed boundary.
- Success criteria checklist - **Decisions** — Organized by category (UI, UX, Behavior, etc.). Actual choices made.
- Codebase analysis - **Claude's Discretion** — Explicit acknowledgment of what Claude can decide during implementation.
- **Specifics** — Product references, examples, "like X but..." statements.
- **Deferred** — Ideas captured but explicitly out of scope. Prevents scope creep while preserving good ideas.
**After creation:** **After creation:**
- File lives in phase directory: `.planning/phases/XX-name/{phase}-CONTEXT.md` - File lives in phase directory: `.planning/phases/XX-name/{phase}-CONTEXT.md`
- Research phase adds technical context (patterns, risks, constraints) - `gsd-phase-researcher` uses decisions to focus investigation
- Planning phase creates executable tasks informed by both vision AND research - `gsd-planner` uses decisions + research to create executable tasks
- Downstream agents should NOT need to ask the user again about captured decisions
</guidelines> </guidelines>

361
get-shit-done/workflows/discuss-phase.md
View File

@@ -1,65 +1,112 @@
<purpose> <purpose>
Gather phase context through collaborative thinking before planning. Help the user articulate their vision for how this phase should work, look, and feel. Extract implementation decisions that downstream agents need. Analyze the phase to identify gray areas, let the user choose what to discuss, then deep-dive each selected area until satisfied.
You are a thinking partner, not an interviewer. The user is the visionary — you are the builder. Your job is to understand their vision, not interrogate them about technical details you can figure out yourself. You are a thinking partner, not an interviewer. The user is the visionary — you are the builder. Your job is to capture decisions that will guide research and planning, not to figure out implementation yourself.
</purpose> </purpose>
<downstream_awareness>
**CONTEXT.md feeds into:**
1. **gsd-phase-researcher** — Reads CONTEXT.md to know WHAT to research
- "User wants card-based layout" → researcher investigates card component patterns
- "Infinite scroll decided" → researcher looks into virtualization libraries
2. **gsd-planner** — Reads CONTEXT.md to know WHAT decisions are locked
- "Pull-to-refresh on mobile" → planner includes that in task specs
- "Claude's Discretion: loading skeleton" → planner can decide approach
**Your job:** Capture decisions clearly enough that downstream agents can act on them without asking the user again.
**Not your job:** Figure out HOW to implement. That's what research and planning do with the decisions you capture.
</downstream_awareness>
<philosophy> <philosophy>
**User = founder/visionary. Claude = builder.** **User = founder/visionary. Claude = builder.**
The user doesn't know (and shouldn't need to know): The user knows:
- Codebase patterns (you read the code)
- Technical risks (you identify during research)
- Implementation constraints (you figure those out)
- Success metrics (you infer from the work)
The user DOES know:
- How they imagine it working - How they imagine it working
- What it should look/feel like - What it should look/feel like
- What's essential vs nice-to-have - What's essential vs nice-to-have
- Any specific things they have in mind - Specific behaviors or references they have in mind
Ask about vision. Figure out implementation yourself. The user doesn't know (and shouldn't be asked):
- Codebase patterns (researcher reads the code)
- Technical risks (researcher identifies these)
- Implementation approach (planner figures this out)
- Success metrics (inferred from the work)
Ask about vision and implementation choices. Capture decisions for downstream agents.
</philosophy> </philosophy>
<scope_guardrail>
**CRITICAL: No scope creep.**
The phase boundary comes from ROADMAP.md and is FIXED. Discussion clarifies HOW to implement what's scoped, never WHETHER to add new capabilities.
**Allowed (clarifying ambiguity):**
- "How should posts be displayed?" (layout, density, info shown)
- "What happens on empty state?" (within the feature)
- "Pull to refresh or manual?" (behavior choice)
**Not allowed (scope creep):**
- "Should we also add comments?" (new capability)
- "What about search/filtering?" (new capability)
- "Maybe include bookmarking?" (new capability)
**The heuristic:** Does this clarify how we implement what's already in the phase, or does it add a new capability that could be its own phase?
**When user suggests scope creep:**
```
"[Feature X] would be a new capability — that's its own phase.
Want me to note it for the roadmap backlog?
For now, let's focus on [phase domain]."
```
Capture the idea in a "Deferred Ideas" section. Don't lose it, don't act on it.
</scope_guardrail>
<gray_area_categories>
Use these categories when analyzing a phase. Not all apply to every phase.
| Category | What it clarifies | Example questions |
|----------|-------------------|-------------------|
| **UI** | Visual presentation, layout, information density | "Card-based or list view?" "What info shows on each item?" |
| **UX** | Interactions, flows, feedback | "How does loading work?" "What happens when you tap X?" |
| **Behavior** | Runtime behavior, state changes | "Auto-refresh or manual?" "How does pagination work?" |
| **Empty/Edge States** | What shows in unusual situations | "What appears with no data?" "How do errors display?" |
| **Content** | What information is shown/hidden | "Show timestamps?" "How much preview text?" |
**Categories to AVOID:**
- **Scope** — The roadmap defines scope, not discussion
- **Technical** — You figure out implementation
- **Architecture** — You decide patterns
- **Performance** — You handle optimization
</gray_area_categories>
<process> <process>
<step name="validate_phase" priority="first"> <step name="validate_phase" priority="first">
Phase number: $ARGUMENTS (required) Phase number from argument (required).
Validate phase exists in roadmap: Load and validate:
- Read `.planning/ROADMAP.md`
```bash - Find phase entry
if [ -f .planning/ROADMAP.md ]; then - Extract: number, name, description, status
cat .planning/ROADMAP.md | grep "Phase ${PHASE}:"
else
cat .planning/ROADMAP.md | grep "Phase ${PHASE}:"
fi
```
**If phase not found:** **If phase not found:**
``` ```
Error: Phase ${PHASE} not found in roadmap. Phase [X] not found in roadmap.
Use /gsd:progress to see available phases. Use /gsd:progress to see available phases.
``` ```
Exit workflow. Exit workflow.
**If phase found:** **If phase found:** Continue to analyze_phase.
Parse phase details from roadmap:
- Phase number
- Phase name
- Phase description
- Status (should be "Not started" or "In progress")
Continue to check_existing.
</step> </step>
<step name="check_existing"> <step name="check_existing">
Check if CONTEXT.md already exists for this phase: Check if CONTEXT.md already exists:
```bash ```bash
ls .planning/phases/${PHASE}-*/CONTEXT.md 2>/dev/null ls .planning/phases/${PHASE}-*/CONTEXT.md 2>/dev/null
@@ -67,122 +114,199 @@ ls .planning/phases/${PHASE}-*/${PHASE}-CONTEXT.md 2>/dev/null
``` ```
**If exists:** **If exists:**
Use AskUserQuestion:
- header: "Existing context"
- question: "Phase [X] already has context. What do you want to do?"
- options:
- "Update it" — Review and revise existing context
- "View it" — Show me what's there
- "Skip" — Use existing context as-is
``` If "Update": Load existing, continue to analyze_phase
Phase ${PHASE} already has context: [path to CONTEXT.md] If "View": Display CONTEXT.md, then offer update/skip
What's next?
1. Update context - Review and revise existing context
2. View existing - Show me the current context
3. Skip - Use existing context as-is
```
Wait for user response.
If "Update context": Load existing CONTEXT.md, continue to questioning
If "View existing": Read and display CONTEXT.md, then offer update/skip
If "Skip": Exit workflow If "Skip": Exit workflow
**If doesn't exist:** **If doesn't exist:** Continue to analyze_phase.
Continue to questioning.
</step> </step>
<step name="questioning"> <step name="analyze_phase">
**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.** Analyze the phase to identify gray areas worth discussing.
Present initial context from roadmap, then immediately use AskUserQuestion: **Read the phase description from ROADMAP.md and determine:**
1. **Domain boundary** — What capability is this phase delivering? State it clearly.
2. **Gray areas by category** — For each relevant category (UI, UX, Behavior, Empty States, Content), identify 1-2 specific ambiguities that would change implementation.
3. **Skip assessment** — If no meaningful gray areas exist (pure infrastructure, clear-cut implementation), the phase may not need discussion.
**Output your analysis internally, then present to user.**
Example analysis for "Post Feed" phase:
``` ```
Phase ${PHASE}: ${PHASE_NAME} Domain: Displaying posts from followed users
Gray areas:
- UI: Layout style (cards vs timeline vs grid)
- UI: Information density (full posts vs previews)
- Behavior: Loading pattern (infinite scroll vs pagination)
- Empty State: What shows when no posts exist
- Content: What metadata displays (time, author, reactions count)
```
</step>
From the roadmap: ${PHASE_DESCRIPTION} <step name="present_gray_areas">
Present the domain boundary and gray areas to user.
**First, state the boundary:**
```
Phase [X]: [Name]
Domain: [What this phase delivers — from your analysis]
We'll clarify HOW to implement this.
(New capabilities belong in other phases.)
``` ```
**1. Open:** **Then use AskUserQuestion (multiSelect: true):**
- header: "Discuss"
- question: "Which areas do you want to discuss?"
- options: Generate 2-4 based on your analysis, each formatted as:
- "[Category] — [Specific gray area question]"
- Last option always: "None — you decide, proceed to planning"
Use AskUserQuestion: **Example options:**
- header: "Vision" ```
- question: "How do you imagine this working?" ☐ UI — Card layout or timeline? How much of each post shows?
- options: 2-3 interpretations based on the phase description + "Let me describe it" ☐ Behavior — Infinite scroll or pagination? Pull to refresh?
☐ Empty state — What appears when there are no posts?
☐ None — You decide, proceed to planning
```
**2. Follow the thread:** If user selects "None": Skip to write_context with minimal context.
Otherwise: Continue to discuss_areas with selected areas.
</step>
Based on their response, use AskUserQuestion: <step name="discuss_areas">
- header: "[Topic they mentioned]" For each selected area, conduct a focused discussion loop.
- question: "You mentioned [X] — what would that look like?"
- options: 2-3 interpretations + "Something else"
**3. Sharpen the core:** **For each area:**
Use AskUserQuestion: 1. **Announce the area:**
- header: "Essential" ```
- question: "What's the most important part of this phase?" Let's talk about [Category].
- options: Key aspects they've mentioned + "All equally important" + "Something else" ```
**4. Capture specifics (optional):** 2. **Ask focused questions using AskUserQuestion:**
- header: "[Category]"
- question: Specific question about that gray area
- options: 2-3 concrete choices + "Let me describe" + "You decide"
If they seem to have specific ideas, use AskUserQuestion: 3. **Follow up based on response:**
- header: "Specifics" - If they chose an option: Capture it, ask if there's more about this area
- question: "Any particular look/feel/behavior in mind?" - If "Let me describe": Receive their input, reflect it back, confirm understanding
- options: Contextual options based on what they've said + "No specifics" + "Let me describe" - If "You decide": Note that Claude has discretion here
CRITICAL — What NOT to ask: 4. **Loop control — Always offer:**
- Technical risks (you figure those out) - "Ask more about [Category]" — Continue probing this area
- Codebase patterns (you read the code) - "Move to next area" — Done with this category
- Success metrics (too corporate) - "That's enough, create context" — Done with all discussion
- Constraints they didn't mention (don't interrogate)
- What's out of scope (implicit from roadmap)
**5. Decision gate:** **Scope creep handling:**
If user mentions something outside the phase domain:
```
"[Feature] sounds like a new capability — that belongs in its own phase.
I'll note it as a deferred idea.
Use AskUserQuestion: Back to [current domain]: [return to current question]"
- header: "Ready?" ```
- question: "Ready to capture this context, or explore more?"
- options (ALL THREE REQUIRED):
- "Create CONTEXT.md" - I've shared my vision
- "Ask more questions" - Help me think through this more
- "Let me add context" - I have more to share
If "Ask more questions" → return to step 2 with new probes. Track deferred ideas internally.
If "Let me add context" → receive input → return to step 2.
Loop until "Create CONTEXT.md" selected. **Continue until:**
- User says "Move to next area" and all selected areas are done, OR
- User says "That's enough, create context"
</step> </step>
<step name="write_context"> <step name="write_context">
Create CONTEXT.md capturing the user's vision. Create CONTEXT.md capturing decisions made.
Use template from ~/.claude/get-shit-done/templates/context.md
**File location:** `.planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md` **File location:** `.planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md`
**If phase directory doesn't exist yet:** Create phase directory if it doesn't exist. Use roadmap phase name for slug (lowercase, hyphens).
Create it: `.planning/phases/${PHASE}-${SLUG}/`
Use roadmap phase name for slug (lowercase, hyphens). **Structure the content by what was discussed:**
Populate template sections with VISION context (not technical analysis): ```markdown
# Phase [X]: [Name] - Context
- `<vision>`: How the user imagines this working **Gathered:** [date]
- `<essential>`: What must be nailed in this phase **Status:** Ready for planning
- `<specifics>`: Any particular look/feel/behavior mentioned
- `<notes>`: Any other context gathered
Do NOT populate with your own technical analysis. That comes during research/planning. <domain>
## Phase Boundary
[Clear statement of what this phase delivers — the scope anchor]
</domain>
<decisions>
## Implementation Decisions
### [Category 1 that was discussed]
- [Decision or preference captured]
- [Another decision if applicable]
### [Category 2 that was discussed]
- [Decision or preference captured]
### Claude's Discretion
[Areas where user said "you decide" — note that Claude has flexibility here]
</decisions>
<specifics>
## Specific Ideas
[Any particular references, examples, or "I want it like X" moments from discussion]
[If none: "No specific requirements — open to standard approaches"]
</specifics>
<deferred>
## Deferred Ideas
[Ideas that came up but belong in other phases. Don't lose them.]
[If none: "None — discussion stayed within phase scope"]
</deferred>
---
*Phase: XX-name*
*Context gathered: [date]*
```
Write file. Write file.
</step> </step>
<step name="confirm_creation"> <step name="confirm_creation">
Present CONTEXT.md summary: Present summary and next steps:
``` ```
Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
## Vision ## Decisions Captured
[How they imagine it working]
## Essential ### [Category]
[What must be nailed] - [Key decision]
### [Category]
- [Key decision]
[If deferred ideas exist:]
## Noted for Later
- [Deferred idea] — future phase
--- ---
@@ -197,12 +321,11 @@ Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
--- ---
**Also available:** **Also available:**
- `/gsd:research-phase ${PHASE}` — investigate unknowns - `/gsd:research-phase ${PHASE}` — investigate unknowns first
- Review/edit CONTEXT.md before continuing - Review/edit CONTEXT.md before continuing
--- ---
``` ```
</step> </step>
<step name="git_commit"> <step name="git_commit">
@@ -214,9 +337,8 @@ git commit -m "$(cat <<'EOF'
docs(${PHASE}): capture phase context docs(${PHASE}): capture phase context
Phase ${PHASE}: ${PHASE_NAME} Phase ${PHASE}: ${PHASE_NAME}
- Vision and goals documented - Implementation decisions documented
- Essential requirements identified - Phase boundary established
- Scope boundaries defined
EOF EOF
)" )"
``` ```
@@ -227,11 +349,12 @@ Confirm: "Committed: docs(${PHASE}): capture phase context"
</process> </process>
<success_criteria> <success_criteria>
- Phase validated against roadmap - Phase validated against roadmap
- Vision gathered through collaborative thinking (not interrogation) - Gray areas identified through intelligent analysis (not generic questions)
- User's imagination captured: how it works, what's essential - User selected which areas to discuss
- CONTEXT.md created in phase directory - Each selected area explored until user satisfied
- CONTEXT.md committed to git - Scope creep redirected to deferred ideas
- User knows next steps (typically: research or plan the phase) - CONTEXT.md captures actual decisions, not vague vision
- Deferred ideas preserved for future phases
- User knows next steps
</success_criteria> </success_criteria>