| 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. |
| phase | review |
| domains | ["review","debugging","security"] |
| stacks | ["any"] |
| allowed_agents | ["lead","developer","reviewer"] |
| surfaces | ["code-implementation","adversarial-review"] |
| skill_source | external |
| origin | addyosmani/agent-skills |
| status | active |
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.
The Process
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)
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.
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):
- 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.
- Valid + actionable — real issue requiring a change to the artifact. Change it, re-loop.
- Valid trade-off — issue is real but cost of fixing exceeds cost of accepting. Document the trade-off explicitly so the user sees it.
- 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 the doubt step" | Confidence correlates poorly with correctness on novel problems. |
| "Spawning a reviewer is expensive" | Debugging a wrong commit in production is more expensive. |
| "The reviewer will just nitpick" | Only if unscoped. Constrain the prompt to issues that would make this fail under the contract. |
"I'll do doubt at the end with /review" | /review is a final gate. Doubt-driven catches wrong directions early. |
| "If I doubt every step I'll never ship" | The skill applies to non-trivial decisions, not every keystroke. |
Red Flags
- Spawning a fresh-context reviewer for a one-line rename or formatting change
- Treating reviewer output as authoritative without re-reading the artifact text
- Looping >3 cycles without escalating to the user
- Prompting the reviewer with "is this good?" instead of "find issues"
- Skipping doubt under time pressure on a high-stakes decision
- Passing the CLAIM to the reviewer (biases toward agreement)
- Stripping the contract from the reviewer's input
Interaction with Other Skills
/review: complementary. /review is post-hoc PR verdict; doubt-driven is in-flight per-decision. Use both.source-driven-development: SDD verifies facts about frameworks against official docs. Doubt-driven verifies your reasoning about the artifact.test-driven-development: TDD's RED step is doubt made concrete — a failing test is a disproof attempt. When TDD applies, that failing test is the doubt step for behavioral claims.debugging-and-error-recovery: when the reviewer surfaces a real failure mode, drop into the debugging skill to localize and fix.
Verification
After applying doubt-driven development:
