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

.. code-block:: text

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

.. code-block:: bash

   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.

.. list-table::
   :header-rows: 1
   :widths: 20 10 15 55

   * - 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):**

.. code-block:: yaml

   ---
   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):**

.. code-block:: yaml

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

.. code-block:: yaml

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

.. code-block:: yaml

   ---
   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``):

   a. Build prompt for Persona A with plan, context, issues, and transcript
   b. Call ``ask_model`` with Persona A's model ID, capture response
   c. Build prompt for Persona B with updated transcript
   d. 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:

.. code-block:: markdown

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

.. code-block:: text

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

.. code-block:: text

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

**Simple debate (short topic):**

.. code-block:: text

   > /wf:debate using my-topic.md

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

**Minimal plan (auto-generated personas):**

.. code-block:: text

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