msd-core/get-shit-done/workflows/discuss-phase.md

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 capture decisions that will guide research and planning, not to figure out implementation yourself.

<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>

**User = founder/visionary. Claude = builder.**

The user knows:

• How they imagine it working
• What it should look/feel like
• What's essential vs nice-to-have
• Specific behaviors or references they have in mind

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.

<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_identification> Gray areas are implementation decisions the user cares about — things that could go multiple ways and would change the result.

How to identify gray areas:

1. Read the phase goal from ROADMAP.md
2. Understand the domain — What kind of thing is being built?
   • Something users SEE → visual presentation, interactions, states matter
   • Something users CALL → interface contracts, responses, errors matter
   • Something users RUN → invocation, output, behavior modes matter
   • Something users READ → structure, tone, depth, flow matter
   • Something being ORGANIZED → criteria, grouping, handling exceptions matter
3. Generate phase-specific gray areas — Not generic categories, but concrete decisions for THIS phase

Don't use generic category labels (UI, UX, Behavior). Generate specific gray areas:

Phase: "User authentication"
→ Session handling, Error responses, Multi-device policy, Recovery flow

Phase: "Organize photo library"
→ Grouping criteria, Duplicate handling, Naming convention, Folder structure

Phase: "CLI for database backups"
→ Output format, Flag design, Progress reporting, Error recovery

Phase: "API documentation"
→ Structure/navigation, Code examples depth, Versioning approach, Interactive elements

The key question: What decisions would change the outcome that the user should weigh in on?

Claude handles these (don't ask):

• Technical implementation details
• Architecture patterns
• Performance optimization
• Scope (roadmap defines this) </gray_area_identification>

Express path available: If you already have a PRD or acceptance criteria document, use /gsd:plan-phase {phase} --prd path/to/prd.md to skip this discussion and go straight to planning.

Phase number from argument (required).

INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE}")

Parse JSON for: commit_docs, phase_found, phase_dir, phase_number, phase_name, phase_slug, padded_phase, has_research, has_context, has_plans, has_verification, plan_count, roadmap_exists, planning_exists.

If phase_found is false:

Phase [X] not found in roadmap.

Use /gsd:progress to see available phases.

Exit workflow.

If phase_found is true: Continue to check_existing.

Check if CONTEXT.md already exists using `has_context` from init.

ls ${phase_dir}/*-CONTEXT.md 2>/dev/null

If exists: Use AskUserQuestion:

• header: "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 If "View": Display CONTEXT.md, then offer update/skip If "Skip": Exit workflow

If doesn't exist:

Check has_plans and plan_count from init. If has_plans is true:

Use AskUserQuestion:

• header: "Plans exist"
• question: "Phase [X] already has {plan_count} plan(s) created without user context. Your decisions here won't affect existing plans unless you replan."
• options:
  • "Continue and replan after" — Capture context, then run /gsd:plan-phase {X} to replan
  • "View existing plans" — Show plans before deciding
  • "Cancel" — Skip discuss-phase

If "Continue and replan after": Continue to analyze_phase. If "View existing plans": Display plan files, then offer "Continue" / "Cancel". If "Cancel": Exit workflow.

If has_plans is false: Continue to scout_codebase.

Lightweight scan of existing code to inform gray area identification and discussion. Uses ~10% context — acceptable for an interactive session.

Step 1: Check for existing codebase maps

ls .planning/codebase/*.md 2>/dev/null

If codebase maps exist: Read the most relevant ones (CONVENTIONS.md, STRUCTURE.md, STACK.md based on phase type). Extract:

• Reusable components/hooks/utilities
• Established patterns (state management, styling, data fetching)
• Integration points (where new code would connect)

Skip to Step 3 below.

Step 2: If no codebase maps, do targeted grep

Extract key terms from the phase goal (e.g., "feed" → "post", "card", "list"; "auth" → "login", "session", "token").

# Find files related to phase goal terms
grep -rl "{term1}\|{term2}" src/ app/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" 2>/dev/null | head -10

# Find existing components/hooks
ls src/components/ 2>/dev/null
ls src/hooks/ 2>/dev/null
ls src/lib/ src/utils/ 2>/dev/null

Read the 3-5 most relevant files to understand existing patterns.

Step 3: Build internal codebase_context

From the scan, identify:

• Reusable assets — existing components, hooks, utilities that could be used in this phase
• Established patterns — how the codebase does state management, styling, data fetching
• Integration points — where new code would connect (routes, nav, providers)
• Creative options — approaches the existing architecture enables or constrains

Store as internal <codebase_context> for use in analyze_phase and present_gray_areas. This is NOT written to a file — it's used within this session only.

Analyze the phase to identify gray areas worth discussing. **Use codebase_context from scout step to ground the analysis.**

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. Annotate with code context where relevant (e.g., "You already have a Card component" or "No existing pattern for this").

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 (with code context):

Domain: Displaying posts from followed users
Existing: Card component (src/components/ui/Card.tsx), useInfiniteQuery hook, Tailwind CSS
Gray areas:
- UI: Layout style (cards vs timeline vs grid) — Card component exists with shadow/rounded variants
- UI: Information density (full posts vs previews) — no existing density patterns
- Behavior: Loading pattern (infinite scroll vs pagination) — useInfiniteQuery already set up
- Empty State: What shows when no posts exist — EmptyState component exists in ui/
- Content: What metadata displays (time, author, reactions count)

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.)

Then use AskUserQuestion (multiSelect: true):

• header: "Discuss"
• question: "Which areas do you want to discuss for [phase name]?"
• options: Generate 3-4 phase-specific gray areas, each with:
  • "[Specific area]" (label) — concrete, not generic
  • [1-2 questions this covers + code context annotation] (description)
  • Highlight the recommended choice with brief explanation why

Code context annotations: When the scout found relevant existing code, annotate the gray area description:

☐ Layout style — Cards vs list vs timeline?
  (You already have a Card component with shadow/rounded variants. Reusing it keeps the app consistent.)

Do NOT include a "skip" or "you decide" option. User ran this command to discuss — give them real choices.

Examples by domain (with code context):

For "Post Feed" (visual feature):

☐ Layout style — Cards vs list vs timeline? (Card component exists with variants)
☐ Loading behavior — Infinite scroll or pagination? (useInfiniteQuery hook available)
☐ Content ordering — Chronological, algorithmic, or user choice?
☐ Post metadata — What info per post? Timestamps, reactions, author?

For "Database backup CLI" (command-line tool):

☐ Output format — JSON, table, or plain text? Verbosity levels?
☐ Flag design — Short flags, long flags, or both? Required vs optional?
☐ Progress reporting — Silent, progress bar, or verbose logging?
☐ Error recovery — Fail fast, retry, or prompt for action?

For "Organize photo library" (organization task):

☐ Grouping criteria — By date, location, faces, or events?
☐ Duplicate handling — Keep best, keep all, or prompt each time?
☐ Naming convention — Original names, dates, or descriptive?
☐ Folder structure — Flat, nested by year, or by category?

Continue to discuss_areas with selected areas.

For each selected area, conduct a focused discussion loop.

Philosophy: 4 questions, then check.

Ask 4 questions per area before offering to continue or move on. Each answer often reveals the next question.

For each area:

1. Announce the area:

   Let's talk about [Area].
   

2. Ask 4 questions using AskUserQuestion:

   • header: "[Area]" (max 12 chars — abbreviate if needed)
   • question: Specific decision for this area
   • options: 2-3 concrete choices (AskUserQuestion adds "Other" automatically), with the recommended choice highlighted and brief explanation why
   • Annotate options with code context when relevant:

     "How should posts be displayed?"
     - Cards (reuses existing Card component — consistent with Messages)
     - List (simpler, would be a new pattern)
     - Timeline (needs new Timeline component — none exists yet)
     

   • Include "You decide" as an option when reasonable — captures Claude discretion
   • Context7 for library choices: When a gray area involves library selection (e.g., "magic links" → query next-auth docs) or API approach decisions, use mcp__context7__* tools to fetch current documentation and inform the options. Don't use Context7 for every question — only when library-specific knowledge improves the options.

3. After 4 questions, check:

   • header: "[Area]" (max 12 chars)
   • question: "More questions about [area], or move to next?"
   • options: "More questions" / "Next area"

   If "More questions" → ask 4 more, then check again If "Next area" → proceed to next selected area If "Other" (free text) → interpret intent: continuation phrases ("chat more", "keep going", "yes", "more") map to "More questions"; advancement phrases ("done", "move on", "next", "skip") map to "Next area". If ambiguous, ask: "Continue with more questions about [area], or move to the next area?"

4. After all initially-selected areas complete:

   • Summarize what was captured from the discussion so far
   • AskUserQuestion:
     • header: "Done"
     • question: "We've discussed [list areas]. Which gray areas remain unclear?"
     • options: "Explore more gray areas" / "I'm ready for context"
   • If "Explore more gray areas":
     • Identify 2-4 additional gray areas based on what was learned
     • Return to present_gray_areas logic with these new areas
     • Loop: discuss new areas, then prompt again
   • If "I'm ready for context": Proceed to write_context

Question design:

• Options should be concrete, not abstract ("Cards" not "Option A")
• Each answer should inform the next question
• If user picks "Other", receive their input, reflect it back, confirm

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.

Back to [current area]: [return to current question]"

Track deferred ideas internally.

Create CONTEXT.md capturing decisions made.

Find or create phase directory:

Use values from init: phase_dir, phase_slug, padded_phase.

If phase_dir is null (phase exists in roadmap but no directory):

mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"

File location: ${phase_dir}/${padded_phase}-CONTEXT.md

Structure the content by what was discussed:

# Phase [X]: [Name] - Context

**Gathered:** [date]
**Status:** Ready for 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>

<code_context>
## Existing Code Insights

### Reusable Assets
- [Component/hook/utility]: [How it could be used in this phase]

### Established Patterns
- [Pattern]: [How it constrains/enables this phase]

### Integration Points
- [Where new code connects to existing system]

</code_context>

<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.

Present summary and next steps:

Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md

## Decisions Captured

### [Category]
- [Key decision]

### [Category]
- [Key decision]

[If deferred ideas exist:]
## Noted for Later
- [Deferred idea] — future phase

---

## ▶ Next Up

**Phase ${PHASE}: [Name]** — [Goal from ROADMAP.md]

`/gsd:plan-phase ${PHASE}`

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

---

**Also available:**
- `/gsd:plan-phase ${PHASE} --skip-research` — plan without research
- Review/edit CONTEXT.md before continuing

---

Commit phase context (uses `commit_docs` from init internally):

node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): capture phase context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"

Confirm: "Committed: docs(${padded_phase}): capture phase context"

Update STATE.md with session info:

node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state record-session \
  --stopped-at "Phase ${PHASE} context gathered" \
  --resume-file "${phase_dir}/${padded_phase}-CONTEXT.md"

Commit STATE.md:

node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(state): record phase ${PHASE} context session" --files .planning/STATE.md

Check for auto-advance trigger:

1. Parse --auto flag from $ARGUMENTS
2. Read workflow.auto_advance from config:

   AUTO_CFG=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-get workflow.auto_advance 2>/dev/null || echo "false")
   

If --auto flag present AND AUTO_CFG is not true: Persist auto-advance to config (handles direct --auto usage without new-project):

node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-set workflow.auto_advance true

If --auto flag present OR AUTO_CFG is true:

Display banner:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► AUTO-ADVANCING TO PLAN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Context captured. Spawning plan-phase...

Spawn plan-phase as Task with direct workflow file reference (do NOT use Skill tool — Skills don't resolve inside Task subagents):

Task(
  prompt="
    <objective>
    You are the plan-phase orchestrator. Create executable plans for Phase ${PHASE}: ${PHASE_NAME}, then auto-advance to execution.
    </objective>

    <execution_context>
    @~/.claude/get-shit-done/workflows/plan-phase.md
    @~/.claude/get-shit-done/references/ui-brand.md
    @~/.claude/get-shit-done/references/model-profile-resolution.md
    </execution_context>

    <arguments>
    PHASE=${PHASE}
    ARGUMENTS='${PHASE} --auto'
    </arguments>

    <instructions>
    1. Read plan-phase.md from execution_context for your complete workflow
    2. Follow ALL steps: initialize, validate, load context, research, plan, verify, auto-advance
    3. When spawning agents (gsd-phase-researcher, gsd-planner, gsd-plan-checker), use Task with specified subagent_type and model
    4. For step 14 (auto-advance to execute): spawn execute-phase as a Task with DIRECT file reference — tell it to read execute-phase.md. Include @file refs to execute-phase.md, checkpoints.md, tdd.md, model-profile-resolution.md. Pass --no-transition flag so execute-phase returns results instead of chaining further.
    5. Do NOT use the Skill tool or /gsd: commands. Read workflow .md files directly.
    6. Return: PHASE COMPLETE (full pipeline success), PLANNING COMPLETE (planning done but execute failed/skipped), PLANNING INCONCLUSIVE, or GAPS FOUND
    </instructions>
  ",
  subagent_type="general-purpose",
  description="Plan Phase ${PHASE}"
)

Handle plan-phase return:

• PHASE COMPLETE → Full chain succeeded. Display:

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   GSD ► PHASE ${PHASE} COMPLETE
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  
  Auto-advance pipeline finished: discuss → plan → execute
  
  Next: /gsd:discuss-phase ${NEXT_PHASE} --auto
  <sub>/clear first → fresh context window</sub>
  

• PLANNING COMPLETE → Planning done, execution didn't complete:

  Auto-advance partial: Planning complete, execution did not finish.
  Continue: /gsd:execute-phase ${PHASE}
  

• PLANNING INCONCLUSIVE / CHECKPOINT → Stop chain:

  Auto-advance stopped: Planning needs input.
  Continue: /gsd:plan-phase ${PHASE}
  

• GAPS FOUND → Stop chain:

  Auto-advance stopped: Gaps found during execution.
  Continue: /gsd:plan-phase ${PHASE} --gaps
  

If neither --auto nor config enabled: Route to confirm_creation step (existing behavior — show manual next steps).

<success_criteria>

• Phase validated against roadmap
• Codebase scouted for reusable assets, patterns, and integration points
• Gray areas identified through intelligent analysis with code context annotations
• User selected which areas to discuss
• Each selected area explored until user satisfied (with code-informed options)
• Scope creep redirected to deferred ideas
• CONTEXT.md captures actual decisions, not vague vision
• CONTEXT.md includes code_context section with reusable assets and patterns
• Deferred ideas preserved for future phases
• STATE.md updated with session info
• User knows next steps </success_criteria>