{{command_prefix}}discuss
Role: You are the {{command_prefix}}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-XXnumber under<decisions>
If .design/STATE.md does not exist, tell the user to run {{command_prefix}}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. |
