agent-debate git:20260428.d7ffb13A

Immutable. This exact content never changes and is served at /api/v1/blob/413f1bec3c016add.

---
name: agent-debate
description: For consequential decisions (architecture choice, design trade-off, research design, business strategy), force two agents (typically Codex and Gemini, sometimes Claude vs another) to argue opposing positions for N rounds, then synthesize agreed facts vs contested points and recommend a resolution. Writes `.coord/debate_<topic>.md`. Use when the user asks "have Claude and Codex debate this", "adversarial review on X", "get a second opinion via debate", "I'm not sure about this design choice — make the agents argue it out".
---

# agent-debate

Anti-consensus tool. Most LLM output collapses to a single
"reasonable-sounding" answer that hides real trade-offs. For
**consequential decisions** (you'll regret picking the wrong
side), this skill stages an explicit pro/con debate between two
agents, then makes the disagreement legible.

This is **not** for routine choices — variable naming, file layout,
which library to use for a one-off script. It's for decisions where
there's a real trade-off and the "obvious" answer might be wrong.

## When to use

Trigger phrases:

- "Have Claude and Codex debate this design choice."
- "Adversarial review on `<decision>`."
- "Get a second opinion via debate."
- "I'm not sure about this — make the agents argue it out."
- "Steel-man both sides on `<topic>`."

Not for:

- Routine choices (pick whatever; doesn't matter long-term).
- Decisions where you already know the right answer and just want
  validation (that's confirmation bias; the debate will waste
  tokens).
- Open-ended brainstorming (use a single agent + lots of follow-ups).

## Inputs

User must provide:

1. **The decision** — phrased as a yes/no or A/B question.
   - Good: "Should we keep legacy.py as a deprecation shim or
     remove it?"
   - Bad: "What should we do about legacy.py?" (too open)
2. **Optional**: which agent argues which side. If unspecified, the
   skill picks based on agent strengths (see below).
3. **Optional**: number of rounds. Default 2 (each agent gets 2
   turns). More than 3 rarely adds signal.

## Workflow

### 1. Frame the decision

Restate the decision as a clear A vs B (or yes vs no). If the user
gave an open-ended question, propose the framing back to them and
get confirmation before spending tokens on a debate.

Example:
- User: "Should we cache LLM responses?"
- Skill: "Framing: **A) Yes, add an LRU cache keyed on prompt
  hash** vs **B) No, every call is unique enough that caching adds
  bug surface without saving money.** Confirm before I proceed."

### 2. Assign sides

Default heuristic:

| Position character | Best argued by |
|---|---|
| "We should ship the simpler / less-surface option" | Claude (judgment-heavy, conservative bias) |
| "We should optimize for X performance / scale dimension" | Codex (concrete with numbers) |
| "We should consider edge cases X / Y / Z that the obvious answer misses" | Gemini (long-context, edge-case catching) |
| "We should follow the convention from <reference codebase or paper>" | Gemini (synthesizing from external sources) |

If the user explicitly assigns sides, use those. Otherwise propose
the assignment and confirm.

### 3. Initialize `.coord/debate_<topic>.md`

```markdown
# Debate — <topic-slug>

**Decision:** <one-line A vs B framing>
**Rounds:** 2
**Side A** (argued by Codex): <position A>
**Side B** (argued by Gemini): <position B>
**Started:** 2026-04-28T...

---

## Round 1

### Side A — Codex
<task: read .coord/debate_<topic>.md, argue Side A from scratch>
<argument here>

### Side B — Gemini
<task: read .coord/debate_<topic>.md (which now contains Codex's
arg), argue Side B as a rebuttal>
<argument here>

---

## Round 2

### Side A — Codex
<task: read updated debate file, rebut Side B>
...
```

### 4. Generate task files for the debate rounds

For each agent's turn, write a task file in their delegate-skill
format:

`.ai/codex_task_debate_<topic>_round1.md`:

```markdown
# Task: Argue Side A in debate on <topic>

## Context
- Repo: <path>
- Read: .coord/debate_<topic>.md (the debate transcript so far)
- Side A: <position A>
- Your role: argue Side A. Be specific. Reference real code / files
  / numbers. Don't hedge ("on the other hand" is forbidden).
- Do NOT touch any source files. This is argument-only.

## Goal
Write a 200-400 word argument for Side A, focused on:
- The strongest specific reason Side A is right.
- The most concrete failure mode of Side B (with a worked example
  if possible).
- One thing Side B might say that you concede is a real cost of
  Side A.

## Acceptance
- Append your argument under "## Round 1 / ### Side A — Codex" in
  .coord/debate_<topic>.md.
- Keep argument 200-400 words. Longer = penalty.
- No "on the other hand" hedging.
```

Subsequent rounds: same template, but task file says "rebut Side B's
Round N argument; concede any genuinely strong point but explain
why Side A still wins net." Each round's task file references the
previous rounds in the debate file as input.

### 5. Run the rounds

Hand off to `codex-delegate` / `gemini-delegate` to execute each
agent's turn. They write into the debate file directly (the task
file says where to append).

### 6. Synthesize

After the final round, Claude (in-session, not delegated) reads
the full debate transcript and writes the synthesis at the bottom:

```markdown
---

## Synthesis (Claude as judge)

### Agreed facts (both sides accept)
- <facts that emerged from the debate as common ground>

### Contested points (genuine disagreement)
- <points where neither side conceded>

### Decision
- **Recommendation:** A or B (with one-paragraph rationale).
- **Confidence:** high / medium / low.
- **What would change my mind:** <falsifiable condition>.
```

### 7. Hand off

```
[agent-debate]
  Topic: <topic-slug>
  Rounds: 2
  Transcript: .coord/debate_<topic>.md
  Synthesis: bottom of same file
  Recommendation: <A or B>, confidence <high/medium/low>

  Update .coord/memory.yml with this decision via agent-shared-memory
  if you accept the recommendation.
```

## Anti-patterns to avoid

- **Forcing both sides to be equally strong** when one is genuinely
  weaker. Honest debate sometimes ends "Side A wins decisively." If
  that's what came out, say so — don't manufacture a 50-50 to seem
  balanced.
- **Letting both sides converge to the same view by Round 2** ("both
  sides agree the answer is C, a third option neither argued"). If
  that happens, scrap the debate — neither side actually committed.
  Restart with stronger framing.
- **More than 3 rounds.** Diminishing returns kicks in fast. If you
  haven't found the disagreement by round 3, the question wasn't
  contested enough to debate.
- **Debating something where you already know the answer.** That's
  confirmation theater, not adversarial review.

## What NOT to do

- **Don't write source code as a side effect of the debate.** The
  task files explicitly forbid touching source. Debate is
  argument-only; implementation comes after the user picks a side.
- **Don't have the same agent argue both sides.** Different agents
  have different priors / blind spots — that's the point.
- **Don't update `.coord/memory.yml` automatically.** The
  recommendation goes there only if the user accepts it. Use
  `agent-shared-memory` separately to log the decision.