Skip to main content

​
Overview

The /gsd:discuss-phase command extracts implementation decisions before research and planning begin. This is where you shape how a feature gets built - the details that make it yours.

​
Why This Matters

Your roadmap has a sentence or two per phase:
Phase 3: User dashboard with activity feed
That’s not enough context to build what you imagine. Do you want cards or a table? Infinite scroll or pagination? Real-time updates or manual refresh? Discuss-phase captures these preferences so:
  1. Researcher knows what to investigate - “User wants card layout” → research card component libraries
  2. Planner knows what’s decided - “Infinite scroll confirmed” → plan includes scroll handling
The deeper you go in discuss-phase, the more the system builds what you actually want. Skip it and you get reasonable defaults. Use it and you get your vision.

​
What It Does

1

Load Context

Reads PROJECT.md, REQUIREMENTS.md, STATE.md, and prior CONTEXT.md files to avoid re-asking decided questions.
2

Scout Codebase

Searches for reusable assets, existing patterns, and integration points.
3

Analyze Phase

Identifies gray areas based on what’s being built. Skips areas already decided in prior phases.
4

Present Gray Areas

Shows a menu of implementation areas to discuss. You choose which matter to you.
5

Deep-Dive Each Area

Asks 4 questions per area. After each set, you can dig deeper or move on.
6

Write CONTEXT.md

Creates {phase_num}-CONTEXT.md with your decisions. This file guides planning.

​
Command Usage

/gsd:discuss-phase <phase-number>

/gsd:discuss-phase 1
Starts fresh discussion for phase 1.

​
Domain-Aware Gray Areas

GSD analyzes your phase goal and generates specific gray areas, not generic questions:
For UI/UX work, gray areas might include:
  • Layout & Structure - Cards vs table, grid vs list, responsive breakpoints
  • Density & Spacing - Compact vs spacious, information hierarchy
  • Interactions - Click behavior, hover states, keyboard navigation
  • Empty States - What shows when there’s no data
  • Loading States - Skeleton screens, spinners, progressive loading

​
The Probing Process

When you select a gray area, GSD asks 4 questions at a time: 
🎯 Gray Area: Dashboard Layout & Structure

Q1: Do you want the activity feed to use cards or a table layout?
   - Cards: Better for varied content types, more visual
   - Table: Better for scanning lots of items, more compact

Q2: Should activities be grouped by day or shown as a continuous stream?

Q3: How much detail should each activity show by default?
   - Summary only (expandable)
   - Full details always visible
   - Configurable per user

Q4: Where should filters be positioned?
   - Top bar
   - Sidebar
   - Dropdown menu

More questions about Dashboard Layout, or move to next area?
After each set of 4:
  • More questions → Ask 4 more, repeat
  • Move to next → Close this area, move on
After all selected areas are explored:
  • Ready to create context? → Write CONTEXT.md
Don’t feel pressured to answer everything. If you don’t care about a detail, say “whatever’s standard” or “Claude’s choice” and move on.

​
Scope Guardrails

Discuss-phase clarifies HOW to implement, not WHETHER to add more features.
The phase boundary from ROADMAP.md is fixed. If you suggest new capabilities during discussion: 
💡 That's a separate phase. I'll note it for later.

Adding to deferred ideas:
- Real-time collaboration features
- Activity export to CSV

Let's continue with the current phase scope.
This prevents scope creep while capturing good ideas for future work.

​
Code-Informed Questions

GSD scouts your codebase before asking questions: 
📋 Codebase Context:
Found existing card component at src/components/Card.tsx
Currently used in: Dashboard, Settings, Profile

Q: Should activity feed use the existing Card component?
   - Yes, reuse Card.tsx (maintains consistency)
   - No, create new ActivityCard (custom styling needed)
   - Enhance Card.tsx (add features, use everywhere)
This helps you:
  • Reuse existing components
  • Maintain design consistency
  • Identify opportunities to improve shared code

​
Context7 Integration

When choosing libraries or frameworks, GSD can query Context7 for official documentation: 
🔍 Library Choice:

You mentioned using ShadCN for the dashboard. Would you like me to:
- Query Context7 for ShadCN best practices
- Research alternative component libraries
- Use what's already in the project
Context7 queries require the MCP server to be configured. See MCP Servers.

​
Output: CONTEXT.md

After discussion, GSD creates {phase_num}-CONTEXT.md: 
# Phase 3 Context: Activity Dashboard

## Dashboard Layout & Structure
- Use card layout for activity items (visual, varied content)
- Group activities by day with date headers
- Show summary by default, expand on click for details
- Filters in top bar: type, date range, user

## Data Loading & Updates
- Infinite scroll (load 20 items at a time)
- Optimistic updates when user creates activity
- Pull-to-refresh on mobile
- No real-time updates (manual refresh)

## Empty & Error States
- Empty state: illustration + "No activity yet" + CTA button
- Loading: skeleton cards (3 visible)
- Error: toast notification + retry button

## Code Context
- Reuse Card.tsx component from src/components/
- Follow existing loading pattern from Dashboard.tsx
- Use date utility from src/lib/dates.ts
This file is loaded by:
  • Research agent - Knows what to investigate
  • Planning agent - Knows what decisions are locked

​
Prior Context Loading

GSD reads all previous CONTEXT.md files to avoid repeating questions: 
📚 Prior Context Loaded:
- 01-CONTEXT.md: Decided on ShadCN components
- 02-CONTEXT.md: Decided on Zustand for state management

🎯 Gray Areas for Phase 3:
✓ Component library (decided in Phase 1) - skipping
✓ State management (decided in Phase 2) - skipping
- Dashboard layout (new)
- Data loading strategy (new)
- Filter implementation (new)

Which would you like to discuss?

​
What NOT to Ask

Discuss-phase focuses on user-facing decisions. GSD does NOT ask about:
  • Technical implementation - Claude handles code structure
  • Architecture choices - Determined during planning
  • Performance concerns - Handled during execution
  • Testing strategy - Built into plan verification
If you find yourself discussing file structure or function names, you’re too deep in technical details. Discuss-phase is about what users experience, not how code is organized.

​
Example Session

1

Start discussion

/gsd:discuss-phase 3

📋 Phase 3: User Activity Dashboard
Goal: Display user activity with filtering and search
Requirements: REQ-007, REQ-008, REQ-009

Loading prior context...
Scouting codebase...
Analyzing gray areas...
2

Review gray areas

🎯 Implementation Gray Areas:

1. Dashboard Layout & Structure
2. Activity Item Display
3. Filtering & Search
4. Data Loading & Updates
5. Empty & Error States

Which would you like to discuss? (Select multiple)
You select: 1, 3, 4
3

Discuss first area

🎯 Dashboard Layout & Structure

Q1: Cards or table layout for activities?
> Cards - more visual

Q2: Group by day or continuous stream?
> Group by day

Q3: Detail level by default?
> Summary, expand on click

Q4: Filter position?
> Top bar

More questions about layout, or move to next?
> Move to next
4

Complete discussion

After covering all selected areas:
✓ Discussed 3 gray areas
✓ Created 03-CONTEXT.md

Next steps:
- /gsd:plan-phase 3 - Research and create execution plans
- /gsd:discuss-phase 3 - Update this context

​
When to Skip Discuss-Phase

You can skip directly to planning if:
  • The phase is purely technical (refactoring, optimization)
  • You’re happy with reasonable defaults
  • The implementation is obvious from requirements
  • You’re prototyping and will iterate later
Even if you skip, you can always run discuss-phase later and update context before execution.

​
Next Steps

After capturing context:

Plan Phase

Research the domain and create detailed execution plans

Update Context

Re-run discuss-phase to revise decisions

​
Tips

Use code examples. Show GSD a screenshot or existing component you like. Visual references clarify intent faster than words.
Start broad, go deep. Select multiple gray areas, explore each lightly, then dive deep into the ones that matter most.
Capture “why” not just “what”. “Infinite scroll because users browse aimlessly” is better than “use infinite scroll”.
Context is immutable during planning/execution. If you change your mind after execution starts, you’ll need to update CONTEXT.md and re-plan.