/gsd discuss

What It Does

/gsd discuss runs a guided interview so you can record intent before auto mode plans and executes work. It has three modes depending on where you are in the project:

Slice discussion — Pick a pending slice in the active milestone, answer questions about UX, edge cases, and scope, and the agent writes a CONTEXT.md for that slice. Auto mode reads this file when planning so your intent is baked in from the start.
Milestone discussion (needs-discussion phase) — If the active milestone has a CONTEXT-DRAFT.md but no full context or roadmap yet, /gsd discuss routes to a milestone-level interview instead of the slice picker.
Queued milestone discussion — If there is no active milestone but the registry has pending milestones, or if you select “Discuss a queued milestone” from the slice picker, the agent runs a milestone-level interview without activating the milestone. This is how you pre-populate context for work that hasn’t started yet.

This is useful when you know things the agent doesn’t: how a feature should feel to the user, what happens in failure states, which edge cases are in scope, or what a slice should explicitly not do. /gsd discuss is where that intent gets captured before planning starts.

The discussion is behaviour-focused, not tech-focused. The agent asks about what the user sees and experiences, what should happen when things go wrong, and where scope begins and ends. Library choices, architecture, and naming conventions are left for the research and planning phases — unless a technical choice materially changes scope or integration behaviour, in which case the agent asks directly.

Usage

/gsd discuss

No flags. Requires a GSD project (.gsd/ directory) with at least one milestone. The slice picker flow additionally requires the active milestone to have a roadmap and at least one pending slice. The needs-discussion flow works without a roadmap. If there is no active milestone, at least one queued milestone must exist in the registry.

How It Works

The slice picker

GSD reads the active milestone’s slice list and filters to slices that are not yet complete. Each slice is shown with its discussion status — “discussed ✓” or “not discussed” — so you can see at a glance what’s left. The first undiscussed slice is pre-selected as the recommended choice. Active slices (currently being executed) are labelled “active” rather than “upcoming”.

If there are any pending (queued) milestones in the registry, a “Discuss a queued milestone” option appears at the bottom of the picker. Selecting it opens a separate milestone picker without affecting the current milestone’s execution.

The picker loops: after each discussion finishes, it returns to the picker so you can chain multiple slice interviews in one session. When all pending slices have been discussed, it checks whether any queued milestones remain before exiting — if they do, it routes to the queued milestone picker automatically.

If a slice already has a CONTEXT.md from a prior discussion, selecting it shows a re-discuss confirmation. Confirming launches an update interview that reads the existing context, asks about changes and new decisions, then rewrites the file with merged findings.

The guided interview

The interview is a back-and-forth conversation, not a form. Before asking anything, the agent scouts the codebase and reads surrounding context so its questions are grounded in what actually exists. It focuses on:

UX and user-facing behaviour — What does the user see, click, trigger, or experience?
Edge cases and failure states — What happens when things go wrong or are in unusual states?
Scope boundaries — What is explicitly in vs out for this slice? What’s deferred to later?
Feel and experience — Tone, responsiveness, feedback, transitions, what “done” feels like

Questions come in rounds of 1–3 at a time. The agent continues asking rounds until it genuinely believes the slice is well understood. Only then does it offer a wrap-up choice: “Write the context file” or “One more pass.” You decide the pace.

Non-bypassable write gate: The agent cannot write the context file until you explicitly select “Write the context file.” If the option is dismissed or the tool fails, it re-asks rather than proceeding. This gate protects the interview work from being bypassed.

Incremental persistence: Every two question rounds, the agent silently saves a draft <SID>-CONTEXT-DRAFT.md to the slice directory. This protects confirmed work against session crashes. The draft is invisible to you — the final CONTEXT.md replaces it when you choose to write.

Context loaded before each interview

To make questions grounded and specific, the agent preloads the following before starting each slice interview:

The milestone roadmap (to understand surrounding slices and dependencies)
The milestone context file (to understand the broader milestone intent)
Milestone research notes, if they exist
The decisions register (for architectural constraints that bound this slice)
Completed slice summaries (to know what’s already been built that this slice builds on)

The CONTEXT.md output

The interview produces a slice CONTEXT.md at .gsd/milestones/<MID>/slices/<SID>/<SID>-CONTEXT.md. This file becomes authoritative input for the planning phase — when auto mode later plans this slice, it reads the CONTEXT.md to understand your intent for behaviour, scope, and feel.

The context file is structured around:

Goal — one sentence: what this slice delivers
Why this Slice — why now, what it unblocks
Scope / In Scope — what was confirmed in scope during the interview
Scope / Out of Scope — what was explicitly deferred or excluded
Constraints — hard constraints the user flagged
Integration Points — what this slice consumes and produces
Open Questions — anything still unresolved, with current thinking

The agent preserves your exact terminology, emphasis, and specific framing rather than paraphrasing it into generic summaries. The context file is the downstream planner’s only window into this conversation.

Queued milestone discussion

When there is no active milestone (all are complete or none exist yet), /gsd discuss shows a picker of pending milestones from the registry. Selecting one launches a milestone-level interview for that milestone.

The same option is available from inside the slice picker — even when there is an active milestone, you can break out and discuss an upcoming queued milestone to get its context ready in advance. Discussing a queued milestone does not activate it. Auto mode will still pause when it reaches that milestone and prompt you to confirm, but the context file will already be written so the actual planning can begin immediately.

When a queued milestone already has a CONTEXT-DRAFT.md, the discussion seeds itself automatically from that draft and fast path mode is applied — broad codebase scouting is skipped and the draft is treated as authoritative seed context. When there is no draft, you are offered two modes:

Full discussion — Scout the codebase, ask open-ended questions, explore deeply. Use this when you haven’t thought through the milestone scope yet.
I have the scope — fast path — Treat your first message as authoritative seed context; skip codebase scouting. Use this when you already know exactly what the milestone should do and just want to lock in the context quickly.

Needs-discussion phase

If the active milestone is in a needs-discussion state — it has a CONTEXT-DRAFT.md from an earlier multi-milestone discussion but no full CONTEXT.md or roadmap yet — /gsd discuss routes to a milestone-level discussion instead of the slice picker. It offers three choices:

Discuss from draft — Seeds the new discussion with the draft content so nothing from the prior conversation is lost
Start fresh discussion — Discards the draft and begins a clean discussion
Skip — create new milestone — Leaves this milestone as-is and starts a fresh vision discussion for the next milestone

Integration with auto mode

When auto mode encounters a slice that has a CONTEXT.md, it uses that file during planning. The planner reads it alongside the roadmap entry to produce a more informed slice plan — one that reflects your stated behavioural intent rather than only what the roadmap entry describes.

What Files It Touches

Reads

File	Purpose
`.gsd/milestones/<MID>/<MID>-ROADMAP.md`	Slice list and completion status
`.gsd/milestones/<MID>/<MID>-CONTEXT.md`	Milestone-level intent and constraints
`.gsd/milestones/<MID>/<MID>-RESEARCH.md`	Technical research notes (if present)
`.gsd/DECISIONS.md`	Architectural decisions that constrain this slice
`.gsd/milestones/<MID>/slices/<SID>/<SID>-SUMMARY.md`	Completed slice summaries (for context)
`.gsd/milestones/<MID>/<MID>-CONTEXT-DRAFT.md`	Draft seed for needs-discussion phase
`.gsd/milestones/<MID>/slices/<SID>/<SID>-CONTEXT.md`	Existing slice context (for re-discuss flow)

Creates

File	Purpose
`.gsd/milestones/<MID>/slices/<SID>/`	Created if the slice directory doesn’t exist
`.gsd/milestones/<MID>/slices/<SID>/<SID>-CONTEXT.md`	Written on first discussion of a slice
`.gsd/milestones/<MID>/<MID>-CONTEXT.md`	Written when discussing a milestone (needs-discussion or queued flow)

Writes

File	Purpose
`.gsd/STATE.md`	Rebuilt from derived state before each dispatch
`.gsd/milestones/<MID>/slices/<SID>/<SID>-CONTEXT-DRAFT.md`	Incremental draft saved every 2 question rounds to protect against crashes
`.gsd/milestones/<MID>/slices/<SID>/<SID>-CONTEXT.md`	Slice context from the interview; rewritten on re-discuss
`.gsd/milestones/<MID>/<MID>-CONTEXT-DRAFT.md`	Incremental draft saved every 2 question rounds during milestone-level discussions
`.gsd/milestones/<MID>/<MID>-CONTEXT.md`	Updated when a milestone-level re-discussion concludes

Examples

Discussing an upcoming slice in a Cookmate project:

> /gsd discuss

● GSD — Discuss a slice
  M001: Core Recipe Platform
  Pick a slice to interview. Context file will be written when done.

  Slices:
    S03: Recipe search and filtering  · upcoming · not discussed  (recommended)
    S04: Image upload pipeline        · upcoming · not discussed
    S05: User profiles                · upcoming · not discussed
  ──────────────────────────────────────────────────────
    Discuss a queued milestone

> S04: Image upload pipeline

● Starting interview for S04: Image upload pipeline
  [Agent scouts codebase, reads roadmap, milestone context, decisions register]

  When a user picks a photo from their camera roll, what should happen before
  they see it on the recipe?
> It should show a preview immediately. Upload in background. If upload fails,
  keep the draft recipe and show a retry banner — don't block saving.

  What's the right feel for the upload progress indicator?
> Subtle — a thin progress bar under the image, not a modal spinner. Upload
  should feel like it's just happening, not like a big deal.

  What image sizes should be stored, and is there a file size cap?
> Three sizes: thumbnail (200px), medium (800px), full (2400px). Max 5MB.
  Use Cloudinary for storage — presigned URLs from client direct, don't
  proxy through our API.

  [Agent decides depth is sufficient, offers wrap-up]
  Write the context file  (recommended)
  One more pass
> Write the context file

● Writing .gsd/milestones/M001/slices/S04/S04-CONTEXT.md
  ✓ S04 context written.

● GSD — Discuss a slice
  [Returns to picker with S04 now marked "discussed ✓"]

When all slices are covered:

> /gsd discuss

● All 3 slices discussed. Run /gsd to start planning.

Re-discussing a slice to update its context:

> /gsd discuss

  Slices:
    S04: Image upload pipeline  · upcoming · discussed ✓  (recommended)

> S04: Image upload pipeline

● Re-discuss S04?
  S04 already has a context file from a prior discussion.
  Re-discussing will interview for updates and rewrite the context file.

  Re-discuss to update context  (recommended)
  Cancel
> Re-discuss to update context

  [Agent reads existing S04-CONTEXT.md, asks about any changes since last time]

Discussing a queued milestone using the fast path:

> /gsd discuss

  Slices:
    S01: Authentication  · active · discussed ✓
    S02: Dashboard       · upcoming · not discussed  (recommended)
  ──────────────────────────────────────────────────────
    Discuss a queued milestone

> Discuss a queued milestone

● GSD — Discuss a queued milestone
  Select a queued milestone to discuss.
  Discussing will update its context file. It will not be activated.

  M002: Analytics & Reporting  [queued] · no context yet  (recommended)
  M003: Team collaboration     [queued] · no context yet

> M002: Analytics & Reporting

● Discuss M002
  Choose how to start the discussion.
  Fast path skips generic scouting — use it when you already know the scope.

  Full discussion  (recommended)
  I have the scope — fast path

> I have the scope — fast path

> We need dashboard charts for DAU, retention cohorts, and funnel drop-off.
  All data lives in the existing analytics_events table. No new ingestion.

  [Agent treats first message as authoritative seed, skips scouting, writes context]
  ✓ M002 context written.

/gsd auto — Autonomous execution (reads slice CONTEXT.md during planning)
/gsd — Step mode execution and project wizard
/gsd queue — Add future milestones to the pipeline
/gsd status — Check milestone progress
/gsd steer — Hard override for changing direction mid-execution

Previous
/gsd quick Next
/gsd steer