How `/gsd-discuss-phase` Captures Your Implementation Preferences Before AI Planning Starts

Apr 21, 2026

When I first used GSD, I ran straight from roadmap to planning. The results were… not what I imagined. The layout was wrong, the API returned XML when I wanted JSON, and the error messages were too verbose. I realized that a roadmap with “build user dashboard” gives zero context about what I imagine that dashboard looks like.

That’s when I discovered /gsd-discuss-phase. This command captures your preferences before planning begins, ensuring the AI builds what you actually want.

Why Discussion Matters

Roadmaps describe phases briefly. A sentence like “Phase 3: User Dashboard” isn’t enough context. Without discussion, GSD guesses based on defaults and patterns it’s seen elsewhere. Those guesses often don’t match your vision.

Discussion captures what you imagine:

Layout preferences (grid vs flex, compact vs spacious)
API formats (JSON vs XML, minimal vs verbose responses)
Edge cases and empty states
Naming conventions and organization strategies

After discussion, GSD knows exactly what you want. It doesn’t guess.

Gray Areas by Phase Type

GSD identifies different gray areas depending on what’s being built. The questions change based on the phase type:

Visual features ask about:

Layout (grid vs flex, sidebar placement)
Density (compact tables vs spacious cards)
Interactions (hover effects, click feedback, transitions)
Empty states (what shows when no data exists)

APIs and CLIs ask about:

Response format (JSON vs XML, structure of response envelope)
Flags (—verbose vs -v, naming conventions)
Error handling (HTTP codes vs error objects, message detail)
Verbosity (minimal vs detailed output)

Content systems ask about:

Structure (sections vs chapters, hierarchy depth)
Tone (formal vs casual, technical vs approachable)
Depth (surface overview vs deep dive)
Flow (linear progression vs branching paths)

Organization tasks ask about:

Grouping criteria (by type vs by date vs by author)
Naming conventions (camelCase vs snake_case)
Duplicate handling (merge vs flag vs ignore)
Exceptions (how to handle edge cases)

This phase-type awareness means GSD asks relevant questions, not generic ones.

The CONTEXT.md Output

Discussion produces {phase}-CONTEXT.md. This file has a specific structure that feeds directly into planning:

# Phase 3: User Dashboard

## Decisions (Locked)
- D-01: Layout must use CSS Grid with sidebar on the left
- D-02: Density should be compact (tables, not cards)
- D-03: Empty states must show actionable messages, not just "No data"

## Deferred Ideas (Blocked)
- Dark mode toggle (save for Phase 7)
- Export functionality (out of scope)
- Analytics integration (blocked pending API design)

## Claude's Discretion
- Hover effects: Use judgment, document choices
- Color scheme: Follow existing patterns
- Loading states: Match existing UX patterns

Each section has different implications for the planner:

Decisions (D-01, D-02…): These are locked. The planner MUST implement them exactly as specified. No interpretation allowed.

Deferred Ideas: These are blocked. The planner MUST NOT include them in any plan. Adding them would be scope creep.

Claude’s Discretion: Here the planner can use judgment, but must document the choices made.

How Planner Uses CONTEXT.md

When the planner reads CONTEXT.md, it follows strict rules:

Every locked decision has a corresponding task
Task actions reference the decision ID (e.g., “Implement grid layout per D-01”)
No task implements deferred ideas
Discretion areas handled with documented rationale

The planner self-checks: Does every D-* have a task? Are deferred ideas absent? If not, the plan is incomplete.

Before finalizing plan:
- [ ] D-01 has task implementing grid layout
- [ ] D-02 has task for compact density
- [ ] D-03 has task for actionable empty states
- [ ] No tasks mention dark mode, export, or analytics
- [ ] Hover effects documented with rationale

This prevents the “I thought you wanted X” disconnect. The planner has explicit instructions.

The Assumptions Mode Alternative

Sometimes I don’t want to answer questions. I have an established codebase with clear patterns. In that case, I use assumptions mode:

Enable via /gsd-settings:

workflow.discuss_mode: 'assumptions'

In assumptions mode, GSD reads my codebase first and surfaces structured assumptions. Instead of asking “should I use grid or flex?”, it states:

Assumption A-01: Based on existing components (UserList, ProductGrid),
this phase would use CSS Grid with 3-column layout.
Correct? [yes/no/modify]

I only need to confirm, correct, or expand. This mode works best for:

Experienced developers who know their patterns
Rapid iteration on established projects
Teams with consistent coding conventions

Flags for Discussion Control

GSD provides several flags to control how discussion works:

/gsd-discuss-phase 1 --all

The --all flag discusses every gray area without letting you select which ones matter. Use this when you want comprehensive coverage.

/gsd-discuss-phase 3 --auto

The --auto flag auto-selects recommended defaults for each gray area. Useful when defaults match your style and you want speed.

/gsd-discuss-phase --batch

The --batch flag presents grouped questions instead of one-by-one intake. Faster when you have clear preferences.

/gsd-discuss-phase 2 --analyze

The --analyze flag adds trade-off analysis for each decision. It explains pros/cons before you choose.

/gsd-discuss-phase 1 --chain

The --chain flag auto-chains into planning and execution after discussion finishes. No stopping to review CONTEXT.md.

When I Skip Discussion

I don’t always run discuss phase. Sometimes I skip it:

Quick mode tasks (too small to need preferences)
Phases with no gray areas (implementation is obvious)
Established patterns (assumptions mode covers it)
Emergency fixes (speed matters more than precision)

But for anything substantial, discuss phase prevents the “not what I imagined” outcome. The few minutes I spend answering questions saves hours of revision later.

The Flow: Discussion to Planning

Here’s how preferences flow into implementation:

Roadmap (brief) --> Discuss Phase --> CONTEXT.md --> Research Phase --> Plan Phase --> Execution

                    [Gray Areas]        [Decisions]     [Patterns]      [Tasks]
                    [Questions]         [Deferred]      [Investigate]   [Implement]
                                        [Discretion]

The researcher reads CONTEXT.md to know what patterns to investigate. The planner reads it to know what decisions are locked. Both agents operate with your preferences baked in.

Summary

In this post, I explained how /gsd-discuss-phase captures your implementation preferences before planning begins. GSD identifies gray areas based on phase type: visual features ask about layout/density/interactions, APIs ask about format/error handling, content systems ask about structure/tone/depth. CONTEXT.md captures locked decisions (NON-NEGOTIABLE), deferred ideas (BLOCKED), and discretion areas (judgment allowed). The planner reads CONTEXT.md and verifies every locked decision has a corresponding task. Assumptions mode lets GSD read your codebase and surface structured assumptions instead of asking questions. Flags like --all, --auto, --batch, and --chain control how discussion works.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!