Gsd Discuss Phase

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 — decisions clear enough that downstream agents can act without asking the user again

Load project state: @.planning/STATE.md

Load roadmap: @.planning/ROADMAP.md

1. Check if phase argument provided
2. Parse phase number (handle both integer and decimal: "5", "5.1")
3. Load ROADMAP.md
4. Search for phase in roadmap phases list
5. If not found: display error with available phases, exit
6. Extract phase goal and description

1. Find phase directory: .planning/phases/{phase}-*/
2. Look for {phase}-*-CONTEXT.md files
3. If exists:
   • Display current content
   • Offer: "Update / View only / Skip"
   • If Update: proceed with discussion
   • If View: display full file and exit
   • If Skip: exit
4. If doesn't exist: proceed to analysis

Domain-aware analysis: Gray areas depend on what's being built. Based on phase goal, identify:

• Something users SEE → layout, density, interactions, states, visual hierarchy
• Something users CALL → responses, errors, auth, versioning, rate limiting
• Something users RUN → output format, flags, modes, error handling
• Something users READ → structure, tone, depth, flow
• Something being ORGANIZED → criteria, grouping, naming, exceptions

Generate 3-4 phase-specific gray areas, not generic categories.

Examples:

• Phase: "Build task dashboard" → Gray areas: "Task grouping", "Urgency indicators", "Empty states", "Interaction feedback"
• Phase: "Add authentication" → Gray areas: "Session duration", "Password requirements", "2FA approach", "Error messaging"
• Phase: "Create reports" → Gray areas: "Report formatting", "Date range defaults", "Export formats", "Performance data depth"

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 in separate section — don't lose them, don't act on them

1. List all generated gray areas (3-4)
2. For each: brief description of what decisions need to be made
3. Ask: "Which areas do you want to discuss? (select 1 or more)"
4. NO skip/none option — at least one area must be discussed
5. User can select multiple or all
6. Record selected areas for deep-dive

Probing approach:

1. Start with 4 context-specific questions for the area
2. Listen to responses, ask follow-up based on answers
3. After 4 questions: "More questions about [area], or move to next?"
4. If more: ask 4 more, check again
5. If next: move to next selected area
6. After all areas: "Ready to create context?"

Question quality:

• Ask about SPECIFIC implementation choices, not general preferences
• Focus on user-observable behavior, not technical internals
• Avoid "how should we..." — instead "what do you expect when..."
• Dig into edge cases: "What if X happens? What should user see?"

Do NOT ask about (Claude handles these):

• Technical implementation details
• Architecture choices (libraries, patterns)
• Performance optimization strategies
• Testing approaches
• Scope expansion beyond phase boundary

Use template from templates/context.md as base structure.

Sections to populate:

1. Essential Features

   • Must-have features user specified
   • Core functionality that defines phase completion
   • User-observable outcomes that MUST exist

2. Technical Boundaries

   • Locked decisions: libraries, patterns, architecture
   • Constraints from discussion (e.g., "must use JWT", "no external APIs")
   • Technology choices user specified

3. Scope Limits

   • Explicitly out of scope items
   • Features deferred to future phases
   • Boundaries user confirmed

4. Open Questions

   • Things to investigate during research
   • Unclear areas that need research findings
   • Technical unknowns that research should answer

Synthesis rules:

• Write in clear, actionable language
• Use bullet points, not paragraphs
• Be specific: "Use JWT with 1-hour expiration" not "Handle authentication"
• Capture decisions, not discussion history
• Each item should guide downstream agents without additional user input

Frontmatter:

---
phase: {phase}
discussed: {ISO timestamp}
areas: [{list of discussed areas}]
decisions_count: {number of decisions captured}
---

Body: Use synthesized sections from previous step

File naming:

• Find next available number: {phase}-{NN}-CONTEXT.md
• Typically: {phase}-01-CONTEXT.md (first artifact in phase)
• If multiple discussions: increment number

Example path: .planning/phases/05-authentication/05-01-CONTEXT.md

git add .planning/phases/{phase}-*/{phase}-*-CONTEXT.md
git commit -m "docs(${phase}): capture context from discussion

Areas discussed: {list areas}
Decisions captured: {count}
"

If phase has no RESEARCH.md:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 CONTEXT CAPTURED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Discussed: {areas}
Decisions: {count} captured in CONTEXT.md

───────────────────────────────────────────────────────────────

## ▶ Next Up

**Research phase** — investigate open questions and validate approach

/gsd-research-phase {phase}

<sub>/clear first → fresh context window</sub>

───────────────────────────────────────────────────────────────

**Also available:**
- /gsd-plan-phase {phase} — skip research, plan directly (if confident)

───────────────────────────────────────────────────────────────

If phase already has RESEARCH.md:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 CONTEXT UPDATED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Updated decisions based on discussion.
Research may need refresh if decisions changed significantly.

───────────────────────────────────────────────────────────────

## ▶ Next Up

**Plan phase** — create execution plans with updated context

/gsd-plan-phase {phase}

<sub>/clear first → fresh context window</sub>

───────────────────────────────────────────────────────────────

**Also available:**
- /gsd-research-phase {phase} --refresh — re-research with new context
- cat .planning/phases/{phase_dir}/*-CONTEXT.md — review decisions

───────────────────────────────────────────────────────────────