/by-hypothesis-debate

id: "skill_7aefc997cd234d20aa9d4045314703c9"
name: "by-hypothesis-debate"
display-name: "BY Hypothesis-Debate"
short-description: "Adversarial multi-agent strategy selection for protein/antibody design campaigns. Spawns competing hypothesis agents (conservative / aggressive / diverse), then ranks proposals with a reflection agent before committing GPU compute. Use when starting a novel-target campaign, when research findings are contradictory, or when multiple design modalities are viable."
category: "strategy"
keywords: "hypothesis debate, strategy selection, multi-agent, adversarial ranking, design strategy, novel target, BoltzGen, PXDesign, campaign planning"
version: "1.0"
last-updated: "2026-05-20"

BY Hypothesis-Debate Skill

Picking the wrong design strategy on a novel target wastes a GPU day. This skill forces an explicit, structured debate **before** any compute is spent: three hypothesis agents propose competing strategies in parallel, then a reflection agent ranks them against a fixed rubric. The winner becomes the campaign config.

The pattern is borrowed from adversarial ML and red-team review — it works because three independently-constrained agents will surface failure modes that a single planner misses, and the reflection step exposes hidden assumptions that would otherwise propagate into the campaign plan.

---

When to Use This Skill

✅ **Use this skill when:**

• Starting a campaign against a **novel target** (0–1 PDB structures, no SAbDab antibodies, <10 papers)
• Research findings have `CONTRADICTED` confidence (sources disagree on epitope, modality, or scaffold)
• Multiple **viable modalities** are on the table (VHH vs scFv vs de novo binder) and the user has not pinned one
• The user explicitly says *"compare approaches"*, *"explore options"*, *"which strategy would you pick"*
• Target difficulty is rated `novel` or `exploratory` by `by-research`
• A previous campaign against the same target failed with hit rate < 5% (this skill helps replan, not retry)

❌ **Do NOT use this skill when:**

• Target is well-studied with a clear precedent (e.g., TNF-alpha, PD-L1, HER2) → use `by-campaign-manager` directly
• The user has **already specified** modality, scaffolds, and tier — debating wastes turns
• Running a **preview / feasibility** campaign — overhead of 3-agent debate is not worth it for 5–10 designs
• Iterating on a previously-approved campaign (round 2, 3, … reuse the prior strategy)
• The campaign is gated on lab submission — debate occurs upstream of `/by:approve-lab`, not after

---

Quick Start

Invoke from the orchestrator (main session) **after** `by-research` has written `research.md` and `recommended_hotspots.json` to the campaign directory:

python3 scripts/orchestrate_debate.py \
  --research-dir campaigns/IL23R/campaign_20260520_001/research \
  --campaign-config campaigns/IL23R/campaign_20260520_001/campaign_config.yaml \
  --output-dir campaigns/IL23R/campaign_20260520_001/debate

Expected runtime: 4–8 minutes (3 hypothesis agents run in parallel ~3 min each, reflection agent runs sequentially ~2 min). Expected output: `debate/proposals/` with three `strategy_proposal.json` files, `debate/ranking.json`, and an updated `campaign_config.yaml` reflecting the winning strategy.

---

Inputs

**Required:**

• **Research report directory** — must contain `research.md`, `recommended_hotspots.json`, `design_recommendation.json`, and `validated_findings.json` from `by-research` (8-phase pipeline)
• **Campaign config skeleton** — a YAML file with `target`, `pdb_id`, `compute` block, but `modality`, `scaffolds`, `tier` are TBD

**Alternative inputs:**

• **`campaign_context.json`** — if present (from `/by:plan-campaign`), the user's preferences seed the agents but do NOT override the debate. Agents see the preference as a **prior**, not a constraint
• **`previous_debate.json`** — if rerunning after a failed campaign, prior debate gives historical signal to the reflection agent

**Optional:**

• **Debate budget** — number of hypothesis agents (default 3; 2 acceptable for tight token budgets, 4–5 for high-stakes campaigns)
• **Reflection temperature** — default 0.2 for ranking stability; raise to 0.5 for genuinely novel targets to encourage challenging the rubric
• **Tie-break mode** — `merge` (default), `aggressive_wins`, `user_decides`

See [references/agent-profiles.md](references/agent-profiles.md) for full input specifications including agent-specific directive templates.

---

Outputs

All outputs land under `<campaign_dir>/debate/`:

| File | Description | Written By | |------|-------------|-----------| | `proposals/conservative.json` | Strategy proposal from Conservative agent | hypothesis agent 1 | | `proposals/aggressive.json` | Strategy proposal from Aggressive agent | hypothesis agent 2 | | `proposals/diverse.json` | Strategy proposal from Diverse agent | hypothesis agent 3 | | `ranking.json` | Reflection agent's scoring, winner, and rationale | reflection agent | | `debate_log.jsonl` | Append-only audit trail of every agent dispatch | orchestrator | | `campaign_config.yaml` | **Updated** config — modality, scaffolds, tier filled in from winner | orchestrator | | `decision_summary.md` | Human-readable recap (target, candidates, choice, why) | reflection agent |

`strategy_proposal.json` Schema

Every hypothesis agent writes one of these. Validation: `scripts/validate_proposal.py`.

{
  "agent": "conservative",
  "version": "1.0",
  "target": "IL23R",
  "modality": "VHH",
  "protocol": "nanobody-anything",
  "scaffolds": ["caplacizumab", "ozoralizumab"],
  "tier": "standard",
  "num_designs_per_scaffold": 5000,
  "compute_provider": "local",
  "epitope": {
    "pdb_id": "6WDQ",
    "target_chain": "A",
    "residues": [78, 79, 80, 112, 113, 114, 115],
    "range_notation": "A78-A80,A112-A115"
  },
  "rationale": "Well-validated VHH scaffolds + low-novelty epitope reduces risk. Expected hit rate 20-40% based on prio