clink-debug git:20260731.cd944abA

Immutable. This exact content is served forever at /api/v1/blob/06139078a7188d21.

---
name: clink-debug
description: Sequence clink-subagents and clink-brainstorm into one evidence-carrying bug hunt, for a failure that has ALREADY survived a delegated pass. Enforces that no agent which produced a hypothesis may falsify or repair it, and defines the artifact that must pass between phases. Invoke deliberately when a bug is still open after one worker looked at it, when two agents disagree about a cause, or when a fix landed and the symptom came back. A bug nobody has looked at yet does NOT come here — it goes to clink-subagents with debug-mantra, which closes most of them.
---

# clink-debug

> **Requires the same PAL MCP setup as [`clink-subagents`](../clink-subagents/SKILL.md) and [`clink-brainstorm`](../clink-brainstorm/SKILL.md).** This skill adds no new call shape — it sequences those two and constrains who may sit in which phase. Read whichever of them you are about to use for its own rules; this file does not repeat them.

## Do not start here

**One worker plus `debug-mantra` closes most bugs.** That is [`clink-subagents`](../clink-subagents/SKILL.md), it costs one cheap call, and reaching past it is the most common way to waste an afternoon.

Come here only when one of these is true:

- a delegated pass returned and **the bug is still open**
- **two agents disagree about the cause**, or one produced a cause nobody reproduced
- a fix landed, and **the symptom came back**

If none of them is true, go back and run the cheap path first. What you learn there is the input this skill needs anyway.

## What this file owns, and what it deliberately does not

It owns exactly three things: **who may sit in which phase**, **what must pass between phases**, and **when to stop**.

It owns none of the debugging discipline itself. That is already written and is not restated here:

| For | Read |
|---|---|
| the reproduce → trace → falsify → fix discipline | `debug-mantra` |
| capturing a red-capable repro and a falsifiable prediction | `diagnosing-bugs` |
| root cause before fix, and the evidence registers | `t4-dev-workflow` |
| which model, which effort, which quota lane | the two clink skills — **this file contains no model or effort table, by design** |

## The phases, and who may sit in each

| Phase | Run it through | Seat rule |
|---|---|---|
| **Observe** — reproduce, minimise, trace | `clink-subagents`, workers in parallel over independent areas | any |
| **Promote** — admit a hypothesis | **you.** Never a subagent | — |
| **Falsify** — try to break the hypothesis | `clink-brainstorm` if it is contested or expensive to get wrong; one fresh worker otherwise | **fresh seats only** |
| **Decide** — did it survive | **you.** Panel agreement is not verification | — |
| **Repair** | `clink-subagents` with `tdd` | **fresh seat** |
| **Close** — re-run the repro, then the suite | **you** | — |

**Promote, Decide and Close never leave you.** They are the three points where a wrong answer becomes the premise of everything after it.

## The provenance rule

**No agent session or model lineage that produced a hypothesis may occupy the falsify seat or the repair seat.**

A producer asked to attack its own hypothesis defends it — it has the reasoning that built the hypothesis in context, and that context is exactly what an outside check is supposed to lack. A producer asked to *implement* its own hypothesis is worse: the wrong theory gets written into the code by the one agent already convinced of it, and the diff then looks like evidence.

**The failure this prevents has a name: hypothesis laundering.** A worker's plausible explanation passes through a review that was never independent and comes back as panel-backed certainty. That is *worse* than one agent debugging alone, because the ceremony manufactures confidence that nothing in the process earned. Three agents failing to refute a claim is not evidence the claim is true.

Enforce it by seat, not by intention:

- **a new `continuation_id`** for every falsify and repair call — a fresh thread, not a follow-up
- **a different client where you can afford it** — `codex` produced it, so falsify on `cursor` or `antigravity`. Different lineage beats the same model twice
- the falsifier receives **the evidence and the testable prediction, never the producer's account of why it is right.** A persuasive causal narrative is the thing you are trying to test, so do not hand it over as the frame

## The handoff artifact

The same object moves between every phase. If it degrades into prose at any boundary, the next phase diagnoses the prose.

- the **failing command**, verbatim
- its **actual output**, not a summary of it
- the **`file:line`** the trace reached
- a **testable prediction** — what would be observed if the hypothesis were true, and what would be observed if it were false

**A hypothesis with no discriminating prediction is not ready to be promoted.** Send it back to Observe rather than to the falsifiers; there is nothing for them to test.

## Overriding `clink-brainstorm` — the one place these skills conflict

[`clink-brainstorm`](../clink-brainstorm/SKILL.md) runs its challenge loop and its forced adversarial round **by reusing each agent's own `continuation_id`**, so the probe reaches the seat that produced the position. **In its own file that is correct** — the round's subject is *"which approach do you favour"*, an opinion, and an agent revising its own opinion with full context is the point.

**Here it is wrong, and you must override it.** The subject is a claim about the world, not a preference. Run the falsify round with **fresh threads and, where possible, different clients**, and give them the evidence rather than the transcript.

The distinction generalises: **an opinion may be self-revised; a claim about the world needs an outside check.** That is `mechanisms over judgment` applied at the level of a seat.

## When to stop

- **Falsified** → back to Observe with what the falsifier found. This is progress, not a setback; you spent one round to avoid coding the wrong theory.
- **Survived** → Repair, fresh seat, `tdd`.
- **Neither** — it survived but nothing discriminating was tested → the prediction was too weak. Design a sharper experiment; do not run the same round again with more effort.
- **Two full cycles with no discriminating evidence** → stop delegating. The bug is telling you the instrumentation is missing, and no number of agents substitutes for a log line you have not added yet.

**Say which of these ended the hunt when you report it.** "Fixed" after a hunt that never falsified anything is a hypothesis wearing a verdict's clothes.