From a7249ebe83dfed8a2fcb08970fe2f6b3fdf11766 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Fri, 16 Jan 2026 10:11:17 -0600 Subject: [PATCH] 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 --- commands/gsd/discuss-phase.md | 68 +++-- get-shit-done/templates/context.md | 155 +++++----- get-shit-done/workflows/discuss-phase.md | 361 +++++++++++++++-------- 3 files changed, 370 insertions(+), 214 deletions(-) diff --git a/commands/gsd/discuss-phase.md b/commands/gsd/discuss-phase.md index d1a2eb1a8..b3241dbc4 100644 --- a/commands/gsd/discuss-phase.md +++ b/commands/gsd/discuss-phase.md @@ -1,15 +1,20 @@ --- name: gsd:discuss-phase description: Gather phase context through adaptive questioning before planning -argument-hint: "[phase]" +argument-hint: "" +allowed-tools: [Read, Write, Bash, Glob, Grep, AskUserQuestion] --- -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 @@ -21,7 +26,7 @@ Output: {phase}-CONTEXT.md capturing the user's vision for the phase Phase number: $ARGUMENTS (required) -**Load project state first:** +**Load project state:** @.planning/STATE.md **Load roadmap:** @@ -29,32 +34,39 @@ Phase number: $ARGUMENTS (required) -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) - -- 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 diff --git a/get-shit-done/templates/context.md b/get-shit-done/templates/context.md index dc52bf2f6..2854f59b2 100644 --- a/get-shit-done/templates/context.md +++ b/get-shit-done/templates/context.md @@ -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 - -## 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.] - + - -## 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] -- [Essential thing 2] -- [Essential thing 3 if applicable] +### [Category discussed, e.g., Behavior] +- [Specific decision made] - +### Claude's Discretion +[Areas where user explicitly said "you decide" — Claude has flexibility here during planning/implementation] + + ## 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"] - -## 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"] - + --- @@ -58,83 +66,96 @@ Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures the user's ```markdown -# Phase 3: User Dashboard - Context +# Phase 3: Post Feed - Context **Gathered:** 2025-01-20 -**Status:** Ready for research +**Status:** Ready for planning - -## 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. + - + +## Implementation Decisions - -## 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 - +### 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 + + ## 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 - -## 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. - - + --- -*Phase: 03-user-dashboard* +*Phase: 03-post-feed* *Context gathered: 2025-01-20* ``` -**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 diff --git a/get-shit-done/workflows/discuss-phase.md b/get-shit-done/workflows/discuss-phase.md index d2ed0cdfb..c65ee354d 100644 --- a/get-shit-done/workflows/discuss-phase.md +++ b/get-shit-done/workflows/discuss-phase.md @@ -1,65 +1,112 @@ -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. + +**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. + + **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. + +**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. + + + +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 + + -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. -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. - -**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) +``` + -From the roadmap: ${PHASE_DESCRIPTION} + +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. + -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" + +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" -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 -- ``: How the user imagines this working -- ``: What must be nailed in this phase -- ``: Any particular look/feel/behavior mentioned -- ``: Any other context gathered +**Gathered:** [date] +**Status:** Ready for planning -Do NOT populate with your own technical analysis. That comes during research/planning. + +## Phase Boundary + +[Clear statement of what this phase delivers — the scope anchor] + + + + +## 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] + + + + +## Specific Ideas + +[Any particular references, examples, or "I want it like X" moments from discussion] + +[If none: "No specific requirements — open to standard approaches"] + + + + +## Deferred Ideas + +[Ideas that came up but belong in other phases. Don't lose them.] + +[If none: "None — discussion stayed within phase scope"] + + + +--- + +*Phase: XX-name* +*Context gathered: [date]* +``` Write file. -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 --- ``` - @@ -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" - - 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