doubt-driven-development

name	doubt-driven-development
description	Subjects every non-trivial decision to a fresh-context adversarial review before it stands. Use when correctness matters more than speed, when working in unfamiliar code, when stakes are high (production, security-sensitive logic, irreversible operations), or any time a confident output would be cheaper to verify now than to debug later.

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.

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 author — a colder, different-architecture model catches them. In interactive sessions, always offer cross-model; never silently skip.

Step 1: Ask the user

After single-model review but before RECONCILE: "Single-model review complete. Want a cross-model second opinion? Options: Gemini CLI, Codex CLI, manual external review, or skip." The user decides whether the cost is worth it.

Step 2: If user picks a CLI — verify, then invoke

1. Check tool in PATH, test it works.
2. Confirm exact invocation with user (flags, auth, env vars).
3. Write prompt to temp file, pipe via stdin — never interpolate artifact into shell-quoted argument (backticks, $(...), quotes in code break inline args).
4. Pass ARTIFACT + CONTRACT only. No session context, no CLAIM.
5. Use read-only sandbox where available to prevent prompt injection execution against workspace.

Step 3: If CLI unavailable — surface failure explicitly, offer manual/alternative/skip. Never silently fall back.

Step 4: User skips — acknowledge: "Proceeding with single-model findings only." Silent skipping is not allowed.

Non-interactive (CI, /loop): cross-model skipped, announced in output. Never invoke CLI without user authorization.

Step 4: RECONCILE — Fold findings back

The reviewer's output is data, not verdict. You are still the orchestrator. Re-read the artifact text against each finding before classifying — rubber-stamping the reviewer is the same failure mode as ignoring it.

For each finding, classify in this precedence order (first matching class wins):

1. Contract misread — reviewer flagged something specifically because the CONTRACT you provided was unclear or incomplete. Fix the contract first, re-classify on the next cycle.
2. Valid + actionable — real issue requiring a change to the artifact. Change it, re-loop.
3. Valid trade-off — issue is real but cost of fixing exceeds cost of accepting. Document the trade-off explicitly so the user sees it.
4. Noise — reviewer flagged something that's actually correct under context the reviewer didn't have. Note it, move on, and ask: would adding that context to the contract have prevented the false flag?

A fresh reviewer can be wrong because it lacks context. Don't defer just because it's "fresh."

Step 5: STOP — Bounded loop, not recursion

Stop when:

• Next iteration returns only trivial or already-considered findings, or
• 3 cycles completed (escalate to user, don't grind a fourth alone), or
• User explicitly says "ship it"

If after 3 cycles the reviewer still surfaces substantive issues, the artifact may not be ready. Surface this to the user — three unresolved cycles is information about the artifact, not a reason to keep looping.

If 3 cycles is "obviously insufficient" because the artifact is large: the artifact is too big — return to Step 2 and decompose. Do not lift the bound.

Common Rationalizations

Rationalization	Reality
"I'm confident, skip doubt"	Confidence ≠ correctness on novel problems. Certainty hides blind spots.
"Reviewer is expensive"	Debugging wrong commit in production costs more.
"I'll do /review at the end"	Doubt-driven catches wrong directions early when correction is cheap.
"If I doubt everything I'll never ship"	Applies to non-trivial decisions only, not every keystroke.
"Cross-model is always better"	It catches blind spots a single model shares with itself, but adds cost. Offer every cycle — user decides.

Red Flags

• Spawning reviewer for trivial changes (rename, format)
• Treating reviewer as authoritative without re-reading artifact
• Looping >3 cycles without escalating
• Prompting "is this good?" instead of "find issues"
• Skipping doubt on high-stakes decisions under time pressure
• Doubt theater: ≥2 cycles with substantive findings, zero actionable — you're validating, not doubting
• Doubting only after committing (that's /review)
• Silently skipping cross-model in interactive cycle
• Passing CLAIM to reviewer (biases toward agreement)

Interaction with Other Skills

• code-review-expert / /review: post-hoc PR verdict; doubt-driven is in-flight per-decision. Use both.
• source-driven-development: SDD verifies framework facts; doubt-driven verifies your reasoning.
• testing-patterns: TDD's RED step is doubt made concrete — a failing test satisfies the doubt step for behavioral claims.
• systematic-debugging: when reviewer surfaces a real failure mode, drop into debug skill.
• references/orchestration-patterns.md: main session orchestrates; personas don't invoke other personas.

Verification

After applying doubt-driven development:

• Every non-trivial decision (per the definition above) was named explicitly as a CLAIM before standing
• At least one fresh-context review per non-trivial artifact (a failing test produced by TDD's RED step satisfies this for behavioral claims, per Interaction with Other Skills)
• The reviewer received ARTIFACT + CONTRACT — NOT the CLAIM, NOT your reasoning
• The reviewer's prompt was adversarial ("find issues"), not validating ("is it good")
• Findings were classified against the artifact text (not rubber-stamped) using the precedence: contract misread / actionable / trade-off / noise
• A stop condition was met (trivial findings, 3 cycles, or user override)
• In interactive mode, cross-model was explicitly offered to the user (regardless of artifact stakes) and the response was acknowledged in the output
• In non-interactive mode, cross-model was skipped and the skip was announced
• Any external CLI invocation was preceded by a PATH check, a working-binary test, syntax confirmation with the user, and explicit authorization to run