Doubt Driven Review

Doubt-Driven Development

Overview

A confident answer is not a correct one. Long sessions accumulate context that quietly turns assumptions into "facts" without anyone noticing. Doubt-driven development is the discipline of materializing a fresh-context reviewer — biased to disprove, not approve — before any non-trivial output stands.

This is not /review. /review is a verdict on a finished artifact. This is an in-flight posture: non-trivial decisions get cross-examined while course-correction is still cheap.

When to Use

A decision is non-trivial when at least one of these is true:

• It introduces or modifies branching logic
• It crosses a module or service boundary
• It asserts a property the type system or compiler cannot verify (thread safety, idempotence, ordering, invariants)
• Its correctness depends on context the future reader cannot see
• Its blast radius is irreversible (production deploy, data migration, public API change)

Apply the skill when:

• About to make an architectural decision under uncertainty
• About to commit non-trivial code
• About to claim a non-obvious fact ("this is safe", "this scales", "this matches the spec")
• Working in code you don't fully understand

When NOT to use:

• Mechanical operations (renaming, formatting, file moves)
• Following a clear, unambiguous user instruction
• Reading or summarizing existing code
• One-line changes with obvious correctness
• Pure tooling operations (running tests, listing files)
• The user has explicitly asked for speed over verification

If you doubt every keystroke, you ship nothing. The skill applies only to non-trivial decisions as defined above.

Loading Constraints

This skill is designed for the main-session orchestrator, where Step 3 (DOUBT, detailed below) can spawn a fresh-context reviewer.

• Do NOT add this skill to a persona's skills: frontmatter. A persona that follows Step 3 would spawn another persona — the orchestration anti-pattern explicitly forbidden by references/orchestration-patterns.md ("personas do not invoke other personas").
• If you find yourself applying this skill from inside a subagent context (where Claude Code prevents nested subagent spawn): the preferred path is to surface to the user that doubt-driven cannot run nested and let the main session handle it. As a last resort only, a degraded self-questioning fallback exists — rewrite ARTIFACT + CONTRACT as a fresh self-prompt with a hard mental separator from your prior reasoning, and walk Steps 1–5. This is not fresh-context review (you carry your own context with you), so flag the result as degraded and prefer escalation whenever the user is reachable.

The Process

Copy this checklist when applying the skill:

Doubt cycle:
- [ ] Step 1: CLAIM — wrote the claim + why-it-matters
- [ ] Step 2: EXTRACT — isolated artifact + contract, stripped reasoning
- [ ] Step 3: DOUBT — invoked fresh-context reviewer with adversarial prompt
- [ ] Step 4: RECONCILE — classified every finding against the artifact text
- [ ] Step 5: STOP — met stop condition (trivial findings, 3 cycles, or user override)

Step 1: CLAIM — Surface what stands

Name the decision in two or three lines:

CLAIM: "The new caching layer is thread-safe under the
        read-heavy workload described in the spec."
WHY THIS MATTERS: a race here corrupts user data and is
                  hard to detect in QA.

If you can't write the claim that compactly, you have a vibe, not a decision. Surface it before scrutinizing it.

Step 2: EXTRACT — Smallest reviewable unit

A fresh-context reviewer needs the artifact and the contract, not the journey.

• Code: the diff or the function — not the whole file
• Decision: the proposal in 3–5 sentences plus the constraints it has to satisfy
• Assertion: the claim plus the evidence that supposedly supports it (kept distinct from the Step 1 CLAIM block, which is the orchestrator's hypothesis under scrutiny)

Strip your reasoning. If you hand over conclusions, you'll get back validation of your conclusions. The unit must be small enough that a reviewer can hold it in mind in one read — if it's a 500-line PR, decompose first.

Step 3: DOUBT — Invoke the fresh-context reviewer

The reviewer's prompt must be adversarial. Framing decides the answer.

Adversarial review. Find what is wrong with this artifact.
Assume the author is overconfident. Look for:
- Unstated assumptions
- Edge cases not handled
- Hidden coupling or shared state
- Ways the contract could be violated
- Existing conventions this might break
- Failure modes under unexpected input

Do NOT validate. Do NOT summarize. Find issues, or state
explicitly that you cannot find any after thorough examination.

Verify each claim against the repository before relying on it.
If you cannot check a claim (no access, no tool, no network),
write `unverified` next to it instead of asserting it true or false.
If the CONTRACT lists candidate requirements, check every
candidate and report each one the artifact contradicts.

ARTIFACT: <paste artifact>
CONTRACT: <paste contract>

Pass ARTIFACT + CONTRACT only. Do NOT pass the CLAIM. Handing the reviewer your conclusion biases it toward agreement. The reviewer must independently determine whether the artifact satisfies the contract.

In Claude Code, the role-based reviewers in agents/ start with isolated context by design and are usable here — see agents/ for the roster and per-domain match.

The adversarial prompt above takes precedence over the persona's default response shape. Personas like code-reviewer are written to produce balanced verdicts with both strengths and weaknesses; doubt-driven needs issues-only output. Paste the adversarial prompt verbatim into the invocation so it overrides the persona's default. If a persona's response shape can't be overridden cleanly, fall back to a generic subagent with the adversarial prompt.

Cross-model escalation

A single-model reviewer shares blind spots with the original author — a colder, different-architecture model catches them. Doubt-driven is already opt-in for non-trivial decisions, so within that scope cross-model is part of the skill's value, not optional friction.

Automatic when a reviewer role is set. If a @propose-review-N role is configured AND probes clean (see Choosing the reviewer below), run the cross-model review automatically — do NOT ask the user first. A configured @propose-review-N series IS the user's standing decision that cross-model is wanted; asking again each cycle is redundant friction. Spawn the reviewer, take its output into RECONCILE, and announce in the output that cross-model ran ("Cross-model review ran automatically on @propose-review-N.").

Only ask when no reviewer role resolves. When the @propose-review-N series is empty or every role probes empty, fall back to the interactive offer below.

Step 1: Reviewer role set → run automatically; otherwise offer

After the single-model review in Step 3 above, but before RECONCILE:

• A @propose-review-N role resolves → skip the question. Run the cross-model pass automatically (probe-gated, walking the series), fold its findings into RECONCILE, and note in the output that it ran.

• No @propose-review-N role resolves (none configured, or all probe empty) → pause and offer:

  "Single-model review complete. No reviewer role is configured. Want a cross-model second opinion? Options: configure a @propose-review-N role now, manual external review (you paste it elsewhere), or skip."

The standing @propose-review-N config — not a per-cycle prompt — is where the user decides whether cross-model is worth the cost. When that config is absent, the agent surfaces the choice instead.

The cross-model path in Pi is a subagent on a @propose-review-N role. Pi's Agent tool takes a model param. Use a role ref (@propose-review-1, @propose-review-2, … @propose-review-x) — NOT a raw provider/model-id. Role refs resolve through the supported model:resolve handler and inherit the parent session's live registry, so a curated reviewer (including a custom-provider model) actually spawns. A raw provider/model-id bypasses that path; for a custom provider the child can build a registry that lacks the provider → empty output (the exact failure this role series exists to avoid). The subagent runs in isolated context by construction, passes ARTIFACT as a prompt string (no shell-escaping hazard), and can open repo files to verify the author's code claims. This skill does NOT shell out to an external review CLI; the only automated reviewer is the in-process subagent.

Agent(
  subagent_type: "Explore",           # or any read-capable label
  model: "@propose-review-1",                  # a curated cross-model reviewer role
  description: "Cross-model adversarial review",
  prompt: "<adversarial prompt> + ARTIFACT + CONTRACT"   # NO CLAIM, NO reasoning
)

Choosing the reviewer — walk the @propose-review-N role series. The operator pre-configures a numbered series of reviewer roles (propose-review-1, propose-review-2, … propose-review-x in ~/.pi/agent/providers.json#roles, editable via the update_roles tool or the dashboard Roles panel), each pointing at a different-architecture model than the author and verified reachable. Order matters: put cross-model reviewers first and any same-family-as-usual-author model (e.g. an Anthropic model when the author is typically Claude) last, so it only fires as the final fallback. The skill does not hand-pick or fuzzy-match a catalogue — it walks the series in order:

1. Start at @propose-review-1. Skip any role whose architecture family matches the author's (author is Claude → skip a propose-review-N that maps to claude-*) — a reviewer that shares the author's family shares its blind spots.
2. Probe before the real prompt with a trivial prompt ("Reply with exactly: OK"). Non-empty → use that role for the adversarial pass. Empty, or a resolution error → advance to @propose-review-2, @propose-review-3, … until one probes clean.
3. If no @propose-review-N role resolves (none configured, or all probe empty) and the session is interactive, offer to configure one on the spot — see Bootstrap a reviewer role below — before giving up. Only when the user declines, or the context is non-interactive, treat subagent cross-model as unavailable (Step 2) — offer manual review / skip. Never substitute a raw provider/model-id; that is the path that fails silently for custom providers.

Seeding the series (one-time). Assign each propose-review-N role a reachable, different-architecture model, cross-model reviewers first and any same-family fallback last — e.g. propose-review-1 → opencode-go/glm-5.2, propose-review-2 → deepseek/deepseek-v4-pro, propose-review-3 → anthropic/claude-opus-4-8 (Opus last). Enumerate reachable ids with pi --list-models or dashboard GET /api/models when deciding what to assign; assign via update_roles.

Bootstrap a reviewer role (interactive, when the series is empty or unreachable). On a machine where no @propose-review-N role is set — or none resolves — do NOT jump straight to skip. Configure one live:

1. Enumerate the reachable set with the list_models tool (or pi --list-models / dashboard GET /api/models). Keep only credentialed rows (excludedReason: null); prefer reasoning: true.
2. Drop the author's own architecture family (author is Claude → exclude anthropic/* / claude-*) so the reviewer does not share the author's blind spots.
3. Ask the user to choose via ask_user (method select), offering a handful of the strongest different-family candidates from the enumerated set (do not auto-pick).
4. Assign it via the role API — the update_roles tool: set_role, role: "propose-review-1" (or the next free propose-review-N slot), ref: "<chosen provider/model-id>". This persists to providers.json#roles, so the choice carries to every future session; never hand-edit the file.
5. Probe then spawn on the freshly-assigned @propose-review-N (same "Reply with exactly: OK" gate).

Interactive only — never enumerate-and-ask in CI / /loop / autonomous runs; there, skip per the non-interactive rule below.

Prerequisite + fallback (verify, do not assume):

1. A @propose-review-N role must be configured AND reachable. An unconfigured role, or one pointing at a non-reachable id, makes the spawn return empty output. Probe first ("Reply with exactly: OK"); empty → advance to the next @propose-review-N, never proceed on the empty one. (This series is preferred precisely because a role ref resolves through the parent's live registry; a raw provider/model-id can silently miss a custom provider.)
2. If the whole @propose-review-N series is exhausted with no clean probe, surface it explicitly (per Step 2 below) and fall back to manual external review. Do NOT silently proceed single-model, and do NOT substitute a raw provider/model-id.
3. Pass ARTIFACT + CONTRACT + adversarial prompt only — same rule as every cross-model path. No CLAIM.

Step 2: If the subagent reviewer is unavailable or fails

Surface the failure explicitly. Offer: run the review manually (paste ARTIFACT + CONTRACT + adversarial prompt into an external model yourself), or skip. A @propose-review-N series exhausted with every role probing empty counts as a failure — announce it. Do not silently fall back to single-model — the user should know cross-model didn't happen.

Step 3: If the user skips

Acknowledge the skip in the output ("Proceeding with single-model findings only") and continue to RECONCILE. Skipping is fine; silent skipping is not.

Non-interactive contexts (CI, /loop, autonomous-loop, scheduled runs):

• Cross-model is skipped, and the skip must be announced in the output: "Cross-model skipped: non-interactive context."

Cross-model adds cost and latency. When a reviewer role is set it runs automatically; when none is set, the agent surfaces the choice and the user decides whether this artifact warrants manual review.