doubt-driven-development

Doubt-Driven Development

Skill Overview

Doubt-driven development is a software development methodology that verifies code correctness by introducing adversarial review before critical decisions, preventing production errors caused by blind confidence.

Applicable Scenarios

1. High-Risk Architectural Decisions

When making decisions that affect system architecture, service boundaries, or irreversible operations (such as production deployments and data migrations), doubt-driven development helps identify hidden assumptions and potential failure modes, uncovering design flaws before they cause actual harm.

2. Critical Changes in Unfamiliar Codebases

When working with unfamiliar code or complex modules, the five-step CLAIM-EXTRACT-DOUBT-RECONCILE process systematically questions every nontrivial decision, preventing incorrect decisions caused by missing context. It is particularly suitable for properties that type systems cannot verify, such as thread safety and concurrency control.

3. Development of Security-Sensitive Logic

For high-risk logic involving user data security, authorization, or financial calculations, doubt-driven development uses adversarial review and cross-model verification to ensure correctness under various boundary conditions and malformed inputs, uncovering deep logical flaws earlier than traditional testing.

Core Features

1. Adversarial Review Process

Provides a structured five-step review process (CLAIM: state the decision → EXTRACT: extract artifacts → DOUBT: challenge adversarially → RECONCILE: reconcile findings → STOP: enforce a bounded loop). Reviewers working from fresh context focus specifically on finding problems rather than confirming correctness, effectively uncovering hidden assumptions, edge cases, and shared-state issues.

2. Cross-Model Verification Mechanism

Supports secondary review through external tools such as Gemini CLI and Codex CLI, overcoming the blind spots of a single model. It automatically offers a choice in interactive sessions and explicitly skips the process in non-interactive environments, balancing review quality and tool costs while improving the reliability of critical decisions.

3. Intelligent Review Classification System

Automatically categorizes review findings into four priority levels (contract misinterpretation → actionable issue → valid trade-off → noise), avoiding both blind acceptance of review results and indiscriminate skepticism. This helps developers maintain a questioning mindset while preserving development efficiency, clearly distinguishing issues that require fixes from acceptable technical trade-offs.

Frequently Asked Questions

How is doubt-driven development different from traditional code review?

Doubt-driven development involves adversarial questioning as decisions are being made, whereas traditional review is typically an after-the-fact evaluation. Doubt-driven development uses a reviewer with fresh context to look for problems before code is committed, when the cost of correcting errors is far lower than during the PR stage or in production. The two approaches work best when used together.

How do I determine which decisions require doubt-driven development?

Not every keystroke requires questioning. Doubt-driven development should be used when a decision meets any of the following conditions: it introduces or modifies branching logic; crosses module or service boundaries; asserts properties that the type system cannot verify (such as thread safety or idempotency); depends for correctness on context that future readers cannot see; or has an irreversible impact (such as a production deployment or data migration).

Will using doubt-driven development significantly slow down development?

This skill applies only to nontrivial decisions; mechanical operations (such as renaming and formatting) and explicit user instructions do not require it. Although it adds review time in the short term, it avoids the far greater costs of debugging in production and emergency fixes. By limiting each review to three cycles and using it only for high-risk decisions, it can improve development efficiency overall.