design-debate

Design Debate (MAD Pattern)

Overview

Escalation skill for the DESIGN phase. When brainstorming detects competing architectures, cross-cutting concerns, or high-stakes decisions, this skill orchestrates a Multi-Agent Debate with three perspectives to avoid echo-chamber thinking.

This skill is opt-in. It only activates when brainstorming explicitly escalates after user approval.

When to Escalate

The brainstorming skill should consider escalating when it detects:

Signal	Example
Multiple competing architectures	"We could use microservices or a monolith"
Cross-cutting concerns	Auth + data + API all affected
High-stakes decisions	"This will be hard to change later"
User explicitly requests debate	"I want different perspectives on this"
Ambiguity after 3+ questions	Still unclear on approach after extended exploration

Always ask the user first: "This has competing approaches. Want me to run a design debate with multiple perspectives?"

Team Composition

Teammate	Role	Lens
architect	Lead designer	Proposes architecture, defends trade-offs
critic	Devil's advocate	Attacks assumptions, finds blind spots, proposes alternatives
pragmatist	Implementation realist	Evaluates feasibility, YAGNI, timeline, complexity cost

Debate Protocol

1. TeamCreate("design-debate")

2. Share context with all teammates:
   - Problem statement
   - Constraints identified during brainstorming
   - Options explored so far
   - User preferences expressed

3. Round 1 (parallel):
   - subagent_type: "general-purpose"
   - architect: Proposes approach with reasoning
   - critic: Identifies blind spots and alternatives
   - pragmatist: Evaluates feasibility and complexity cost

4. Round 2 (parallel):
   - Each responds to the others' positions
   - Converge toward consensus or clearly articulated trade-offs

5. Lead synthesizes:
   - Present recommendation with dissenting views noted
   - Highlight unresolved trade-offs

6. User decides:
   - Approve → TeamDelete, write design doc
   - Reject → another round or manual override

Constraints

• 2 rounds maximum — prevents runaway token burn
• Opt-in only — brainstorming asks user before escalating
• Ephemeral team — created and destroyed within DESIGN phase
• Output is a design doc — docs/plans/YYYY-MM-DD-*-design.md

Communication Contract

All inter-agent messages use plain text via SendMessage. No structured JSON.

POSITION: [propose | critique | evaluate]
Stance: Use event sourcing for audit trail
Reasoning: Provides immutable history, enables replay, fits compliance requirements
Risks: complexity, learning curve, storage growth
Confidence: high | medium | low

Spawn Prompts

Architect

You are the architect in a design debate. Your job is to propose the best architecture for the problem and defend your trade-offs.

Context: {problem_statement}
Constraints: {constraints}
Options explored: {options}

Propose your recommended architecture using the plain-text POSITION format. Be specific about components, data flow, and integration points.

Critic

You are the critic in a design debate. Your job is to attack assumptions, find blind spots, and propose alternatives the architect may have missed.

Context: {problem_statement}
Architect's proposal: {architect_position}

Challenge the proposal using the plain-text POSITION format. Focus on: hidden assumptions, failure modes, scaling issues, maintenance burden, and alternative approaches.

Pragmatist

You are the pragmatist in a design debate. Your job is to evaluate feasibility, complexity cost, and whether the proposed approach is the simplest thing that could work.

Context: {problem_statement}
Architect's proposal: {architect_position}
Critic's challenges: {critic_position}

Evaluate using the plain-text POSITION format. Focus on: implementation timeline, team skill requirements, YAGNI violations, incremental delivery options, and operational complexity.

Output

Check session preset first. Read ~/.claude/skill-config.json or check the activation context for the active preset. If the preset has openspec_first: true (e.g., spec-driven), use the spec-driven mode below. Otherwise, use solo mode.

Spec-driven mode (preset: spec-driven)

After the debate, create openspec/changes/<topic>/ (committed, visible to teammates):

1. openspec/changes/<topic>/proposal.md:

   • Why — problem statement
   • What Changes — summary of the decision
   • Capabilities — Added/Modified capabilities this change touches
   • Impact — affected code, APIs, dependencies

2. openspec/changes/<topic>/design.md:

   • Architecture — consensus or lead's recommendation
   • Dissenting views — what the critic and pragmatist flagged
   • Trade-offs — what we're accepting
   • Decisions & Trade-offs — rejected alternatives and rationale

3. openspec/changes/<topic>/specs/<capability>/spec.md:

   • Acceptance Scenarios — 2-4 GIVEN/WHEN/THEN scenarios defining success
   • Use RFC 2119 keywords (MUST, SHOULD, MAY) in UPPERCASE

Capability taxonomy inference (before deciding on <capability>):

First enumerate existing capabilities: ls openspec/specs/. Then apply this heuristic:

1. Noun-family match — core domain noun matches an existing capability? → prefer extending that capability.
2. Subsystem overlap — touches code paths already owned by an existing capability? → prefer extending that capability.
3. Genuinely new — no match? Auto-create openspec/specs/<new-capability>/.

When two existing capabilities look equally applicable, ask the user — do not guess.

When creating a new capability, emit a visible warning:

⚠️ NEW CAPABILITY: This change introduces capability <new-capability>. Confirm the taxonomy is correct before archive. Existing capabilities considered and rejected: <list>.

Bias: err toward fewer, coarser capabilities. Micro-capabilities fragment review routing; a single capability with multiple requirements scales better.

Solo mode (default)

After the debate, synthesize into a design document at docs/plans/YYYY-MM-DD-{topic}-design.md containing:

1. Problem statement — what we're solving
2. Capabilities affected — every subsystem/module this touches
3. Explicit out-of-scope — what this change does NOT do
4. Recommended approach — the consensus or lead's recommendation
5. Dissenting views — what the critic and pragmatist flagged
6. Trade-offs — what we're accepting
7. Acceptance scenarios — 2-4 GIVEN/WHEN/THEN scenarios defining success
8. Decision — what the user approved

Persistence: This artifact is the canonical design intent. It will be:

• Read by writing-plans to carry acceptance scenarios into the plan
• Read by agent-team-review for spec compliance checking
• Compared against as-built output by openspec-ship at archive time
• Archived to docs/plans/archive/ when the feature ships

Then return to the brainstorming skill's sequential flow → writing-plans.