| name | doubt_driven_development_skill |
| 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. |
| version | 1.0.0 |
| type | orchestrator |
| license | N/A |
| category | orchestration |
| requirements | ["cpu"] |
| enable_evolving | false |
| metadata | {} |
Doubt-Driven Development
AgentEvolver adaptation. This skill was adapted from a general engineering-workflow skill for use by AgentEvolver worker/orchestrator agents. The execution model here is autonomous and non-interactive: act through the framework tools (bash_tool, read_file_tool, grep_search_tool, git_tool, …) and deliver the result via done_tool. Code examples written in JS/TS/npm are illustrative of the method — apply the same idea in the task's actual language and commands. Where this guidance conflicts with the repo's CLAUDE.md or an existing project skill, the latter wins. The methodology body below is kept as-is.
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 after-the-fact code review. Code 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 runs from the orchestrator (MetaAgent) session, where Step 3 (DOUBT, detailed below) can spawn a fresh-context worker sub-agent to review.
- Don't run it nested inside a worker that cannot itself spawn a sub-agent. Surface that to the orchestrator and let the main session run doubt-driven. 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.
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.
Spawn the reviewer as a fresh worker sub-agent with isolated context (a general review worker, or code_review_skill for a diff). It must not inherit your reasoning.
The adversarial prompt above takes precedence over any reviewer's default response shape. A general review sub-agent may be written to produce balanced verdicts with both strengths and weaknesses; doubt-driven needs issues-only output. Paste the adversarial prompt verbatim so it overrides that default. If it can't be overridden cleanly, use a generic sub-agent with the adversarial prompt.
Second-opinion escalation
A single reviewer shares blind spots with the author. For high-stakes artifacts, spawn a second, independent review sub-agent — ideally on a different model — with the same ARTIFACT + CONTRACT and adversarial prompt, then reconcile both. Keep each reviewer's context isolated: pass no CLAIM and no session history.
This is optional and costs extra sub-agent budget — reserve it for irreversible or high-blast-radius decisions. In autonomous / non-interactive runs, default to a single reviewer unless the task explicitly calls for more.
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. Moments of certainty are exactly when blind spots hide. |
| "Spawning a reviewer is expensive" | Debugging a wrong commit in production is more expensive. The check is bounded; the bug isn't. |
| "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 code review" | Code review is a final gate. Doubt-driven catches wrong directions early when course-correction is cheap. Once it's committed it's too late. |
| "If I doubt every step I'll never ship" | The skill applies to non-trivial decisions, not every keystroke. Re-read "When NOT to Use." |
| "Two opinions are always better than one" | Not when the second has less context and produces noise. Reconcile, don't defer. |
| "The reviewer disagreed so I was wrong" | The reviewer lacks your context — disagreement is information, not verdict. Re-read the artifact, classify, then decide. |
| "A second reviewer is always better" | A second, different-model reviewer catches blind spots one model shares with itself, but it costs extra sub-agent budget. Reserve it for high-stakes artifacts; a single reviewer is the default. |
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
- Re-spawning fresh-context on an unchanged artifact (you'll get the same findings; you're stalling)
- Doubt theater (checkable signal): across 2 or more cycles where the reviewer surfaced substantive findings, zero findings were classified as actionable. You are validating, not doubting. Stop and escalate.
- Doubting only after committing — that's after-the-fact code review, not doubt-driven development
- Stripping the contract from the reviewer's input
- Passing the CLAIM to the reviewer (biases toward agreement)
Interaction with Other Skills
code_review_skill: complementary. code_review_skill is a post-hoc verdict on a finished diff; doubt-driven is in-flight per-decision. Use both.source_driven_development_skill: SDD verifies facts about frameworks against official docs. Doubt-driven verifies your reasoning about the artifact. SDD checks the API exists; doubt-driven checks you used it correctly under the contract.test_driven_development_skill: 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_skill: when the reviewer surfaces a real failure mode, drop into the debugging skill to localize and fix.
Verification
After applying doubt-driven development:
