discuss

name	discuss
description	Socratic brainstorming to explore approaches before implementation
disable-model-invocation	false

/mz:discuss

Facilitate Socratic brainstorming that explores 5+ alternative approaches before converging on a direction. Produces CONTEXT.md-compatible output for downstream planning. Works both within phase context and as standalone brainstorming.

Reference @skills/init/design-system.md for visual output formatting. Reference @skills/shared/presentation-standards.md for content formatting and Next Up block rules. Reference @skills/shared/interview-language.md for language detection and session-wide persistence rules. Reference @skills/shared/terminology.md for official term definitions.

Step 1: Display Banner

Output the stage banner:

+===============================================+
|  MEGAZORD > DISCUSS                           |
+===============================================+

Step 1b: Language Detection

Detect the user's language from their first natural-language message following the rules in @skills/shared/interview-language.md.

Apply the detected language to all Socratic dialogue: seed questions, challenges, suggestions, summaries, convergence prompts, and the final output document's prose sections.

Keep in English: file paths, CONTEXT.md section headers (<domain>, <decisions>, <specifics>, <deferred>), technical terms, and command names.

Step 2: Determine Context

Parse the user's invocation to determine where output will be written.

Phase context detection (in priority order):

1. Explicit phase number -- user provides a phase number (e.g., /mz:discuss 7):

   • Read .planning/STATE.md to resolve the phase directory
   • Target: {phase_dir}/{padded}-CONTEXT.md (e.g., .planning/phases/07-quality-and-debugging-skills/07-CONTEXT.md)

2. Active phase -- no explicit number, but a phase is in progress:

   • Read .planning/STATE.md for current position
   • If a phase is active (status is "In Progress"): target that phase's CONTEXT.md
   • If the phase CONTEXT.md already exists, note it will be overwritten

3. Standalone -- no phase context at all:

   • Target: .planning/brainstorms/{YYYY-MM-DD}-{slug}.md
   • Create .planning/brainstorms/ directory if it does not exist
   • Generate {slug} from the topic (lowercase, hyphens, max 40 chars)

Display the output target:

> Output: {target file path}

Extract the topic from the user's message (text after /mz:discuss and any phase number). If no topic is provided, ask the user what they want to brainstorm about before proceeding.

Step 3: Seed the Conversation

Ask the user a probing SEED question about their topic. This is NOT a generic "what do you want?" -- it is a question that:

• Demonstrates understanding of the topic domain
• Challenges an implicit assumption the user may hold
• Opens an exploration angle that reveals constraints or trade-offs

Good seed examples:

• Topic "authentication approach" -- "Before we explore approaches -- what's your threat model? Are we protecting user data from external attackers, or also from other authenticated users?"
• Topic "database choice" -- "What's the read/write ratio you're expecting? That changes which options are even viable."
• Topic "monorepo vs polyrepo" -- "How many teams will contribute to this codebase, and do they deploy independently? That's the real forcing function here."

Bad seeds (avoid):

• "What kind of authentication do you want?" (too generic, no challenge)
• "Tell me more about your project." (interviewer tone)
• "Here are 5 options: 1. JWT 2. Sessions 3. OAuth..." (numbered lists, not Socratic)

Step 4: Iterative Dialogue

Maintain an internal counter of distinct approaches explored. For each exchange with the user:

1. Listen -- understand what the user said, identify the core idea
2. Challenge -- find an assumption in their answer and probe it: "What if {assumption} wasn't true? How would that change your approach?"
3. Suggest -- offer an alternative angle: "Have you considered {approach}? It handles {specific concern} differently."
4. Build -- extend their ideas: "Building on that, what if you combined {their idea} with {new element}?"
5. Track -- count each distinct approach explored (an approach counts as distinct when it differs in architecture, trade-offs, or core mechanism)

Tone rules:

• Thinking partner, not interviewer -- build iteratively on what the user says
• No numbered option lists -- weave alternatives into natural dialogue
• Genuine curiosity -- "That's interesting because..." not "Great idea!"
• Direct when challenging -- "That approach has a problem: {evidence}" not "That might possibly have some issues"

Convergence triggers:

After at least 5 distinct approaches have been explored, pause the Socratic dialogue and display a structured checkpoint — NOT a bare nudge:

### Discussion Checkpoint

{Summary of decisions taken so far — Claude's discretion: bullets if 1-3 decisions, short paragraph if 4+}

**Approaches explored:** {N}
**Decisions so far:** {list key decisions/directions that emerged}

Want to go deeper, or ready to move on?

The skill does NOT force convergence — the user may want to explore more.

Soft limit: after 10-15 exchanges without convergence, use the same checkpoint format with stronger framing: "We've covered significant ground. Here's where we are:" followed by the structured checkpoint block.

Key rule: The checkpoint is a structured format for clarity. The dialogue BEFORE the checkpoint stays fully Socratic. Do NOT make the entire dialogue structured — only the checkpoint moments.

Step 5: Convergence

If user responds "go deeper" (or equivalent: "more", "continue", "keep going"):

• Return to Step 4 Socratic dialogue immediately
• No summary table yet — that comes at the next checkpoint

If user responds "ready" (or equivalent: "done", "let's move on", "ship it"):

• Write CONTEXT.md directly — NO preview or confirmation step
• Skip the approach comparison table
• Extract decisions from the discussion, organize into CONTEXT.md sections, write the file
• Jump to Step 6 output confirmation

If user picks a specific direction or asks for the summary table:

• Show the approach comparison table:

  Approach	Strengths	Weaknesses
  {approach 1}	{strengths}	{weaknesses}
  {approach 2}	{strengths}	{weaknesses}
  ...	...	...

  Present the table in the session language. Column headers and approach names may mix English technical terms with session-language descriptions.

• Ask: "Want to go with this direction, or explore more?"

• If they confirm a direction, proceed to CONTEXT.md write

• If they want to explore more, return to Step 4

Step 6: Output

Write the output file using the CONTEXT.md format (compatible with /mz:plan and /gsd:discuss-phase output):

# {Topic} - Context

**Gathered:** {YYYY-MM-DD}
**Status:** Ready for planning

<domain>
## Phase Boundary

{Concise description of the decision scope -- what this brainstorming session covered}
</domain>

<decisions>
## Implementation Decisions

### {Decision 1 Title}
- {Bullet point detail}
- {Bullet point detail}

### {Decision 2 Title}
- {Bullet point detail}

### Claude's Discretion
{Areas explicitly left to implementer judgment -- things discussed but not locked}
</decisions>

<specifics>
## Specific Ideas

- {Concrete implementation idea from the discussion}
- {Another specific idea}
- {Technical detail worth preserving}
</specifics>

<deferred>
## Deferred Ideas

{Ideas explicitly deferred during discussion -- "None" if nothing was deferred}
</deferred>

Display confirmation:

> Context written to {file path}
> {N} approaches explored, {M} decisions locked

Step 7: Next Up

If phase context (active phase or explicit phase number):

## Next Up

**Plan Phase {N}: {Phase Name}** — turn decisions into executable tasks
`/mz:plan {N}`

<sub>`/clear` — start fresh context for the next step</sub>

If standalone (no phase context):

## Next Up

**Use this context** — reference {output file path} in your next planning session

<sub>`/clear` — start fresh context for the next step</sub>

Key Behaviors

• Minimum 5 alternative approaches explored before convergence is offered (user decision -- overrides default of 3)
• Socratic dialogue throughout: probing questions, not questionnaires or numbered lists
• Thinking partner tone: build on ideas, challenge assumptions, genuine curiosity
• Structured checkpoints at convergence moments: summary of decisions taken + "Want to go deeper?" — NOT a bare nudge
• "Ready" shortcut: if user says "ready" (or equivalent), write CONTEXT.md directly without preview or confirmation
• Output format: CONTEXT.md compatible (domain/decisions/specifics/deferred sections)
• Works standalone: brainstorm without any project or phase context, output to .planning/brainstorms/
• No auto-trigger: this skill is manually invoked by the user (not triggered automatically during execution)
• Session language: Detect from first message, apply to all dialogue output per @skills/shared/interview-language.md

Error Handling

Error	Step	Action
No topic provided	Step 2	Ask the user what they want to brainstorm about. Do not proceed without a topic.
STATE.md missing	Step 2	Fall back to standalone mode. Output to .planning/brainstorms/.
Phase directory missing	Step 2	Create the directory, or fall back to standalone mode if creation fails.
User disengages	Step 4	After 2 unanswered prompts, offer to converge with what has been explored so far.

Notes

• ALWAYS use bun/bunx for any JavaScript/TypeScript operations (never npm/npx).
• The output format is intentionally identical to /gsd:discuss-phase output for backward compatibility.
• When overwriting an existing CONTEXT.md, preserve any content not covered by this session by noting it in the deferred section.
• The 5-approach minimum is a floor, not a ceiling. Rich topics may explore 8-10+ approaches.