discuss

What It Does

discuss is the interactive front door to every GSD project. It runs when the user invokes /gsd, /gsd discuss, or /gsd steer, opening a structured conversation that transforms a raw idea into a complete, actionable milestone plan. The prompt is deliberately opinionated about the order of operations: reflection before questions, mandatory codebase investigation before the first question round, and a depth checklist that must be fully satisfied before any roadmap gets written.

The conversation unfolds in a fixed sequence of stages. First the prompt asks “What’s the vision?” and immediately proves comprehension by reflecting back a concrete summary — including an honest size read (roughly how many milestones, roughly how many slices) and a bullet list of major capabilities. This forces the agent to demonstrate understanding before asking anything. Only after the user confirms the reflection does the prompt advance to deep questioning, which continues for as many rounds as the scope demands: simple well-defined work may need one round, a large ambiguous vision may need four or more.

For multi-milestone visions, the prompt maps the full landscape before drilling into details — proposing a milestone sequence with names, one-line intents, and rough dependencies. An anti-reduction rule governs scope: the prompt does not ask “what’s the minimum viable version?” or try to shrink the user’s ambition. When something is complex or risky, it gets phased into a later milestone — not cut. If the user describes a big vision, the prompt plans the big vision.

Before asking its first question, the prompt runs a mandatory investigation pass — scouting the codebase, checking library docs via resolve_library / get_library_docs, and running targeted web searches. The prompt prefers search_and_read for one-shot topic research (combining search and page fetch in a single call) and maintains a web search budget across the multi-turn discussion; library lookups don’t consume the budget, and searches are distributed across turns rather than clustered. The goal is that first questions reflect what is actually true, not what is assumed.

The {{structuredQuestionsAvailable}} flag controls the interaction mode for the entire discussion. When true, question rounds, depth verification, and milestone readiness gates all use ask_user_questions for structured form UX — with options, a freeform escape hatch, and one call per turn. When false, all of these use plain-text mode instead. The same non-bypassable gate logic applies on both paths; the flag changes the mechanism, not the rules.

The prompt maintains a depth checklist throughout the discussion: what is being built, why it needs to exist, who it’s for, what “done” looks like, the biggest technical unknowns, and what external systems it touches. Every two question rounds the prompt silently saves a CONTEXT-DRAFT.md via gsd_summary_save to protect confirmed work against session crashes — this is never surfaced to the user. When all depth checklist items are satisfied, the prompt enters a depth verification gate — printing a structured summary in chat and then confirming with either ask_user_questions (question ID must contain depth_verification) or a plain-text confirmation request. This naming convention is mechanically detected downstream. If the user clarifies, the agent absorbs the correction and re-verifies before proceeding.

Once depth is confirmed the prompt runs a focused research pass — using resolve_library, get_library_docs, search-the-web, search_and_read, and fetch_page to surface table-stakes requirements, domain-standard behaviors, likely omissions, and scope traps — and produces a REQUIREMENTS.md capability contract. Requirements are organised as Active, Validated, Deferred, Out of Scope, and Traceability sections, each with a stable R### ID, source annotation, and slice ownership. The full requirements table is printed in chat before any file is written; the user can confirm, adjust, or add before the roadmap is generated. This gate is non-bypassable — the prompt must re-ask if the user does not respond or gives an ambiguous answer.

After requirements are confirmed, the prompt performs a scope assessment — re-checking whether the size estimate from the reflection still holds after everything discovered in the discussion. If the scope grew or shrank materially, milestone and slice counts are adjusted before any files are written.

Before writing files the prompt also prints a roadmap preview in chat — one row per slice with columns for Slice, Title, Risk, Depends, and Demo — so the user can approve the plan before it lands on disk. There is no second meta-gate asking for permission after depth verification; the depth verification is the write-gate, and the roadmap preview is a final confirmation opportunity. This gate is also non-bypassable — a missing response is not a “yes.” The roadmap itself is created by calling gsd_plan_milestone; architectural decisions made during discussion are recorded via gsd_decision_save.

For multi-milestone visions the prompt handles the full milestone sequence: calling gsd_milestone_generate_id for each milestone, writing shared artifacts (PROJECT.md, REQUIREMENTS.md, DECISIONS.md), producing a full CONTEXT.md and roadmap for the primary milestone, and then running a sequential readiness gate for each remaining milestone — one at a time — offering Discuss now, Write draft for later, or Just queue it. After every gate decision the prompt immediately updates .gsd/DISCUSSION-MANIFEST.json with cumulative gate state. Auto-mode is mechanically blocked until gates_completed equals total in this file. CONTEXT.md files for milestones that depend on earlier milestones must carry depends_on YAML frontmatter — the auto-mode state machine reads this field to enforce execution order.

Pipeline Position

discuss runs once at the start of a project or whenever the user wants to plan new work. It is the only GSD prompt that owns the milestone planning ceremony — all downstream prompts operate on the artifacts this prompt produces. When /gsd steer is used mid-project, this same prompt re-enters the discussion flow with existing milestone context already loaded.

Variables

Variable	Description	Required
preamble	Opening context paragraph describing the current project state and the intended scope of this discussion	Yes
preparationContext	Injected preparation context block assembled by the dispatcher — codebase snapshot, existing planning artifacts, and any prior discussion state the agent should be aware of before the investigation step	Yes
structuredQuestionsAvailable	Boolean flag indicating whether the ask_user_questions tool is available — controls whether question rounds, depth verification, and readiness gates use structured form UX or plain-text mode throughout the discussion	Yes
milestoneId	Current active milestone identifier for scoping the discussion and naming output files	Yes
contextPath	File path to the CONTEXT.md document to write upon completion of the discussion	Yes
commitInstruction	Instruction block telling the agent how to commit GSD state changes at the end of a single-milestone discussion	Yes
multiMilestoneCommitInstruction	Extended commit instruction used when the discussion spans multiple milestones	Yes
inlinedTemplates	Pre-assembled block of GSD output templates (context, roadmap, requirements, decisions, project) for use during the output phase	Yes

Used By

• /gsd — primary invocation; opens the project planning wizard
• /gsd discuss — explicit discuss invocation; same prompt, surfaced directly
• /gsd steer — mid-project steering; re-enters the discussion flow with current milestone context