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

Apr 21, 2026

Roadmap phases are usually described in a sentence or two. That’s not enough context for an AI to build something the way I imagine it. I needed a way to capture my implementation preferences before planning started. GSD’s /gsd-discuss-phase does exactly this.

Why Discussion Matters

When I look at a roadmap entry like “Phase 1: Build user dashboard”, I have a mental image of what that means. The layout I want, the density of information, how interactions should feel. But the AI planner doesn’t know any of this.

Without discussion, the planner guesses. Sometimes guesses are fine. Often they’re wrong. Discussion captures what I imagine so the planner doesn’t have to guess.

Gray Areas by Phase Type

GSD identifies different gray areas based on what’s being built:

Visual features ask about:

Layout: grid vs flex, sidebar vs topbar
Density: compact vs spacious, condensed vs verbose
Interactions: hover effects, click feedback, animations
Empty states: what shows when no data

APIs and CLIs ask about:

Response format: JSON vs XML, flat vs nested
Flags: long-form --verbose vs short -v
Error handling: HTTP codes vs error objects
Verbosity: minimal output vs detailed logging

Content systems ask about:

Structure: sections vs chapters, flat vs hierarchical
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 feature
Naming conventions: camelCase vs snake_case vs kebab-case
Duplicate handling: merge vs delete vs keep both
Exceptions: what gets special treatment

Phase Type         | Gray Areas Explored
-------------------|--------------------------------
Visual feature     | Layout, density, interactions, empty states
API/CLI            | Response format, flags, error handling, verbosity
Content system     | Structure, tone, depth, flow
Organization       | Grouping, naming, duplicates, exceptions

CONTEXT.md Output

After discussion, GSD produces a {phase}-CONTEXT.md file. This file has three types of entries:

Decisions (D-01, D-02, …) are locked. They MUST be implemented exactly as specified.

Deferred Ideas are blocked. They MUST NOT appear in plans.

Claude’s Discretion areas allow judgment. The planner makes choices and documents them.

# Phase 2: User Dashboard Context

## Decisions
- D-01: Use grid layout with 3-column cards (NOT flex)
- D-02: Density must be compact (max 4px padding)
- D-03: Hover effects use subtle border highlight

## Deferred Ideas
- Dark mode support (blocked for this phase)
- Real-time updates via WebSocket (blocked for this phase)

## Claude's Discretion
- Empty state message content
- Card ordering priority
- Mobile responsive breakpoints

How Planner Uses CONTEXT.md

The planner reads CONTEXT.md before creating tasks:

1. Load CONTEXT.md from previous discussion
2. Verify every locked decision has a task
3. Task actions reference decision ID (e.g., "per D-03")
4. No task implements deferred ideas
5. Discretion areas handled with documented choices

I ran a planner after creating CONTEXT.md and noticed every decision had a corresponding task. Task descriptions explicitly referenced the decision IDs. Deferred ideas didn’t appear anywhere. Discretion areas had reasonable choices with documentation.

Assumptions Mode: Codebase-First Analysis

Sometimes I don’t want questions. I want GSD to read my codebase first.

Assumptions mode does this:

GSD analyzes existing code patterns
Surfaces structured assumptions about how it would build
I confirm, correct, or expand on assumptions

This mode works well for:

Experienced developers who know their patterns
Rapid iteration on established projects
Features that extend existing architecture

I enable it via /gsd-settings:

/gsd-settings

# Change:
workflow.discuss_mode: 'assumptions'

# Now /gsd-discuss-phase reads codebase first
# Then surfaces assumptions for confirmation

Flags for Different Workflows

GSD supports several flags for the discuss phase:

# Interactive discussion with area selection
/gsd-discuss-phase 1

# Discuss all gray areas (no area selection prompts)
/gsd-discuss-phase 1 --all

# Auto-select recommended defaults
/gsd-discuss-phase 3 --auto

# Batch mode (grouped question intake, not one-by-one)
/gsd-discuss-phase 2 --batch

# Add trade-off analysis to each question
/gsd-discuss-phase 2 --analyze

# File-based bulk answers for power users
/gsd-discuss-phase 1 --power answers.yaml

# Auto-chain into plan+execute without stopping
/gsd-discuss-phase 1 --chain

The --chain flag is particularly useful. It runs discuss, then automatically continues to plan and execute. I use this when I want hands-off execution after capturing preferences.

What Happens Without Discussion

I tried running /gsd-plan directly without discussion. The planner made reasonable guesses, but:

Layout was flex when I wanted grid
Density was spacious when I wanted compact
Empty states showed generic messages when I wanted specific guidance

The result required multiple corrections. Each correction added commits to git history. The final product matched my intent, but the path was messy.

With discussion first, the first plan matched my intent. Clean commits, no corrections needed.

Discussion vs Planning

Discussion and planning serve different purposes:

DISCUSSION:
- Captures what I imagine
- Locks decisions I'm certain about
- Blocks ideas I don't want
- Allows discretion where I'm flexible

PLANNING:
- Uses decisions as constraints
- Researches patterns for locked decisions
- Makes reasonable choices in discretion areas
- Creates atomic tasks with verification

Discussion is about capturing preferences. Planning is about implementing them. The CONTEXT.md file is the bridge between my vision and AI execution.

When to Use Assumptions vs Questions Mode

Use QUESTIONS mode when:
- New project or unfamiliar codebase
- Team has mixed experience levels
- Want explicit confirmation on all choices
- Building something different from existing patterns

Use ASSUMPTIONS mode when:
- Experienced with the codebase
- Rapid iteration on established patterns
- Feature extends existing architecture
- Team has consistent conventions

I switch between modes depending on context. New features on established projects use assumptions. First-time features or unfamiliar areas use questions.

Summary

In this post, I explained how /gsd-discuss-phase captures implementation preferences before AI planning starts. The command identifies gray areas based on phase type: visual features get layout/density questions, APIs get format/error handling questions, content systems get structure/tone questions. The CONTEXT.md output locks decisions that must be implemented exactly, blocks deferred ideas from appearing in plans, and allows discretion where I’m flexible. Use --assumptions mode for codebase-first analysis when working with established patterns, or --chain for hands-off execution after capturing preferences.

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!