Debate

Debate#

Orchestrate a plan critique or structured debate between two LLM personas, producing a transcript with synthesis.

Description#

This skill has two modes:

  • Plan critique mode (default): Parse a markdown plan, auto-embed referenced source files, extract issues, debate them across rounds, and produce a critique report with a revised plan.

  • Simple debate mode: For short topics (body < 50 words), run a classic for/against debate with balanced synthesis.

The current session acts as moderator: parsing input, embedding context files, routing persona turns when an external model router is available, capturing responses round by round, and writing the final output.

External model routing: HydraMCP or another model router enables external-model personas. If unavailable, the skill asks whether to continue as a within-model debate before writing a transcript.

Routing Fallback#

When personas specify external model IDs and HydraMCP or the requested router is unavailable, the generated skill must stop and ask whether to continue as a within-model debate using the current model. If the user agrees, the transcript records the downgrade and ignores external model IDs for execution. If the user declines, no debate transcript is written.

Triggers#

The skill activates when you mention:

  • Debating a topic or decision

  • Critiquing or reviewing a plan

  • Arguing both sides of a question

  • Devil’s advocate analysis

  • Pros and cons debate

  • Stress testing a decision

Explicit invocation:

/wf:debate

Input Format#

The debate takes a markdown file with optional YAML frontmatter. The JSON config format is no longer used.

Create a plan file by copying the template:

cp templates/active/debates/plan-template.md .claude/debate.md

Edit the platform default input file to describe your plan and set reviewer preferences.

Search order:

  1. Explicit path provided by the user

  2. the platform default input file in the current repository root

  3. If not found, shows a minimal example for the user to create

Frontmatter Fields#

All fields are optional. If frontmatter is omitted entirely, all defaults apply.

Field

Type

Default

Description

rounds

int

3

Number of back-and-forth exchanges

response_scale

float

1.5

Max response words = scale × plan word count (floor: 200)

context_budget_kb

int

100

Max total KB for embedded context files

synthesizer

string

"host"

Who writes synthesis: "host" or a persona name

output_dir

string

"resources/agent-docs/reviews/debates"

Where transcripts are written

personas

list

auto-generated

Optional. Exactly 2 if provided

Persona fields (when provided):

  • name: Display name for the reviewer

  • perspective: System instructions defining review angle

  • model: HydraMCP model ID (e.g. sub/claude-sonnet-4-5-20250929)

Use the list_models tool to see available model IDs.

Example Frontmatter#

Full example (plan critique with custom personas):

---
rounds: 3
response_scale: 1.5
context_budget_kb: 100
synthesizer: host
output_dir: resources/agent-docs/reviews/debates
personas:
  - name: Feasibility Reviewer
    perspective: >
      You review for technical feasibility and implementation risk.
      Focus on whether the approach is realistic, identify missing
      steps, and flag complexity that may be underestimated.
    model: sub/claude-sonnet-4-5-20250929
  - name: Security Reviewer
    perspective: >
      You review for security, scalability, and operational concerns.
      Focus on attack surfaces, data integrity, failure modes, and
      whether the design scales to production load.
    model: sub/claude-sonnet-4-5-20250929
---

Minimal example (auto-generated personas, all defaults):

---
# No frontmatter needed — or use an empty block:
---

The plan body alone is enough. Personas are auto-generated from the plan content, and all settings use their defaults.

Simple debate example (short topic, < 50 words in the body):

---
rounds: 2
personas:
  - name: Advocate
    perspective: Argue in favour of the proposition.
    model: sub/claude-sonnet-4-5-20250929
  - name: Critic
    perspective: Argue against the proposition.
    model: sub/claude-sonnet-4-5-20250929
---

When the body is under 50 words, the skill skips issue extraction and produces a standard for/against debate with synthesis.

Overriding just one default:

---
rounds: 5
---

All other fields keep their defaults. Personas are auto-generated.

@file Auto-Detection#

In plan critique mode, the skill scans the markdown body for @path/to/file references and embeds their contents into prompts.

Detection rules:

  • Pattern: @ followed by a path containing / or .

  • Must be preceded by whitespace or start-of-line

  • References inside fenced code blocks are skipped

  • Files are resolved relative to the repo root

  • Missing files produce a warning (not an error)

Embedding with budget:

Each file is read and checked against the context_budget_kb budget:

  • If it fits: embed the full file content in a fenced code block

  • If it exceeds the remaining budget: call smart_read with the plan topic as query, embed the condensed result marked [CONDENSED via smart_read]

Set context_budget_kb: 0 to disable file embedding entirely.

Workflow#

  1. Find and parse input file

    • Locate the markdown file using the search order

    • Split YAML frontmatter from markdown body

    • Apply defaults for missing fields

    • Count words → determine mode (< 50 words = simple debate)

    • Calculate max_response_words = max(200, int(response_scale * plan_words))

  2. Detect and embed context files (plan critique mode only)

    • Scan body for @file references outside code fences

    • Read and embed files within budget, use smart_read for oversized files

  3. Verify models are available

    • Call list_models to check each persona’s model exists

    • Stop with available model list if a model is not found

  4. Auto-generate personas (only if personas omitted)

    • Call ask_model to suggest 2 complementary reviewer roles

    • Parse YAML response, assign default model

  5. Issue extraction (plan critique mode only)

    • Call ask_model to extract a numbered list of issues from the plan

  6. Execute debate rounds

    For each round (1 to rounds):

    1. Build prompt for Persona A with plan, context, issues, and transcript

    2. Call ask_model with Persona A’s model ID, capture response

    3. Build prompt for Persona B with updated transcript

    4. Call ask_model with Persona B’s model ID, capture response

  7. Synthesise

    • Plan critique + host: the current session writes critique report + revised plan

    • Plan critique + persona: ask_model call for two-part synthesis

    • Simple debate + host: the current session writes balanced synthesis

    • Simple debate + persona: ask_model call for synthesis

  8. Write transcript

    • Write complete transcript to output_dir/debate-YYYY-MM-DD-HHMMSS.md

Transcript Format#

Plan critique mode includes additional sections:

# Debate Transcript

**Topic:** Migrate Auth to JWT
**Plan:** platform default input file
**Date:** 2026-02-10 14:30:00
**Rounds:** 3
**Mode:** plan-critique
**Response scale:** 1.5 (300 words max)

## Personas

| Role | Name | Model |
|------|------|-------|
| Persona A | Feasibility Reviewer | sub/claude-sonnet-4-5-20250929 |
| Persona B | Security Reviewer | sub/claude-sonnet-4-5-20250929 |

## Context Files

- src/auth/session.py (2,340 bytes)
- src/middleware/auth.py (1,102 bytes) [CONDENSED via smart_read]

---

## Issue Extraction

[numbered list of issues]

---

## Round 1

### Feasibility Reviewer

[response]

### Security Reviewer

[response]

---

## Synthesis

### Critique Report

[per-issue recommendations]

### Revised Plan

[rewritten plan with [CHANGED] annotations]

Simple debate mode uses the standard format (no issue extraction or revised plan sections).

Example Usage#

Plan critique (full flow):

> cp templates/active/debates/plan-template.md .claude/debate.md
> # Edit the platform default input file with your plan and @file references
> /wf:debate

Plan critique with explicit path:

> /wf:debate using docs/plans/migration-plan.md

Simple debate (short topic):

> /wf:debate using my-topic.md

Where my-topic.md contains a short question (< 50 words).

Minimal plan (auto-generated personas):

> # Create the platform default input file with just a plan, no frontmatter
> /wf:debate

Personas will be auto-generated based on the plan content.

Error Handling#

  • Plan file not found: Shows minimal example for the user to create

  • Model not available: Shows the available models from list_models

  • ``ask_model`` call fails: Includes error in transcript, asks whether to continue or abort

  • ``@file`` not found: Warning in transcript, file skipped

  • Persona auto-generation fails: Falls back to generic reviewers

  • ``smart_read`` fails: File skipped, warning logged

  • Frontmatter parse error: Reports the YAML error and line number

Limits#

  • Rounds: 2-4 recommended. Above 5 rounds the transcript may exceed context limits for smaller models.

  • Response length: Controlled by response_scale * plan_words (floor 200). Longer plans get proportionally longer responses.

  • Personas: Exactly 2. The schema supports arrays for future N-way debates.

  • Context budget: Default 100 KB. Set to 0 to disable file embedding.

  • Models: Any model available via HydraMCP (Claude, GPT, ollama, etc.)

Integration with the slice loop#

Debate transcripts can feed into the slice-loop workflow:

  1. Run a plan critique on an architecture decision

  2. Capture the revised plan as a spec with the to-spec skill

  3. Break the spec into slices with to-slices

  4. Implement the chosen approach slice by slice with implement

Contents