agent-debate · diff
git:20260514.64910a0 to git:20260831.ca20117
55 added, 263 removed. Audit A to A.
---
name: agent-debate
- description: Use when a consequential decision needs adversarial review, opposing agent arguments, a second opinion via debate, or explicit trade-off analysis before implementation.
+ description: Use when a consequential decision has genuinely competing positions that need bounded adversarial review before a human decision.
---
# 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
+ Run a bounded adversarial review of a consequential trade-off. Debate improves
+ the evidence visible to a decision maker; it does not establish truth by vote
+ and does not authorize implementation.
- Trigger phrases:
+ ## Preconditions
- - "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>`."
+ Use debate only when:
- Not for:
+ - the positions are both plausible and materially different;
+ - the decision is consequential enough to justify independent review;
+ - the question can be falsified or informed by identifiable evidence; and
+ - the current policy allows the required work.
- - 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).
+ Do not debate a factual question that can be settled by direct verification, a
+ minor naming preference, or a decision already made by an authorized human.
- ## Inputs
+ ## Roles
- User must provide:
+ - Independent `reviewer` task packets argue named positions.
+ - A `synthesizer` compares their evidence without external tool access unless
+ the plan explicitly grants it.
+ - The `primary-agent` records the recommendation and presents it to the human.
+ - The human approves, declines, or requests revision.
- 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.
+ Provider and model names belong to host-adapter metadata, not the public debate
+ contract.
## 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>.
- ```
-
- 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)
+ 1. Define the decision, alternatives, known facts, disputed assumptions,
+ evidence standard, and human decision owner.
+ 2. Evaluate policy before every reviewer spawn. Persist a required checkpoint
+ before continuing.
+ 3. Give each reviewer the same evidence packet plus one position to steel-man.
+ Reviewers are argument-only and must not modify source files.
+ 4. After each plan-act-reflect cycle, update the `TaskCheckpoint` and evaluate
+ policy. Stop immediately when policy says `stop`.
+ 5. Filter missing or failed reviewer outputs, but record their status. Never
+ invent the absent side.
+ 6. Have the synthesizer separate agreed facts, contested claims, evidence
+ quality, uncertainties, and falsifiable conditions that would change the
+ recommendation.
+ 7. Present the synthesis to the human decision owner. No implementation or
+ canonical-memory update occurs without an explicit recorded decision.
- **When**: Debate enters round 3+, OR `.coord/debate_<topic>.md`
- exceeds 4 KB.
+ All cycle, context, concurrency, and transcript limits come from the canonical
+ machine-readable policy. Do not hardcode them in task packets or prose.
- **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.
+ ## Output
- **Pattern**:
+ Produce a scratch debate record containing:
- ```
- 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
+ - decision and alternatives;
+ - policy and checkpoint references;
+ - each position's claims and evidence references;
+ - missing or failed reviewer records;
+ - agreed facts and contested points;
+ - synthesizer recommendation, uncertainty, and what would change it;
+ - pending human decision.
- Main session reads only the synthesis; if user accepts, `agent-shared-memory`
- promotes the decision (NOT the transcript) to `.coord/memory.yml`.
- ```
+ If the outcome may be useful later, emit a memory proposal. The proposal may
+ become canonical only after an explicit human decision; resolution appends a
+ new event and never rewrites an earlier memory record.
- ## Commit Boundary
+ See `references/debate_protocol.md` for task framing.
- 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.
+ ## Prohibitions
- **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.
+ - No majority vote as an evidence or acceptance mechanism.
+ - No silent retry, model switch, context discard, or missing-result coercion.
+ - No implementation, source mutation, commit, merge, or push during debate.
+ - No direct write, overwrite, archive, or deletion of canonical memory.