helderberto/doubt-driven-development

Doubt-Driven Development

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 code-review or review. Those are verdicts on finished artifacts. Doubt-driven is an in-flight posture: non-trivial decisions get cross-examined while course-correction is still cheap.

When a decision is "non-trivial"

At least one of these holds:

• Introduces or modifies branching logic
• Crosses a module or service boundary
• Asserts a property the type system or compiler cannot verify (thread safety, idempotence, ordering, invariants)
• Correctness depends on context the future reader cannot see
• Blast radius is irreversible (production deploy, data migration, public API change)

Apply 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

The 5-step process

1. ARTIFACT

Write down precisely what was decided / will be done. One paragraph. Concrete enough that a stranger could implement it.

2. CONTRACT

State the property the artifact must satisfy. Invariants, edge cases, error modes. What must remain true if this is correct?

3. DOUBT

Spawn a fresh-context reviewer whose only job is to disprove the artifact against the contract. The reviewer:

• Has not seen any prior reasoning in this session
• Receives only ARTIFACT + CONTRACT
• Tries to find counterexamples, edge cases, hidden coupling, false assumptions
• Outputs a verdict: HOLDS or BREAKS (with specific failure)

In Claude Code, this means spawning a subagent (e.g., general-purpose or junior-engineer) with a self-contained prompt. The reviewer must NOT inherit the orchestrator's confidence.

4. RECONCILE

If reviewer returns HOLDS → proceed. If reviewer returns BREAKS → either:

• Fix the artifact to address the break, then loop back to step 3
• Demonstrate the break is non-applicable (write down why)
• Escalate to the human if the break reveals genuine ambiguity

5. STAND

Only after RECONCILE produces a clean HOLDS does the decision stand. Record the HOLDS in a code comment, ADR, or commit message when the property is non-obvious.

When NOT to apply (avoid analysis paralysis)

• Mechanical operations: renames, formatting, file moves
• Clear, unambiguous user instruction with no ambiguity
• 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. This is a tool for non-trivial decisions only.

Spawning the reviewer

The reviewer prompt must be self-contained — it has no memory of this session:

ARTIFACT:
<paste the one-paragraph description>

CONTRACT:
<paste invariants and edge cases>

Your job: disprove the artifact against the contract. Find a counterexample,
hidden coupling, false assumption, or edge case the artifact doesn't handle.
Output one of:
- HOLDS — explain why every invariant is preserved
- BREAKS — give the specific scenario that breaks it

Do not approve out of politeness. Find the flaw.

Loading constraints

Do not add this skill to a subagent persona's frontmatter. A persona that follows step 3 would spawn another persona — anti-pattern. Doubt-driven runs in the main session that has spawn authority.

If applied from inside a subagent (where nested spawn is blocked): flag to the user that doubt-driven needs main-session authority and let them handle it. As a degraded fallback only: rewrite ARTIFACT + CONTRACT as a fresh self-prompt with a hard mental separator from prior reasoning. Flag the result as degraded — it's not fresh-context review, you carry your own context with you.

Rules

• Apply only to non-trivial decisions (definition above)
• Reviewer must have fresh context — no inherited reasoning
• Reviewer is biased to disprove, not approve
• BREAKS findings either fix the artifact or get explicitly dismissed with a recorded reason
• Record non-obvious HOLDS as a comment / ADR / commit message
• Never silent-approve when the reviewer has not actually run

Red flags

• Skipping the reviewer because "it's probably fine"
• Reviewer agreeing too easily — prompt may be leaking confidence
• Re-running with a different prompt until HOLDS appears (cherry-picking)
• Applying to trivial work (creates ceremony, not safety)

Verification

After standing a non-trivial decision:

• [ ] ARTIFACT written explicitly
• [ ] CONTRACT enumerates invariants and edge cases
• [ ] Fresh-context reviewer ran and returned HOLDS
• [ ] If HOLDS was non-obvious, it's recorded somewhere the future reader will find