Agent Debate

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 ``."
• "Get a second opinion via debate."
• "I'm not sure about this — make the agents argue it out."
• "Steel-man both sides on ``."

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)

1. Optional: which agent argues which side. If unspecified, the

skill picks based on agent strengths (see below).

1. Optional: number of rounds. Default 2 (each agent gets 2

turns). More than 3 rarely adds signal.

1. Optional: context policy. Default debate turns are 200-400

words, final synthesis is " | Gemini (synthesizing from external sources) |

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

3. Initialize .coord/debate_.md

# Debate — 

**Decision:** 
**Rounds:** 2
**Side A** (argued by Codex): 
**Side B** (argued by Gemini): 
**Started:** 2026-04-28T...

---

## Round 1

### Side A — Codex
.md, argue Side A from scratch>

### Side B — Gemini
.md (which now contains Codex's
arg), argue Side B as a rebuttal>

---

## Round 2

### Side A — Codex

...

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__round1.md:

# Task: Argue Side A in debate on 

## Context
- Repo: 
- Read: .coord/debate_.md (the debate transcript so far)
- Side 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_.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:

---

## Synthesis (Claude as judge)

### Agreed facts (both sides accept)
- 

### Contested points (genuine disagreement)
- 

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

Keep the synthesis under 250 words unless the user explicitly asks for a longer decision record. If the recommendation is accepted, promote only the final decision and rationale to .coord/memory.yml; do not promote the full debate transcript.

7. Hand off

[agent-debate]
  Topic: 
  Rounds: 2
  Transcript: .coord/debate_.md
  Synthesis: bottom of same file
  Recommendation: , confidence 

  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.

• Don't let debate transcripts become memory. Store the transcript

as .coord/debate_.md; memory gets only the accepted decision, if any.

Hard caps (enforced by agent-acceptance-gate when debate is wired into a plan round)

If the debate is referenced from .coord/plan.yml (i.e., recorded as a formal task with agent: claude or similar), the acceptance gate checks these caps against .coord/debate_.md:

| Field | Cap | |---|---| | Per-turn argument (Pro / Con) | 400 words | | Total rounds | 3 (override requires explicit user opt-in in plan.yml debate_rounds) | | Final synthesis section | 250 words | | Total debate file size | 8 KB (~ 1200 words across all rounds + synthesis) |

If the debate is invoked ad-hoc (no plan.yml round), these caps are soft guidance — Claude should still respect them but no automated gate runs. For consequential decisions, always wire the debate into a formal round so the gate enforces the cap.

When caps are exceeded:

• Pro/Con turn over 400 words → reject the turn, ask the agent to

compress to ≤400 before continuing.

• Synthesis over 250 words → rewrite to ≤250 before promoting any

decision to memory.

• Total file over 8 KB → debate is no longer auditable in a glance;

recommend splitting into sub-debates per sub-decision.

Subagent review (keep main session lean)

When: Debate enters round 3+, OR .coord/debate_.md exceeds 4 KB.

Why: After 2-3 rounds, the full transcript is heavy. The judge synthesis is where the user actually consumes value. A subagent can read the entire transcript and return only the synthesis + verdict, so the main session never holds the full Pro/Con turns.

Pattern:

Spawn `general-purpose` subagent (read-only) with:
  - Read .coord/debate_.md (entire transcript)
  - Verify cap compliance: each turn ≤ 400 words, total ≤ 8 KB,
    rounds ≤ 3 (or plan-declared override)
  - Compose synthesis (≤ 250 words) covering: framing, strongest
    Pro argument, strongest Con argument, recommended decision,
    confidence level, conditions to revisit
  - Return: synthesis text + cap-violation flags

Main session reads only the synthesis; if user accepts, `agent-shared-memory`
promotes the decision (NOT the transcript) to `.coord/memory.yml`.

Commit Boundary

Every agent boundary is a commit boundary (see global rule: ~/.claude/CLAUDE.md → "Commit Discipline for Multi-Agent Work"). This makes multi-agent work auditable (commit log = agent log) and enables surgical rollback via git revert of just one agent's commit.

Specific to this skill: each round (Pro turn, Con turn, judge verdict) is a commit. The full debate is then a commit-by-commit replay. If Pro and Con both edit the same file in a round, the second commit appears as the contested diff that the judge resolves in the third commit.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: WenyuChiou
• Source: WenyuChiou/agent-collab-skills
• License: MIT
• Homepage: https://github.com/WenyuChiou/agent-collab-skills

Install and usage instructions live in the source repository linked above.