Doubt Driven Development

Doubt-Driven Development

Purpose

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.

Stage: in-flight, applied during Plan and Implement. doubt is NOT a merge gate and is NOT one of the three agent-internal SHIP gates (quality-verification · Review fan-out · evaluator floors) — its whole value is firing before a decision reaches a gate, while reversing it is still cheap.

When to use / when to skip

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.

Inputs

doubt runs IN-FLIGHT during Plan or Implement — it is not a chain stage and consumes no upstream artifact file. The orchestrator (or the in-flight author — plan-breakdown or incremental-implementation) hands it exactly two things, the smallest reviewable unit (Step 2 EXTRACT):

• ARTIFACT — the in-flight decision under scrutiny: the diff/function, or the proposal in 3–5 sentences,

or the claim plus the evidence that supposedly supports it.

• CONTRACT — the properties the artifact must satisfy: the constraints, invariants, or the relevant

acceptance.md scenario the decision is meant to honor.

Refuse-to-run when there is no non-trivial decision to examine (see When to use / when to skip): mechanical edits, clear user instructions, read-only/summarize work, and obviously-correct one-liners get no doubt cycle. depth: lite — the refuse-to-run test is the triviality test, not a missing-file test (there is no chain artifact to be absent).

Depends on (contract): foundation only — doubt has no upstream house-skill dependency.

Loading Constraints

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

• doubt runs from the main-session orchestrator — the context that can spawn a fresh subagent for Step 3. Do not bury doubt inside a subagent: a subagent that reaches Step 3 cannot spawn a nested subagent (Claude Code blocks nested spawn), so its "fresh-context" review silently degrades to self-questioning — the orchestration anti-pattern named in ../../references/orchestration-patterns.md (a subagent invoking another subagent).
• 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: 
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.

Dispatch the reviewer as a fresh, code-cold subagent — the same fresh-context-per-subagent isolation the Review fan-out uses (see ../../references/orchestration-patterns.md). The house has no personas to reuse; the reviewer is a generic fresh-context subagent that starts with isolated context by design, handed the adversarial prompt below.

The subagent's default instinct is a balanced verdict (strengths + weaknesses); doubt needs issues-only output. Paste the adversarial prompt verbatim so it governs the response shape — the subagent finds issues, or states it cannot after thorough examination, and nothing else.

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 offering cross-model is part of the skill's value, not optional friction.

Interactive sessions: always offer. Never silently skip.

Step 1: Ask the user

After the single-model review in Step 3 above, but 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 on artifacts that feel low-stakes. The user — not the agent — decides whether the cost is worth it. The agent's job is to surface the choice.

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

1. Check the tool is in PATH (which gemini, which codex).
2. Test it works (gemini --version or equivalent) before passing the full prompt — a stale or broken binary may pass which but fail on real input.
3. Confirm the exact invocation with the user, including required flags, auth, and env vars (e.g., API keys). Implementations vary; never assume.
4. Pass ARTIFACT + CONTRACT + the adversarial prompt only. No session context, no CLAIM.
5. Mind shell escaping. If the artifact contains quotes, $(...), or backticks, prefer stdin (echo … | gemini) or a heredoc over inline -p "…". When in doubt, ask the user to confirm the invocation before running it.
6. Take the output into Step 4 (RECONCILE).

Never interpolate the artifact into a shell-quoted argument. Code, markdown, and review prompts routinely contain backticks, $(...), and quote characters that will either truncate the prompt or execute embedded shell. Write the full prompt to a file and pipe it through stdin.

Example shapes (verify flags against your installed tool — syntax differs 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  - 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 `/review`, not doubt-driven development
- Hardcoding an external CLI invocation without confirming with the user that the tool exists, is configured, and accepts that exact syntax
- **Silently skipping cross-model in an interactive doubt cycle.** Even when not recommending it, the offer must be visible. Skipping is fine; silent skipping is not.
- Falling back silently when an external CLI errors or is missing — surface the failure and let the user redirect
- Stripping the contract from the reviewer's input
- Passing the CLAIM to the reviewer (biases toward agreement)

## Interaction with Other Skills

- **`code-review`**: complementary. The merge-time Review fan-out 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*. SDD checks the API exists; doubt-driven checks you used it correctly under the contract.
- **`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.
- **Repo orchestration rules** (`../../references/orchestration-patterns.md`): this skill orchestrates from the main session. A persona calling another persona is anti-pattern B — see Loading Constraints above.

## Verification (ending criteria)

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

## Outputs & handoff contract

**Emits: `issues`** — the reviewer's adversarial findings, each CLASSIFIED by the Step 4 RECONCILE
precedence (contract-misread → actionable → trade-off → noise) and folded back into the artifact under
construction. `issues` are in-flight working data, **not** a chain artifact: doubt writes no `*.md` to the
resume spine and `docs/features//` gains no file.

**Stable sections a consumer reads:** none — `issues` are consumed immediately by the in-flight author
(`plan-breakdown` re-loops the plan; `incremental-implementation` re-loops the diff). Anything that must outlive the cycle
is recorded by that author in its own artifact (plan.md / the diff / a documented trade-off), never by doubt.

**STATE.md:** doubt drives **NO** gate transition. It is the in-flight adversarial posture during
Plan/Implement, deliberately distinct in timing from the merge-time Review fan-out (`code-review` ·
`code-simplification` · `security-and-hardening` · `performance-optimization`) and from the three agent-internal SHIP gates (quality-verification · Review fan-out ·
evaluator floors). doubt sets neither `slice state` nor `gate`. A *valid + actionable* finding it
surfaces is resolved **before** the slice ever reaches a gate — that is the point.

**Handoff:** the bounded loop ends on a Step 5 STOP condition (only trivial/already-considered findings,
3 cycles completed, or user override). On 3 unresolved cycles, **escalate to the user** rather than grind a
fourth — three unresolved cycles is information about the artifact, not a reason to keep looping.

## Subagents

For a fresh-context, code-cold pass, dispatch the **`adversarial-reviewer`** agent (`agents/adversarial-reviewer.md`) as an
independent subagent. This skill is the *method*; the agent is the *role* that applies it with no prior
context — preserving maker≠checker. Reach for it when a confident, high-stakes, or irreversible in-flight decision needs an independent skeptic.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [celestialdust](https://github.com/celestialdust)
- **Source:** [celestialdust/achilles-skills](https://github.com/celestialdust/achilles-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.