phone-a-friend

What this skill does

# Phone a Friend

## Overview

A consultation workflow where the primary Claude Code agent pauses its work, assembles a synopsis of the current situation, and engages an Opus sub-agent ("the friend") in a back-and-forth debate. The two agents argue, critique, research, and refine until they reach one of two valid terminal states: **genuine consensus** or **a clean agree-to-disagree**. At that point the primary reports back to the user.

There is **no hard iteration cap**. The goal is a real outcome, not a turn counter. If the user is not satisfied with the report, they can send the debate back for another round — the jury-room rule (Phase 7).

This is NOT a one-shot review. It is a multi-turn dialogue where both sides push back, ask questions, update their views, and — when they need information only the user has — pause to ask the user directly (Phase 4b).

## When the user invokes this skill

The user will typically say something like "phone a friend", "get a second opinion on this", "sanity check this", or "debate this with another model". Do not invoke this skill proactively — wait for the explicit ask.

## Workflow

Follow these phases in order.

### Phase 1: Confirm scope with the user (brief)

Before spinning up the friend, confirm in one sentence what the friend should debate. Offer a default based on current session context, e.g. "Phoning a friend to pressure-test the migration plan in `db/schema.ts` — want to narrow the question, or go broad?" Wait for the user's OK or redirection. Keep this exchange to one round; do not interrogate.

### Phase 2: Build the synopsis

Assemble a structured synopsis. The synopsis is a self-contained briefing — the friend has **zero** prior context from the session. Include:

1. **The question** — a single sentence stating what is being debated. Be specific. "Is this migration safe?" not "review this."
2. **Background** — what the user is trying to accomplish, why it matters, any deadlines or constraints.
3. **Current approach / proposal** — what the primary agent is about to do or has done, with concrete details (file paths, code snippets, command sequences, architectural choices).
4. **What has been tried / ruled out** — prior attempts, dead ends, options already rejected and why.
5. **Uncertainties** — where the primary is unsure or has low confidence.
6. **Relevant artifacts** — file paths (with line numbers), error messages, test output, logs. Quote small snippets inline; reference larger ones by path so the friend can read them.
7. **The ask** — what kind of feedback is wanted: adversarial critique, alternative approaches, risk assessment, missing considerations, etc.
8. **Research hints (optional)** — specific things the friend should consider investigating: "check whether library X supports this", "look at how `src/auth/*` handles the same case", "web-search current best practices for Y as of 2026". The friend decides for itself whether to act on these.

Keep the synopsis tight but complete. Aim for enough signal that the friend can form a real opinion without needing to ask clarifying questions on turn 1.

### Phase 3: Spawn the friend (turn 1)

Use the **Agent** tool with these exact settings:

- `subagent_type`: `"general-purpose"` (gives the friend access to all tools: Read, Grep, Glob, WebSearch, WebFetch, Bash, Edit, Write, etc.)
- `model`: `"opus"`
- `description`: `"Phone a friend: <short topic>"`
- `prompt`: the synopsis, framed as below.

The prompt MUST:

- Open with the word **`ultrathink`** on its own line to trigger maximum extended thinking budget.
- State the friend's role explicitly: "You are being consulted as a second opinion. Your job is to push back, not rubber-stamp. Disagree where you see flaws. Propose alternatives."
- Include the full synopsis.
- State the terminal goal: "Our job together is to reach genuine consensus, *or* to cleanly agree to disagree with both positions clearly stated. There is no turn limit. Do not force agreement to end the debate, and do not drag the debate out past its useful life. Stop when real progress stops."
- Explain the human-escalation channel: "If at any point you have a question only the human user can answer — missing business context, ambiguous requirements, a values/preference call, information not in the codebase or on the web — say so explicitly and I will pause our debate and surface the question to the user. Do NOT escalate questions you could answer yourself by reading files, searching the web, or running commands."
- State the read-only constraint in plain terms: **"You are a thought partner, not an actor. You must NOT create, modify, or delete any files or data under any circumstances. You must NOT run commands that mutate state (no `git commit`, no `git push`, no `rm`, no `mv`, no `touch`, no package installs, no migrations, no API calls that write, no config changes). Your tool use is strictly read-only: reading files, grepping, globbing, web search, web fetch, and read-only shell commands (`ls`, `cat`, `git log`, `git diff`, `git status`, etc.) are fine. If you believe an action should be taken, describe it in your response and let the primary agent carry it out after the user approves. Your job is to think, debate, and advise — never to act."**
- Tell the friend it has read/search tools (Read, Grep, Glob, WebSearch, WebFetch, read-only Bash) and should use them when grounding its opinion would benefit from real evidence — but that Edit, Write, NotebookEdit, and mutating Bash commands are off-limits.
- End with: "Respond with (a) your independent assessment, (b) specific critiques or concerns, (c) questions for me or for the human (label which), and (d) a current position (agree / disagree / need-more-info) on the primary ask. If you need to read files, search the web, or run commands to form your view, do so before responding."

Capture the Agent tool call's returned agent ID or name — it is needed for follow-up turns via SendMessage.

### Phase 4: The dialogue loop

After turn 1, enter a dialogue loop. Each iteration:

1. **Read the friend's response carefully.** Extract: its position, its critiques, its questions, any new evidence it surfaced.
2. **Form the primary's next turn.** This is the primary agent's job — do not just pass the friend's message back. The primary should:
   - Answer any questions the friend asked (with concrete info from the session or by reading files).
   - Push back on critiques the primary genuinely disagrees with, with reasoning.
   - Concede points the friend got right.
   - Surface new considerations the friend may have missed.
   - Ask the friend for clarification where its reasoning is unclear.
   - Re-state the primary's current position (agree / disagree / evolving).
3. **Continue the dialogue** by calling **SendMessage** with `to` set to the friend's agent ID from Phase 3. Do NOT call Agent again — that would start a fresh agent with no memory of the prior turns. Always SendMessage to continue.
4. **Check for termination** after each response (see Phase 5).

**No hard iteration cap.** The task is to reach a real outcome — either a genuine consensus or a clean agree-to-disagree — not to hit a turn counter. Both agents should be explicitly told: "Your job is to reach consensus *or* to cleanly agree to disagree. Do not stop debating just because you are tired of debating. Do not force agreement to end the dialogue. When you have genuinely exhausted the productive arguments, say so explicitly."

That said, the primary agent should use judgment about when enough is enough. Use these heuristics:

- **Productive turns**: the friend is still surfacing new angles, evidence, or arguments → keep going.
- **Diminishing returns**: two consecutive turns add nothing new → check if this is consensus, agree-to-disagree, or genuine stalemate; then stop.
- **Reasonable bound**: around turn 25, reassess whether continued debate is actually productive. This is not a cap, it is a checkpoint. If real progress is sti