Discuss Phase Implementation

Capture your vision before planning through adaptive questioning

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>

First Discussion

/gsd:discuss-phase 1

Starts fresh discussion for phase 1.

Update Existing

/gsd:discuss-phase 3

If 03-CONTEXT.md exists, you’ll be offered options:

• Update existing context
• View current context
• Skip to planning

Automatic Mode

/gsd:discuss-phase 2 --auto

Auto mode is for future use when you have pre-written context documents.

Domain-Aware Gray Areas

GSD analyzes your phase goal and generates specific gray areas, not generic questions:

Visual Features

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

APIs & CLIs

For backend or command-line tools:

• Response Format - JSON structure, pagination approach, field naming
• Error Handling - Error codes, message detail level, recovery suggestions
• Authentication - Token format, refresh strategy, permission model
• Versioning - URL scheme, header-based, breaking change policy
• Output Verbosity - Default detail level, debug modes, quiet flags

Content Systems

For content management or documentation:

• Structure - Hierarchies, taxonomies, categorization approach
• Tone & Voice - Formal vs casual, technical depth, audience level
• Flow - Reading order, navigation patterns, cross-references
• Formatting - Markdown flavor, rich text features, code highlighting

Organization Tasks

For refactoring or restructuring:

• Grouping Criteria - What files go where, directory structure
• Naming Conventions - File names, function names, variable patterns
• Duplicate Handling - Merge strategy, conflict resolution
• Exception Cases - Special files, legacy code, migration approach

The Probing Process

When you select a gray area, GSD asks 4 questions at a time:

Example: Dashboard Layout

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

Reusing Existing Patterns

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

Example: 03-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:

Skipping Decided Areas

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