doubt-driven-development

Doubt-Driven Development

Overview

A confident answer is not the same as a correct answer. Long sessions accumulate context and quietly turn assumptions into "facts" without anyone noticing. Doubt-Driven Development is a discipline: before any non-trivial output is finalized, materialize a reviewer with a fresh context whose bias isfalsification, not approval.

This is not /review。/review is a verdict on a finished artifact. This is an ongoing stance: subject non-trivial decisions to cross-examination while course correction is still cheap.

When to use

A decision isnon-trivialwhen at least any one of the following conditions is met:

Introduces or modifies branching logic
Crosses module or service boundaries
Asserts a property that the type system or compiler cannot verify (thread safety, idempotency, ordering, invariants)
Correctness depends on context that future readers cannot see
The blast radius is irreversible (production deployments, data migrations, public API changes)

Apply this skill in the following scenarios:

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 with code you do not fully understand

When not to use:

Mechanical operations (renaming, formatting, moving files)
Following clear, unambiguous user instructions
Reading or summarizing existing code
One-line changes whose correctness is obvious
Pure tooling operations (running tests, listing files)
The user explicitly asks for speed over verification

If you doubt every keystroke, you will never ship anything. This skill applies only to the non-trivial decisions defined above.

Loading constraints

This skill is designed to be used by themain-session orchestrator, because step 3 (DOUBT, see 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, which is exactly the orchestration anti-pattern that ../../references/orchestration-patterns.md explicitly prohibits ("personas do not invoke other personas").
If you find yourself applying this skill in a subagent context(Claude Code blocks nested subagent spawn): the preferred path is to tell the user that doubt-driven cannot run nested, and let the main session handle it. Only as a last resort, use the degraded self-challenge fallback: rewrite ARTIFACT + CONTRACT into a fresh self-prompt with a hard mental separation, isolated from prior reasoning, and perform steps 1-5. Thisis not a fresh-context review(you are carrying your own context), so mark the result as degraded, and prefer escalating when the user is reachable.

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 — present what is about to be established

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 cannot write the claim this compactly, what you have is a feeling, not a decision. Present it before scrutinizing it.

Step 2: EXTRACT — the minimal reviewable unit

What a fresh-context reviewer needs isartifactandcontract, not your train of thought.

Code: the diff or function, not the whole file
Decision: a 3-5 sentence proposal, plus the constraints it must satisfy
Assertion: the claim plus the evidence allegedly supporting it (kept distinct from the Step 1 CLAIM block, which is the assumption the orchestrator is submitting for scrutiny)

Strip out your reasoning. If you hand over conclusions, what you get back is endorsement of conclusions. The unit must be small enough for the reviewer to fit it into their head in one pass; if it is a 500-line PR, break it down first.

Step 3: DOUBT — invoke a fresh-context reviewer

The reviewer's prompt must be adversarial. The framing determines 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 only ARTIFACT + CONTRACT. Do not pass CLAIM. Handing your conclusions to the reviewer biases it toward agreement. The reviewer must independently judge whether the artifact satisfies the contract.

In Claude Code,agents/ role-based reviewers natively launch with isolated context and can be used here. See agents/ 's roster and the domain matching relationships.

The adversarial prompt above takes precedence over the persona's default response shape. A persona like code-reviewer is written to output a balanced verdict with strengths and weaknesses; doubt-driven requires outputting only problems. Paste the adversarial prompt verbatim into the invocation so it overrides the persona's default behavior. If a persona's response shape cannot be cleanly overridden, fall back to a generic subagent with that adversarial prompt.

Cross-model escalation

A single-model reviewer shares blind spots with the original author; a colder, architecturally different model can catch those blind spots. Doubt-driven is inherently opt-in for non-trivial decisions, so within that scope, offering a cross-model option is one of the skill's values, not optional friction.

Interactive session: always offer. Do not silently skip.

Step 1: Ask the user

After the single-model review in Step 3 above completes and before RECONCILE, pause and ask:

"Single-model review complete. Want a cross-model second opinion? Options: Gemini CLI, Codex CLI, manual external review (you paste it elsewhere), or skip."

This question is mandatory in every interactive doubt cycle, even if the artifact appears very low-risk. The user, not the agent, decides whether the cost is worth it. The agent's job is to present the choice.

Step 2: If the user chooses the CLI, verify before invoking

Check whether the tool is on PATH (which gemini、which codex）。
Test that it works before passing the full prompt (gemini --version or an equivalent command). A stale or broken binary may pass which, but fail on real input.
Confirm the exact invocation with the user, including required flags, auth, and env vars (e.g. API keys). Implementations vary; never assume.
Pass only ARTIFACT + CONTRACT + the adversarial prompt. Do not pass session context, and do not pass CLAIM.
Watch out for shell escaping. If the artifact contains quotes,$(...) , or backticks, prefer stdin (echo … | gemini）or heredoc, rather than inline -p "…". When in doubt, ask the user to confirm the invocation before running it.
Carry the output into Step 4 (RECONCILE).

Never insert an artifact into a shell-quoted argument. Code, Markdown, and review prompts often contain backticks,$(...) and quote characters that will truncate the prompt or execute embedded shell. Write the full prompt to a file and pass it in via a stdin pipe.

Example form (verify flags against installed tools; syntax varies across implementations and versions):

# Write the adversarial prompt + ARTIFACT + CONTRACT to a temp file first.
# Then pipe via stdin so shell metacharacters in the artifact stay inert.

# Codex (read-only sandbox keeps the CLI from writing to your workspace):
codex exec --sandbox read-only -C <repo-path> - < /tmp/doubt-prompt.md

# Gemini ('--approval-mode plan' is read-only; '-p ""' triggers non-interactive
# mode and the prompt is read from stdin):
gemini --approval-mode plan -p "" < /tmp/doubt-prompt.md

A read-only sandbox is a load-bearing detail: the doubt artifact itself may contain intentional or unintentional instructions (prompt injection) that a cross-model CLI could otherwise execute against your workspace.

Step 3: If the CLI is unavailable or fails

Present the failure explicitly. Offer options: the user runs it manually, tries a different tool, or skips. Do not silently fall back to a single model; the user should know that cross-model did not happen.

Step 4: If the user skips

Confirm the skip in the output ("Proceeding with single-model findings only"), then continue to RECONCILE. Skipping is fine; silently skipping is not.

Non-interactive context（CI、/loop、autonomous-loop、scheduled runs）：

Cross-model will beskipped, and the output muststateskip:"Cross-model skipped: non-interactive context."
Never invoke an external CLI without the user's explicit authorization, this is a load-bearing security property.

Cross-model adds cost, latency, and tool fragility. The agent presents the choice at each cycle; the user decides whether the artifact is worth it.

Step 4: RECONCILE — merge findings

The reviewer's output is data, not a verdict.You are still the orchestrator. Before classifying each finding, reread it against the artifact text; rubber-stamping the reviewer is the same failure mode as ignoring it.

For each finding, classify it in the followingpriority order(the first matching category wins):

Contract misread: The reviewer flagged something because the CONTRACT you provided was unclear or incomplete. Fix the contract first, then reclassify in the next round.
Valid + actionable: A real issue that requires modifying the artifact. After modifying, loop again.
Valid trade-off: The issue is real, but the cost of fixing it exceeds the cost of accepting it. Record the trade-off explicitly so the user can see it.
Noise: The reviewer flagged something that is actually correct given the context it lacks. Record it, continue, and ask: if that context were added to the contract, would this false flag be avoided?

A brand-new reviewer may err due to missing context. Do not defer to it just because it is “fresh.”

Step 5: STOP — a bounded loop, not recursion

Stop under the following conditions:

The next round returns only trivial or already-considered findings,or
3 cycles have been completed (escalate to the user; do not grind out a fourth round on your own),or
The user explicitly says “ship it”

If the reviewer still raises substantive issues after 3 cycles, the artifact may not be ready. Present this to the user; three unresolved rounds is itself information about the artifact, not a reason to keep looping.

If 3 rounds is 'obviously not enough' because the artifact is large: that means the artifact is too large. Go back to step 2 and break it down. Do not raise the limit.

Common Self-Justifications

Self-Justification	Reality
"I'm pretty confident, skip the doubt step"	On new problems, confidence correlates poorly with correctness. Blind spots hide most easily when you feel most certain.
"Spawning a reviewer is too expensive"	Debugging a bad commit in production is more expensive. Checks are bounded; bugs are not.
"Reviewers just nitpick"	That only happens when scope is unset. Constrain the prompt to "issues that would make it fail under the contract."
"I'll just use `/review` for doubt at the end"	`/review` is the final gate. Doubt-driven catches wrong directions while course correction is still cheap. By the PR stage it's too late.
"If I doubt every step I'll never ship"	This skill applies to non-trivial decisions, not every keystroke. Reread "When NOT to Use."
"Two opinions are always better than one"	Not when the second opinion has less context and generates noise. Reconcile, don't defer.
"The reviewer disagrees, so I'm wrong"	The reviewer lacks your context. Disagreement is information, not a verdict. Reread the artifact, classify, then decide.
"Cross-model is always better"	Cross-model can catch blind spots a single model shares with itself, but it adds cost and tool fragility. Offer it in every interactive doubt cycle and let the user decide whether the artifact is worth it. The agent's job is to present the choice, not to treat it as a gate.
"The user agreed once, so I can keep invoking the CLI"	Every invocation needs separate authorization. The artifact, prompt, and flags change between invocations; reconfirm the exact command before each run.

Red Flags

Spawning a fresh-context reviewer for a one-line rename or formatting
Treating reviewer output as authoritative without rereading the artifact text
Looping more than 3 cycles without escalating to the user
Prompting the reviewer with "is this good?" instead of "find issues"
Skipping doubt on high-stakes decisions due to time pressure
Respawning a fresh context without modifying the artifact (you'll get the same findings; this is stalling)
Doubt theater (detectable signal): in 2 or more consecutive cycles, the reviewer raised substantive findings, but 0 findings were classified as actionable. You're validating, not doubting. Stop and escalate.
Doubting only after committing, that's /review, not doubt-driven development
Hardcoding external CLI calls without confirming with the user that the tool exists, is configured, and accepts that syntax
Silently skipping cross-model in an interactive doubt cycle. Even if not recommended, the offer must be visible. Skipping is fine; silently skipping is not.
Silently falling back when an external CLI errors or is missing; surface the failure and let the user redirect
Stripping the contract from reviewer input
Pass CLAIM to the reviewer (which will lean toward agreeing)

Interaction with Other Skills

code-review-and-quality / /review: complementary./review is post-hoc PR adjudication; doubt-driven is an in-progress per-decision stance. Use both.
source-driven-development: SDD verifies against official documentationframework facts. Doubt-driven verifiesyour reasoning about the artifact. SDD checks whether the API exists; doubt-driven checks whether you are using it correctly under the contract.
test-driven-development: TDD's RED step is concretized doubt; a failing test is a falsification attempt. When TDD applies, that failing testisthe doubt step for the behavior claim.
debugging-and-error-recovery: when the reviewer raises a real failure mode, enter the debugging skill to locate and fix it.
Repository orchestration rules（../../references/orchestration-patterns.md): this skill orchestrates from the main session. A persona invoking another persona is anti-pattern B, see the loading constraints above.

Verification

After applying doubt-driven development:

Every non-trivial decision (as defined above) has been explicitly named as a CLAIM before being accepted
Every non-trivial artifact has had at least one fresh-context review (a failing test produced by TDD's RED step can satisfy this requirement for behavior claims, see Interaction with Other Skills)
The reviewer received ARTIFACT + CONTRACT, not CLAIM, and not your reasoning
The reviewer's prompt is adversarial ("find issues"), not verification-style ("is it good")
Findings have been classified based on the artifact text (not rubber-stamp acceptance), with classification priority: contract misread / actionable / trade-off / noise
The stop condition has been met (trivial finding, 3 cycles, or user override)
In interactive mode, the user has beenexplicitly offered cross-model (regardless of artifact risk), and their response has been confirmed in the output
In non-interactive mode, cross-model has been skipped and the skip declared
Before any external CLI call, a PATH check, binary availability test, syntax confirmation with the user, and explicit run authorization have all been completed