gdd-discuss

name	gdd-discuss
description	Adaptive design interview command that spawns design-discussant in normal / --all / --spec mode to gather decisions via one-question-at-a-time AskUserQuestion, writing D-XX entries to STATE.md <decisions>. Use when locking design decisions outside the main pipeline or backfilling missing context.
argument-hint	[topic] [--all] [--spec] [--cycle <name>]
tools	Read, Write, Task

/gdd:discuss

Role: You are the /gdd:discuss command. You spawn the design-discussant agent with the right mode and context.

Step 1 - Read state

Read .design/STATE.md. Note:

• Current cycle: frontmatter value
• Highest existing D-XX number under <decisions>

If .design/STATE.md does not exist, tell the user to run /gdd:brief first and stop.

Step 2 - Parse arguments

Inspect $ARGUMENTS:

• Free-text before flags → <topic>
• --all → batch gray-areas mode
• --spec → Socratic ambiguity scoring mode
• --cycle <name> → scope decisions to that cycle

Step 3 - Spawn design-discussant

Task("design-discussant", """
<required_reading>
@.design/STATE.md
@.design/BRIEF.md
@.design/DESIGN-CONTEXT.md
@./.claude/skills
</required_reading>

<mode>{normal|--all|--spec}</mode>
<topic>{topic or omit}</topic>
<cycle>{cycle-name or omit}</cycle>

Run an adaptive design interview. Append D-XX decisions to STATE.md <decisions> block.
Emit `## DISCUSS COMPLETE` when done.
""")

Use only the modes the user actually passed. Missing flags → <mode>normal</mode>.

Step 4 - Inline glossary maintenance (CONTEXT.md)

When a fuzzy phrase is resolved into a sharper term, or a new domain concept is named during the interview: write to ./CONTEXT.md IMMEDIATELY (do NOT batch). Use the schema in ./../../reference/context-md-format.md - H2 heading per term, body paragraph, optional **Aliases:** line for term-merging. Multi-context repos use CONTEXT-MAP.md plus per-area <area>/CONTEXT.md. CONTEXT.md is lazy-created on the first term write.

Step 5 - Session wrap: ADR-offer scan

For each decision recorded this session, check ALL three criteria from ./../../reference/adr-format.md: (a) hard-to-reverse, (b) surprising-without-context, (c) real-tradeoff. If ALL three hold, offer to author docs/adr/NNNN-<slug>.md. If ANY criterion fails, the decision stays in STATE.md <decisions>. Routine choices are NEVER auto-promoted.

Step 6 - Report

Wait for ## DISCUSS COMPLETE. Re-read STATE.md. Count new D-XX entries since Step 1. Print:

━━━ Discuss complete ━━━
New decisions: N (D-XX through D-YY)
Mode: normal | --all | --spec
Cycle: <name or "default">
━━━━━━━━━━━━━━━━━━━━━━━━

Constraints

• Do not run the interview yourself - always spawn the agent.
• Do not touch files outside .design/.

Rationalizations - Thought to Reality

The shortcuts an agent takes during a discuss session, and what each one costs the decision record:

Thought	Reality
"I'll ask all eight questions at once to save time."	Batched questions overwhelm the user; one-at-a-time keeps each decision clean and prevents coupled answers.
"I can run the interview inline instead of spawning the discussant."	The skill's contract is to always spawn the agent - running it yourself skips the discussant's mode handling and D-XX numbering.
"This answer is good enough, I'll record it as a decision without follow-up."	A vague answer ("modern", "clean") recorded as a D-XX locks in an undecided premise; reject and re-ask once.
"I'll batch all the new D-XX entries into STATE.md at the end."	Decisions written atomically per answer survive an interrupted session; batching loses everything if the session drops.
"The glossary term can wait until I write the summary."	CONTEXT.md is written immediately per term - a deferred glossary entry is a naming inconsistency the next cycle inherits.
"Every decision this session is worth an ADR."	ADRs require all three criteria (hard-to-reverse, surprising, real-tradeoff); auto-promoting routine choices buries the genuinely essential ones.

DISCUSS COMMAND COMPLETE