---
name: grok-debate
description: Host a multi-round structured debate between Claude (this assistant) and Grok via a shared filesystem folder, with auto-detection of Grok's responses and unified two-color display of both sides in the user's terminal. Use when the user wants to set up a Claude-vs-Grok debate, watch two AI models argue a topic across multiple rounds, archive a deep discussion with a written record, run a "duet" or "辩论" or "双模型对话" between Claude and Grok, hold a discussion across two AI CLIs, or invokes /debate / /grok-debate / /duet.
---

# grok-debate

Orchestrate a multi-round debate between Claude and Grok via a shared folder. Claude writes its rounds, **auto-detects** when Grok writes its rounds (via Bash polling), and displays both sides in one unified message in the user's terminal — so the user sees a single dialogue instead of toggling between two CLI windows.

## Related skill: when to use this vs `ask-grok`

| Need | Skill |
|---|---|
| One quick second opinion, synthesize and move on | **`ask-grok`** (shell-out, no folder, ~5s) |
| Multi-round contention with an archived trace | **`grok-debate`** (this skill) |
| Cross-check a fact, hedging escape, simple consult | **`ask-grok`** |
| Watch two AIs argue with rounds visible, get a written verdict | **`grok-debate`** |

If the user just wants Grok's view on something, `ask-grok` is almost always the right call. Reach for `grok-debate` only when the topic is contentious enough to warrant 3 rounds of forced rebuttals + a written verdict.

## Mental model

The user runs two terminals:
- **This one**: Claude Code (you).
- **Another**: a Grok CLI agent (running with the watcher prompt from `templates/grok-watcher-prompt.md`).

Both have read/write access to a shared folder. You are the "host". You write your rounds as files, wait for Grok's files to appear, then render both into one chat message. The user only interacts with this terminal; they don't need to ferry messages.

## Trigger

User says any of: `/debate <topic>`, `/grok-debate <topic>`, `/duet <topic>`, "和 grok 辩论 X", "让 grok 加入聊 X", "辩论 X", "duet on X".

If no shared folder is in context, ask the user which folder to use. If the current working directory contains "讨论", "debate", "duet", or "grok", default to it without asking.

## Phase 0 — Bootstrap

1. Resolve `<shared>` = the shared folder path.
2. Create `<shared>/debates/<topic-slug>/` (slug = topic lowercased, spaces→`-`, non-ASCII preserved, max 40 chars).
3. Write `<shared>/debates/<topic-slug>/PROTOCOL.md` from the template at the bottom of this skill — this is what Grok reads to learn the format.
4. If `<shared>` doesn't yet have a copy of `templates/grok-watcher-prompt.md` and `templates/grok-readme.md`, copy them in (so Grok side can find them).
5. Tell the user: "辩论文件夹建好了：`<path>`。确认 Grok 端在监听这个文件夹（贴过 watcher prompt），我开始 round 1。"

## Phase 1 — Claude opens (Round 1)

Write `round-1-claude.md` using the round format. Round 1 has no `## 我不同意的地方` (nothing to disagree with yet); instead use `## 留给 Grok 的钩子` listing 2–3 points you expect Grok to push back on. This invites disagreement and pre-tests the anti-sycophancy contract.

Display Claude's round 1 to the user, rendered in the unified format (just Claude's side for now).

## Phase 2 — Wait for Grok

Auto-poll for Grok's file. Use Bash `run_in_background` with an `until` loop (one notification when the file appears):

```bash
until [ -f "<shared>/debates/<slug>/round-N-grok.md" ]; do sleep 2; done
echo "grok wrote round N"
```

Timeout: 600s. If timeout fires, ask the user: "Grok 那边好像还没写出来，需要我催他吗，还是有别的情况？"

While waiting, do not poll or output messages — the background command will notify you.

## Phase 3 — Read, display, respond

When Grok's file lands:

1. **Read** `round-N-grok.md`.
2. **Display unified view** in the chat:

```
━━━━━━━━━━━━━━━━━━━━━━━ ROUND N ━━━━━━━━━━━━━━━━━━━━━━━

🟦 Claude
<Claude's round N — full text if under ~500 chars; otherwise show stance + 论据 headers + key claims, with note "[full at round-N-claude.md]">

🟧 Grok
<Grok's round N — same compression rule>

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

3. **Write `round-(N+1)-claude.md`**. This MUST:
   - Open with `## 直接回应 Grok 第 N 轮` — quote 1–2 specific points from Grok and respond.
   - Include `## 我不同意的地方` with at least one concrete disagreement (quote Grok exactly, then refute).
   - If you genuinely agree with everything (rare; if it happens often, you're being lazy), write `## 我同意，但补充：` and add an angle Grok missed.
   - Use confidence markers `[高]/[中]/[低]` on any factual claim.
   - Keep it under ~600 words. Long rounds repeat themselves.

4. Display Claude's new round (in the same unified format, just Claude's side this round).
5. Loop back to Phase 2 with N+1.

## Phase 4 — Termination

Stop after 3 rounds (default) OR when the user says "stop / summarize / 收 / 总结".

Write `verdict.md`:

```markdown
# Verdict — <topic>

## 收敛点
<where Claude and Grok converged, with the round where it happened>

## 仍未解决的分歧
<list each, with the strongest version of each side's argument — steelman both>

## 新出现的信息
<facts/angles that surfaced only because both AIs were forced to engage, not present in any single model's first response>

## 元观察
<short note on whether the anti-bias contract held: did Claude commit, did Grok disagree?>
```

Display the verdict to the user.

## Round file format (writing `round-N-claude.md`)

```markdown
# Round N — Claude

## 立场
<one sentence, no hedge words. "A 优于 B because X" not "A 可能优于 B"。>

## 论据
1. **<claim>** [置信度] — <evidence/reasoning>
2. **<claim>** [置信度] — <reasoning>
3. **<claim>** [置信度] — <reasoning>

## 我不同意的地方  (round 2+ only)
- Grok 第 N-1 轮说："<exact quote>"。我不同意，因为 <reasoning>。

## 留给 Grok 的钩子  (round 1 only, optional later)
- <point you expect Grok to push back on>
- <point where you're least confident>
```

## PROTOCOL.md template (write to debate folder for Grok to read)

```markdown
# 协议：Claude × Grok 辩论 — <topic>

## 文件命名
- Claude 写：`round-N-claude.md`
- Grok 写：`round-N-grok.md`
- N 从 1 开始；每完成一轮（Claude + Grok 各一次）N+1
- 最终：Claude 写 `verdict.md` 综合双方

## 双方承诺

**Claude（反回避）**：有判断就直接讲，不挂"可能/或许"做盾牌；要拒绝某话题须说明拒绝理由经不经得起反驳。

**Grok（反谄媚）**：不同意就明说，不要先夸再绕；每个事实点后打置信度标记 `[高]`（多源印证）/ `[中]`（记忆有未核实）/ `[低]`（推测）。

## 强制对抗机制
每轮回信结尾必须有 `## 我不同意的地方`，明确指出对方上一轮里至少一个不同意的点（带原文引用 + 反驳理由）。
若真无异议，写 `## 我想补的角度` 提一个对方未考虑的视角。
**禁止只说"完全同意"或"说得好"** —— 违反则下一轮被对方点名。

## 长度
每轮 ≤ 600 字（中文）。长论必啰嗦。

## 终止
- 默认 3 轮
- 用户可随时说"停"/"总结"提前结束
- Claude 在终局写 verdict.md，综合：收敛点、未解决分歧（steelman 双方）、新出现的信息、元观察（协议是否生效）

## 显示
Claude 端会自动读取双方文件，统一渲染到用户终端。Grok 只需按格式写文件即可，不必担心显示。
```

## When NOT to use this skill

- Single-question Q&A where one model suffices — use `ask-grok` instead.
- User wants a one-off "ask Grok this" — use `ask-grok`.
- No Grok terminal is running with the watcher — ask user to start one first (paste `templates/grok-watcher-prompt.md`), don't write rounds into the void.

## Edge cases

- **Grok writes before Claude finishes round 1**: ignore the file, ask user to have Grok wait for `round-N-claude.md` to land first.
- **Grok returns malformed file** (no `## 我不同意的地方`, or just praise): display what you got, then in your next round, explicitly call it out — "你 round N 没有反对意见，这违反协议。我先假设你同意 X、Y、Z，下面我推到边界看看你还跟不跟。"
- **User wants to inject mid-debate**: they write `interjection-N.md` (or just paste in chat); you incorporate it into the next round's opening.
- **Beyond 3 rounds**: ask user to confirm extending. Debates past round 3 usually repeat.
- **No `<shared>` folder exists yet**: create it. Do NOT silently fall back to `/tmp` — the folder location matters for Grok's access.

## Anti-patterns to avoid

- Polling Grok's file with foreground `sleep` loops — use background Bash with `until` for one notification.
- Rendering raw files without compression — long files clutter chat; show structured summary + pointer to file.
- Letting "we both agreed" rounds pass without flagging — if both sides keep agreeing, the contract has failed.
- Switching to Chinese/English mid-format inconsistently — match the topic's language; user's framing wins.
- Reaching for `grok-debate` when `ask-grok` would do — debate infrastructure is overhead; don't pay it for small questions.