dirien/decide

<!-- Copyright 2025-2026 Richard Shade. Licensed under Apache-2.0. --> <!-- SPDX-License-Identifier: Apache-2.0 -->

Adversarial Consensus Protocol

Run a structured three-agent debate to reach consensus on a strategic decision. Two advocates steelman opposing positions while a moderator asks hard questions, identifies risks, and synthesizes the binding consensus.

Why this works: adversarial structure surfaces arguments brainstorming misses. Evidence-grounded research prevents epistemic closure. Forced concessions in Round 2 prevent entrenchment. The moderator writes the binding consensus after hearing both sides.

Pre-flight validation

Before running the debate, verify the input contains a genuine decision with at least two distinguishable options or courses of action.

If the input is a factual question, explanation request, or single-option statement, respond directly instead: "This protocol works best when choosing between alternatives. Could you rephrase with the options you're weighing, or ask me directly?"

When in doubt, proceed — err on the side of running the debate.

Phase 0: Research and frame the decision

Step 0.1: Gather context

Read project documentation and context files to understand the decision space. Common sources include README, architecture docs, product docs, recent git history, and any files the user referenced.

Step 0.2: Identify the two positions

From the decision topic, formulate two clear, opposing positions:

• Position A: one side of the decision
• Position B: the opposing side

If the topic naturally implies two sides (e.g., "gRPC vs REST"), use those directly. If the topic is open-ended (e.g., "pricing strategy"), research the space and formulate the two strongest opposing approaches.

Step 0.3: Identify constraints

Extract hard constraints from the user's message or project docs: budget limits, timeline requirements, team size, technical constraints, business requirements, non-negotiable values.

Step 0.4: Present brief

Generate the debate brief before proceeding. Evaluate against three conditions:

• Can the two positions be stated without significant overlap?
• Is the question genuine (not leading or presupposing an answer)?
• Are there at least two meaningfully distinct outcomes?

If all conditions pass, present the brief and proceed to Phase 1:

Decision: [one-line summary]
Position A: [name] — [one-sentence description]
Position B: [name] — [one-sentence description]
Constraints: [list any hard constraints]
Launching Round 1...

If any condition fails, present the brief and ask the user whether to reframe or proceed as-is.

Phase 1: Round 1 — position papers

Launch three agents in parallel. Each agent runs independently and cannot read the others' output.

• Advocate A: steelman Position A. Research externally to find at least 2 supporting sources. Write a comprehensive position paper with architecture, implementation plan, costs, timelines, risks, and mitigations. Cite sources inline.
• Advocate B: steelman Position B with the same structure and research requirements as Advocate A.
• Moderator: critically examine both positions using external counter-evidence. Find at least 2 sources that challenge each position. List the 10 hardest questions (5 per position), identify the 5 biggest risks per approach, propose a hybrid model, and reach a preliminary recommendation.

Compose agent prompts following references/debate-prompts.md — Round 1 section.

Synthesize Round 1

After all three agents complete, present to the user:

1. Where all three agree — table of consensus points
2. Where they disagree — table of tensions with each agent's position
3. Brief commentary on the key tensions

Then immediately proceed to Round 2.

Phase 2: Round 2 — forced convergence

Launch three agents in parallel. Each agent receives a summary of the other agents' arguments and must respond.

• Revised Advocate A: respond to the strongest challenges from Advocate B and the Moderator. Concede valid points honestly, defend where Position A remains strongest, and state a revised position.
• Revised Advocate B: same structure as Revised A, responding to challenges from Advocate A and the Moderator.
• Consensus Moderator: drive toward final consensus. Write the binding consensus document: the agreed model, resolved tensions, execution timeline, 3 key metrics, the single biggest risk, and a one-paragraph elevator pitch.

Compose agent prompts following references/debate-prompts.md — Round 2 section.

Phase 3: Present results

Step 3.1: Present the consensus

Show the user:

1. Key concessions from each advocate (what changed their minds)
2. The consensus model — the Moderator's final recommendation
3. Structure or plan details (tiers, architecture, timeline)
4. Key metrics to track
5. Biggest risk and mitigation

Step 3.2: Ask about persistence

Ask the user if they want to save the consensus. Determine the appropriate file based on the decision type:

• Business decisions → biz.md
• Architecture decisions → ARCHITECTURE.md or ADR-NNN.md
• Product decisions → PRODUCT.md
• Strategy → appropriate project document
• Or a new file if none fits

Orchestrator guidelines

• Always launch all 3 agents per round in a single step (parallel)
• Never edit the agents' arguments — present them faithfully
• The Moderator's Round 2 consensus is the binding output — but the user has final authority to override
• Keep your own commentary brief — the agents did the thinking; you synthesize and present
• If agents do not converge after Round 2, highlight the remaining disagreement and ask the user to break the tie rather than running more rounds
• Adapt prompt specifics to the domain — a pricing decision needs cost numbers; an architecture decision needs technical tradeoffs
• Include relevant project context in every agent prompt — agents run in isolation and cannot read each other's output