mirror of
https://github.com/glittercowboy/get-shit-done
synced 2026-04-25 17:25:23 +02:00
feat(discuss-phase): intelligent gray area analysis with scope guardrails
- 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
@@ -1,15 +1,20 @@
|
||||
---
|
||||
name: gsd:discuss-phase
|
||||
description: Gather phase context through adaptive questioning before planning
|
||||
argument-hint: "[phase]"
|
||||
argument-hint: "<phase>"
|
||||
allowed-tools: [Read, Write, Bash, Glob, Grep, AskUserQuestion]
|
||||
---
|
||||
|
||||
<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>
|
||||
|
||||
<execution_context>
|
||||
@@ -21,7 +26,7 @@ Output: {phase}-CONTEXT.md capturing the user's vision for the phase
|
||||
<context>
|
||||
Phase number: $ARGUMENTS (required)
|
||||
|
||||
**Load project state first:**
|
||||
**Load project state:**
|
||||
@.planning/STATE.md
|
||||
|
||||
**Load roadmap:**
|
||||
@@ -29,32 +34,39 @@ Phase number: $ARGUMENTS (required)
|
||||
</context>
|
||||
|
||||
<process>
|
||||
1. Validate phase number argument (error if missing or invalid)
|
||||
2. Check if phase exists in roadmap
|
||||
3. Check if CONTEXT.md already exists (offer to update if yes)
|
||||
4. Follow discuss-phase.md workflow with **ALL questions using AskUserQuestion**:
|
||||
- Present phase from roadmap
|
||||
- Use AskUserQuestion: "How do you imagine this working?" with interpretation options
|
||||
- Use AskUserQuestion to follow their thread — probe what excites them
|
||||
- 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)
|
||||
1. Validate phase number (error if missing or not in roadmap)
|
||||
2. Check if CONTEXT.md exists (offer update/view/skip if yes)
|
||||
3. **Analyze phase** — Identify domain boundary and gray areas by category
|
||||
4. **Present gray areas** — Multi-select AskUserQuestion: which to discuss?
|
||||
5. **Deep-dive each area** — Loop per area until user says "move on"
|
||||
6. **Write CONTEXT.md** — Structured by decisions made
|
||||
7. Offer next steps (research or plan)
|
||||
|
||||
**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:
|
||||
- Ask about vision, feel, essential outcomes
|
||||
- DON'T ask about technical risks (you figure those out)
|
||||
- DON'T ask about codebase patterns (you read the code)
|
||||
- DON'T ask about success metrics (too corporate)
|
||||
- DON'T interrogate about constraints they didn't mention
|
||||
**Gray area categories (use what's relevant):**
|
||||
- **UI** — Layout, visual presentation, information density
|
||||
- **UX** — Interactions, flows, feedback
|
||||
- **Behavior** — Runtime behavior, state changes
|
||||
- **Empty/Edge States** — What shows in unusual situations
|
||||
- **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>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
- Phase validated against roadmap
|
||||
- Vision gathered through collaborative thinking (not interrogation)
|
||||
- CONTEXT.md captures: how it works, what's essential
|
||||
- User knows next steps (research or plan the phase)
|
||||
- Gray areas identified through intelligent analysis
|
||||
- User chose which areas to discuss
|
||||
- Each selected area explored until satisfied
|
||||
- Scope creep redirected to deferred ideas
|
||||
- CONTEXT.md captures decisions, not vague vision
|
||||
- User knows next steps
|
||||
</success_criteria>
|
||||
|
||||
@@ -1,8 +1,12 @@
|
||||
# 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
|
||||
|
||||
**Gathered:** [date]
|
||||
**Status:** [Ready for research / Ready for planning]
|
||||
**Status:** Ready for planning
|
||||
|
||||
<vision>
|
||||
## How This Should Work
|
||||
<domain>
|
||||
## 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>
|
||||
## What Must Be Nailed
|
||||
<decisions>
|
||||
## 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]
|
||||
- [Essential thing 2]
|
||||
- [Essential thing 3 if applicable]
|
||||
### [Category discussed, e.g., Behavior]
|
||||
- [Specific decision made]
|
||||
|
||||
</essential>
|
||||
### Claude's Discretion
|
||||
[Areas where user explicitly said "you decide" — Claude has flexibility here during planning/implementation]
|
||||
|
||||
</decisions>
|
||||
|
||||
<specifics>
|
||||
## 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>
|
||||
|
||||
<notes>
|
||||
## Additional Context
|
||||
<deferred>
|
||||
## 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>
|
||||
```markdown
|
||||
# Phase 3: User Dashboard - Context
|
||||
# Phase 3: Post Feed - Context
|
||||
|
||||
**Gathered:** 2025-01-20
|
||||
**Status:** Ready for research
|
||||
**Status:** Ready for planning
|
||||
|
||||
<vision>
|
||||
## How This Should Work
|
||||
<domain>
|
||||
## 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>
|
||||
## What Must Be Nailed
|
||||
### UI
|
||||
- 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
|
||||
- **Personal feel** - This is YOUR dashboard, not a team dashboard. It should feel like opening your personal notebook.
|
||||
### Behavior
|
||||
- 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>
|
||||
## Specific Ideas
|
||||
|
||||
- I like how Linear's home screen highlights what's assigned to you without noise
|
||||
- Should show projects in a card format, not a list
|
||||
- Maybe a "Today" section at the top with urgent stuff
|
||||
- Dark mode is essential (already have this from Phase 2)
|
||||
- "I like how Twitter shows the new posts indicator without disrupting your scroll position"
|
||||
- Cards should feel like Linear's issue cards — clean, not cluttered
|
||||
- No infinite scroll fatigue — maybe show "You're all caught up" after ~50 posts
|
||||
|
||||
</specifics>
|
||||
|
||||
<notes>
|
||||
## Additional Context
|
||||
<deferred>
|
||||
## 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.
|
||||
|
||||
</notes>
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 03-user-dashboard*
|
||||
*Phase: 03-post-feed*
|
||||
*Context gathered: 2025-01-20*
|
||||
```
|
||||
</good_examples>
|
||||
|
||||
<guidelines>
|
||||
**This template captures VISION, not technical specs.**
|
||||
**This template captures DECISIONS for downstream agents.**
|
||||
|
||||
The user is the visionary. They know:
|
||||
- How they imagine it working
|
||||
- What it should feel like
|
||||
- What's essential vs nice-to-have
|
||||
- References to things they like
|
||||
The output should answer: "What does the researcher need to investigate? What choices are locked for the planner?"
|
||||
|
||||
The user does NOT know (and shouldn't be asked):
|
||||
- Codebase patterns (Claude reads the code)
|
||||
- Technical risks (Claude identifies during research)
|
||||
- Implementation constraints (Claude figures out)
|
||||
- Success metrics (Claude infers from the work)
|
||||
**Good content:**
|
||||
- "Card-based layout, not timeline"
|
||||
- "Infinite scroll with pull-to-refresh"
|
||||
- "Show 10 posts initially"
|
||||
- "New posts indicator rather than auto-insert"
|
||||
|
||||
**Content should read like:**
|
||||
- A founder describing their product vision
|
||||
- "When you use this, it should feel like..."
|
||||
- "The most important thing is..."
|
||||
- "I don't want it to be like X, I want it to feel like Y"
|
||||
**Bad content (too vague):**
|
||||
- "Should feel modern and clean"
|
||||
- "Good user experience"
|
||||
- "Fast and responsive"
|
||||
- "Easy to use"
|
||||
|
||||
**Content should NOT read like:**
|
||||
- A technical specification
|
||||
- Risk assessment matrix
|
||||
- Success criteria checklist
|
||||
- Codebase analysis
|
||||
**Sections explained:**
|
||||
|
||||
- **Domain** — The scope anchor. Copied/derived from ROADMAP.md. Fixed boundary.
|
||||
- **Decisions** — Organized by category (UI, UX, Behavior, etc.). Actual choices made.
|
||||
- **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:**
|
||||
- File lives in phase directory: `.planning/phases/XX-name/{phase}-CONTEXT.md`
|
||||
- Research phase adds technical context (patterns, risks, constraints)
|
||||
- Planning phase creates executable tasks informed by both vision AND research
|
||||
- `gsd-phase-researcher` uses decisions to focus investigation
|
||||
- `gsd-planner` uses decisions + research to create executable tasks
|
||||
- Downstream agents should NOT need to ask the user again about captured decisions
|
||||
</guidelines>
|
||||
|
||||
@@ -1,65 +1,112 @@
|
||||
<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>
|
||||
|
||||
<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>
|
||||
**User = founder/visionary. Claude = builder.**
|
||||
|
||||
The user doesn't know (and shouldn't need to know):
|
||||
- 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:
|
||||
The user knows:
|
||||
- How they imagine it working
|
||||
- What it should look/feel like
|
||||
- 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>
|
||||
|
||||
<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>
|
||||
|
||||
<step name="validate_phase" priority="first">
|
||||
Phase number: $ARGUMENTS (required)
|
||||
Phase number from argument (required).
|
||||
|
||||
Validate phase exists in roadmap:
|
||||
|
||||
```bash
|
||||
if [ -f .planning/ROADMAP.md ]; then
|
||||
cat .planning/ROADMAP.md | grep "Phase ${PHASE}:"
|
||||
else
|
||||
cat .planning/ROADMAP.md | grep "Phase ${PHASE}:"
|
||||
fi
|
||||
```
|
||||
Load and validate:
|
||||
- Read `.planning/ROADMAP.md`
|
||||
- Find phase entry
|
||||
- Extract: number, name, description, status
|
||||
|
||||
**If phase not found:**
|
||||
|
||||
```
|
||||
Error: Phase ${PHASE} not found in roadmap.
|
||||
Phase [X] not found in roadmap.
|
||||
|
||||
Use /gsd:progress to see available phases.
|
||||
```
|
||||
|
||||
Exit workflow.
|
||||
|
||||
**If phase found:**
|
||||
Parse phase details from roadmap:
|
||||
|
||||
- Phase number
|
||||
- Phase name
|
||||
- Phase description
|
||||
- Status (should be "Not started" or "In progress")
|
||||
|
||||
Continue to check_existing.
|
||||
**If phase found:** Continue to analyze_phase.
|
||||
</step>
|
||||
|
||||
<step name="check_existing">
|
||||
Check if CONTEXT.md already exists for this phase:
|
||||
Check if CONTEXT.md already exists:
|
||||
|
||||
```bash
|
||||
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:**
|
||||
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
|
||||
|
||||
```
|
||||
Phase ${PHASE} already has context: [path to CONTEXT.md]
|
||||
|
||||
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 "Update": Load existing, continue to analyze_phase
|
||||
If "View": Display CONTEXT.md, then offer update/skip
|
||||
If "Skip": Exit workflow
|
||||
|
||||
**If doesn't exist:**
|
||||
Continue to questioning.
|
||||
**If doesn't exist:** Continue to analyze_phase.
|
||||
</step>
|
||||
|
||||
<step name="questioning">
|
||||
**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
|
||||
<step name="analyze_phase">
|
||||
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:
|
||||
- header: "Vision"
|
||||
- question: "How do you imagine this working?"
|
||||
- options: 2-3 interpretations based on the phase description + "Let me describe it"
|
||||
**Example options:**
|
||||
```
|
||||
☐ UI — Card layout or timeline? How much of each post shows?
|
||||
☐ 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:
|
||||
- header: "[Topic they mentioned]"
|
||||
- question: "You mentioned [X] — what would that look like?"
|
||||
- options: 2-3 interpretations + "Something else"
|
||||
<step name="discuss_areas">
|
||||
For each selected area, conduct a focused discussion loop.
|
||||
|
||||
**3. Sharpen the core:**
|
||||
**For each area:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Essential"
|
||||
- question: "What's the most important part of this phase?"
|
||||
- options: Key aspects they've mentioned + "All equally important" + "Something else"
|
||||
1. **Announce the area:**
|
||||
```
|
||||
Let's talk about [Category].
|
||||
```
|
||||
|
||||
**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:
|
||||
- header: "Specifics"
|
||||
- question: "Any particular look/feel/behavior in mind?"
|
||||
- options: Contextual options based on what they've said + "No specifics" + "Let me describe"
|
||||
3. **Follow up based on response:**
|
||||
- If they chose an option: Capture it, ask if there's more about this area
|
||||
- If "Let me describe": Receive their input, reflect it back, confirm understanding
|
||||
- If "You decide": Note that Claude has discretion here
|
||||
|
||||
CRITICAL — What NOT to ask:
|
||||
- Technical risks (you figure those out)
|
||||
- Codebase patterns (you read the code)
|
||||
- Success metrics (too corporate)
|
||||
- Constraints they didn't mention (don't interrogate)
|
||||
- What's out of scope (implicit from roadmap)
|
||||
4. **Loop control — Always offer:**
|
||||
- "Ask more about [Category]" — Continue probing this area
|
||||
- "Move to next area" — Done with this category
|
||||
- "That's enough, create context" — Done with all discussion
|
||||
|
||||
**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:
|
||||
- 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
|
||||
Back to [current domain]: [return to current question]"
|
||||
```
|
||||
|
||||
If "Ask more questions" → return to step 2 with new probes.
|
||||
If "Let me add context" → receive input → return to step 2.
|
||||
Loop until "Create CONTEXT.md" selected.
|
||||
Track deferred ideas internally.
|
||||
|
||||
**Continue until:**
|
||||
- User says "Move to next area" and all selected areas are done, OR
|
||||
- User says "That's enough, create context"
|
||||
</step>
|
||||
|
||||
<step name="write_context">
|
||||
Create CONTEXT.md capturing the user's vision.
|
||||
|
||||
Use template from ~/.claude/get-shit-done/templates/context.md
|
||||
Create CONTEXT.md capturing decisions made.
|
||||
|
||||
**File location:** `.planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md`
|
||||
|
||||
**If phase directory doesn't exist yet:**
|
||||
Create it: `.planning/phases/${PHASE}-${SLUG}/`
|
||||
Create phase directory if it doesn't exist. Use roadmap phase name for slug (lowercase, hyphens).
|
||||
|
||||
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
|
||||
- `<essential>`: What must be nailed in this phase
|
||||
- `<specifics>`: Any particular look/feel/behavior mentioned
|
||||
- `<notes>`: Any other context gathered
|
||||
**Gathered:** [date]
|
||||
**Status:** Ready for planning
|
||||
|
||||
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.
|
||||
</step>
|
||||
|
||||
<step name="confirm_creation">
|
||||
Present CONTEXT.md summary:
|
||||
Present summary and next steps:
|
||||
|
||||
```
|
||||
Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
|
||||
|
||||
## Vision
|
||||
[How they imagine it working]
|
||||
## Decisions Captured
|
||||
|
||||
## Essential
|
||||
[What must be nailed]
|
||||
### [Category]
|
||||
- [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:**
|
||||
- `/gsd:research-phase ${PHASE}` — investigate unknowns
|
||||
- `/gsd:research-phase ${PHASE}` — investigate unknowns first
|
||||
- Review/edit CONTEXT.md before continuing
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="git_commit">
|
||||
@@ -214,9 +337,8 @@ git commit -m "$(cat <<'EOF'
|
||||
docs(${PHASE}): capture phase context
|
||||
|
||||
Phase ${PHASE}: ${PHASE_NAME}
|
||||
- Vision and goals documented
|
||||
- Essential requirements identified
|
||||
- Scope boundaries defined
|
||||
- Implementation decisions documented
|
||||
- Phase boundary established
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
@@ -227,11 +349,12 @@ Confirm: "Committed: docs(${PHASE}): capture phase context"
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
- Phase validated against roadmap
|
||||
- Vision gathered through collaborative thinking (not interrogation)
|
||||
- User's imagination captured: how it works, what's essential
|
||||
- CONTEXT.md created in phase directory
|
||||
- CONTEXT.md committed to git
|
||||
- User knows next steps (typically: research or plan the phase)
|
||||
- Gray areas identified through intelligent analysis (not generic questions)
|
||||
- User selected which areas to discuss
|
||||
- Each selected area explored until user satisfied
|
||||
- Scope creep redirected to deferred ideas
|
||||
- CONTEXT.md captures actual decisions, not vague vision
|
||||
- Deferred ideas preserved for future phases
|
||||
- User knows next steps
|
||||
</success_criteria>
|
||||
|
||||
Reference in New Issue
Block a user