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.
4. Optional: context policy. Default debate turns are 200-400
   words, final synthesis is <= 250 words, and only the accepted
   decision is eligible for shared memory.

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 "	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

# 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:

# 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:

---

## 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>.

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: <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.
• Don't let debate transcripts become memory. Store the transcript
  as .coord/debate_<topic>.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_<topic>.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_<topic>.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_<topic>.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 <hash> 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.