ratchet-debate

name	ratchet:debate
description	View or continue an ongoing debate

/ratchet:debate — View or Continue a Debate

View full transcript of a debate, or continue an unresolved one.

Usage

/ratchet:debate              # List all debates with status
/ratchet:debate [id]         # View a specific debate's full transcript
/ratchet:debate [id] --continue  # Continue an escalated debate with another round

Execution Steps

No Arguments — List Debates

Read all .ratchet/debates/*/meta.json files. If none exist, inform user: "No debates found. Run /ratchet:run to start your first debate." Then AskUserQuestion with options: "Start a debate (/ratchet:run) (Recommended)", "Done for now".

If debates exist, AskUserQuestion to pick one:

• Question: "Which debate to view?"
• Options: one per debate as "[debate-id] — [pair-name] | [status] | [N] rounds | [verdict or 'pending']", plus "Cancel"

With ID — View Transcript

Error handling: If meta.json missing or malformed:

if [ ! -f ".ratchet/debates/<id>/meta.json" ]; then
  echo "Error: Debate '<id>' not found — no meta.json in .ratchet/debates/<id>/" >&2
  # Suggest listing available debates
fi
# Validate JSON is parseable
jq empty .ratchet/debates/<id>/meta.json 2>/dev/null \
  || { echo "Error: meta.json for debate '<id>' is malformed JSON. It may have been corrupted by an interrupted write." >&2; exit 1; }

Recovery for corrupted meta.json: attempt recovery before giving up.

1. Regenerate from round files — reconstruct meta.json from disk:

   debate_dir=".ratchet/debates/<id>"
   pair_name=$(echo "<id>" | sed 's/-[0-9T]*$//')
   round_count=$(ls "$debate_dir/rounds"/round-*-adversarial.md 2>/dev/null | wc -l)
   last_round="$debate_dir/rounds/round-${round_count}-adversarial.md"
   
   # Extract verdict from the last adversarial round (look for verdict keywords)
   verdict=""
   if [ -f "$last_round" ]; then
     verdict=$(grep -oE '(ACCEPT|CONDITIONAL_ACCEPT|TRIVIAL_ACCEPT|REJECT|REGRESS)' \
       "$last_round" | head -1)
   fi
   
   # Reconstruct minimal meta.json
   cat > "$debate_dir/meta.json" << EOF
   {
     "id": "<id>",
     "pair": "$pair_name",
     "phase": "unknown",
     "status": "$([ -n "$verdict" ] && echo 'consensus' || echo 'initiated')",
     "rounds": $round_count,
     "max_rounds": 3,
     "started": "unknown",
     "resolved": null,
     "verdict": $([ -n "$verdict" ] && echo "\"$verdict\"" || echo 'null'),
     "fast_path": false,
     "recovered": true,
     "recovery_note": "Regenerated from round files after corruption"
   }
   EOF
   echo "meta.json regenerated from $round_count round files. Review and correct any 'unknown' fields." >&2
   

2. If no round files exist — no recoverable state:

   if [ "$round_count" -eq 0 ]; then
     echo "Error: No round files found for debate '<id>'. Cannot recover. Delete the debate directory and re-run." >&2
     # Suggest: rm -rf .ratchet/debates/<id> && /ratchet:run
   fi
   

After recovery, inform user via AskUserQuestion:

• Question: "Debate '' meta.json was corrupted and recovered from round files. Some fields may need manual correction. How to proceed?"
• Options: "View recovered debate (Recommended)", "Re-run debate from scratch", "Delete and skip"

Verdict storage note: Verdicts may exist in two locations:

• meta.json → verdict field: populated by debate-runner for consensus (ACCEPT, CONDITIONAL_ACCEPT) or tiebreaker verdicts. Embedded object.
• verdict.json (separate file): populated by /ratchet:verdict for human-cast verdicts. Read both; prefer verdict.json if exists (human decision overrides).

Read meta.json and all round files. Present full transcript:

Debate: [id]
Pair: [pair-name]
Files: [file list]
Status: [status]
Started: [timestamp]

--- Round 1 ---

[Generative]:
[contents of round-1-generative.md]

[Adversarial]:
[contents of round-1-adversarial.md]

--- Round 2 ---
...

[If verdict exists:]
--- Verdict ---
Decision: [ACCEPT/CONDITIONAL_ACCEPT/REJECT] (or [accept/modify/reject] for human/tiebreaker verdicts)
Decided by: [consensus/tiebreaker/human]
Reasoning: [...]

With --continue

Only valid for debates with status escalated or initiated. Resume protocol from where it left off via AskUserQuestion:

• If escalated:
  • Question: "Debate [id] escalated after [N] rounds (max was [max_rounds]). How to proceed?"
  • Options: "Run another round (extend max by 1)", "Proceed to verdict", "View full transcript first"
  • If "Run another round": increment max_rounds by 1 in meta.json:

    jq '.max_rounds += 1' .ratchet/debates/<id>/meta.json > /tmp/meta-tmp.json \
      && mv /tmp/meta-tmp.json .ratchet/debates/<id>/meta.json
    

    Then execute one debate round per /ratchet:run Step 5e protocol.
• If initiated:
  • Question: "Debate [id] interrupted at round [N]. Resume from where it left off?"
  • Options: "Resume debate (Recommended)", "Restart debate", "Abandon debate"
  • If "Restart debate": delete all files in rounds/, reset rounds to 0 in meta.json, start fresh from round 1 per /ratchet:run Step 5e protocol.

When resuming or running another round, execute same debate protocol as /ratchet:run Step 5e (generative round, adversarial round, check verdict). Read pair's agent definitions from .ratchet/pairs/<pair-name>/ and debate context from meta.json and existing round files. If rounds/ empty, start from round 1.

Tool boundaries for resumed debates — enforce same role boundaries as /ratchet:run Step 5e:

• Generative agent: tools = Read, Grep, Glob, Bash, Write, Edit
• Adversarial agent: tools = Read, Grep, Glob, Bash — disallowedTools = Write, Edit
• Tiebreaker agent: tools = Read, Grep, Glob, Bash — disallowedTools = Write, Edit

Pass guilty-until-proven-innocent principle to resumed debate agents: new changes are GUILTY until proven innocent — test failures on a PR branch are caused by the PR unless definitively proven otherwise. Burden of proof is on demonstrating failure exists on master.

If user picks "Abandon debate", set status to "resolved" with verdict {"decision": "reject", "decided_by": "human", "reasoning": "Debate abandoned by user"}. Update meta.json accordingly.

After Viewing — Next Steps

After showing transcript (or completing --continue action), AskUserQuestion to guide user:

• Options (adapt based on debate status):
  • "Continue this debate" — only if status is escalated or initiated
  • "Render verdict (/ratchet:verdict)" — only if status is escalated
  • "View another debate" — if more debates exist
  • "Back to main flow (/ratchet:run) (Recommended)"
  • "Done for now"