doubt-driven-development Skill for Claude: Cross-Examine Decisions

doubt-driven-development makes Claude hand each non-trivial decision to a fresh reviewer whose job is to find what is wrong with it.

Installs: 61K; on skills.sh
Stars: 112.6K; on GitHub
Updated: Nov 2026; last repo commit

This skill, from Addy Osmani's agent-skills collection, is a habit rather than a command. Before a non-trivial decision stands, Claude states the claim, strips out its own reasoning, and sends only the artifact and the contract to a reviewer with fresh context. The reviewer is told to find issues, not approve.

Claude then sorts every finding, and the loop stops after trivial findings, three cycles, or your say-so. In an interactive session it must offer a cross-model second opinion each cycle (Gemini CLI, Codex CLI, or manual). It only runs an outside CLI after you confirm the exact command.

Good for

Developers working on auth, migrations or other irreversible changes
Anyone in unfamiliar code who wants assumptions checked early
Reviewers who want a second opinion before a PR exists

Install doubt-driven-development

Claude Code

Copy this prompt.

Install the doubt-driven-development skill in Claude Code. Run this command:

npx skills add https://github.com/addyosmani/agent-skills --skill doubt-driven-development

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Subjects every non-trivial decision to a fresh-context adversarial review before it stands. Use when you want every assumption cross-examined before proceeding, when stress-testing a plan for hidden failure modes, when correctness matters more than speed, when working in unfamiliar code, when stakes are high (production auth, security-sensitive logic, a high-stakes migration, irreversible operations), or any time a confident output would be cheaper to verify now than to debug later.

Sections in SKILL.md

Overview
When to Use
Loading Constraints
The Process
Step 1: CLAIM — Surface what stands
Step 2: EXTRACT — Smallest reviewable unit
Step 3: DOUBT — Invoke the fresh-context reviewer
Step 4: RECONCILE — Fold findings back
Step 5: STOP — Bounded loop, not recursion
Common Rationalizations
Red Flags
Interaction with Other Skills
Verification

Key facts

Author: addyosmani (GitHub repo owner)
Repo: addyosmani/agent-skills
Installs on skills.sh: 60,986 as of 2026-11-02
GitHub stars (repo): 112,555 as of 2026-11-02
Last repo commit: 2026-11-01
License: MIT
Files: 1 file (SKILL.md only)
Works in: Claude Code, Cursor, Codex, Gemini CLI, Antigravity CLI, Windsurf, OpenCode, GitHub Copilot and Kiro (README lists setup for each)
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass

What it includes

Write the decision and why it matters
Two or three lines naming what is about to stand. If it cannot be written that compactly, the skill says it is a vibe, not a decision.
Step 1: CLAIM
Smallest reviewable unit: artifact plus contract
The diff or function, plus the constraints it must meet. Claude strips its reasoning but keeps evidence that contradicts the claim.
Step 2: EXTRACT
Fresh-context reviewer with an adversarial prompt
The reviewer gets artifact and contract only, never the claim, and is told to find issues. In Claude Code the role-based reviewers in the repo's agents/ folder can be used.
Runs code · Step 3: DOUBT
Offer Gemini CLI, Codex CLI, manual or skip
Interactive sessions must always offer it. Claude checks the CLI is in PATH, tests it, confirms the exact command with you and pipes the prompt through a file. It is skipped, and announced, in non-interactive runs.
Runs code · Cross-model escalation
Sort findings: misread, actionable, trade-off, noise
In that order of precedence. Claude re-reads the artifact against each finding instead of rubber-stamping the reviewer.
Step 4: RECONCILE
Trivial findings, three cycles, or 'ship it'
After three cycles with substantive findings, Claude escalates to you instead of grinding a fourth. A large artifact is decomposed rather than given more cycles.
Step 5: STOP

From the official docs

Permissions

Medium risk

The main risk is the optional cross-model step, which sends your code to another AI tool and runs a command on your machine. Decline it for private code and read any command before you approve it.

What it can do

Read your data
Create and change things
Delete things
Read-only modeHow to turn it on

Watch out for

It can send your code to another AI tool
If you pick Gemini CLI or Codex CLI, Claude writes the artifact and prompt to a file and pipes it to that tool. Choose skip for private code, and read the command before you approve it.
It can run shell commands on your machine
The cross-model step has Claude write the prompt to a temp file, run `which`, a version check and the review command. The SKILL.md requires your authorization for each invocation, so decline any you do not recognise.
A second reviewer can also be wrong
The SKILL.md says the fresh reviewer lacks your context and can produce noise. Claude is told to re-read the artifact against each finding before acting on it.

Technical details

Turning on read-only	The SKILL.md's example commands run Codex with --sandbox read-only and Gemini with --approval-mode plan.
Talks to	Gemini CLI or Codex CLI provider, only if you approve cross-model review
Sign-in and keys	The SKILL.md names no credentials of its own. It tells Claude to confirm required flags, auth and environment variables for the outside CLI with you.

Questions

What does doubt-driven-development do?

It makes Claude cross-examine non-trivial decisions before they stand. Claude spawns a reviewer with fresh context, passes it the artifact and the contract but not its own conclusion, and treats the findings as data to sort, not a verdict.

How do I install it?

Use the install box above. The README gives npx skills add addyosmani/agent-skills --skill doubt-driven-development for a single skill. The README says a per-skill install copies only skills/<name>/, not the repo-level references/ folder. This SKILL.md points to ../../references/orchestration-patterns.md and an agents/ roster, so a per-skill install will not include those.

How is it different from /review?

The SKILL.md says /review is a verdict on a finished artifact. This skill is an in-flight posture, applied while course-correction is still cheap. It lists the two as complementary.

Will it run Gemini or Codex on my machine?

Only if you pick that option and confirm the exact command. The SKILL.md says never to invoke an external CLI without explicit authorization, and each invocation needs its own go-ahead. Its examples run Codex with --sandbox read-only and Gemini with --approval-mode plan.

Does it slow every task down?

The SKILL.md limits it to non-trivial decisions: new branching logic, changes across a module boundary, claims the compiler cannot check, or irreversible changes. Renames, formatting, summaries and one-line fixes are excluded.

Can I add it to a subagent persona?

No. The SKILL.md says not to add it to a persona's skills: frontmatter, because the persona would spawn another persona. It is built for the main session.

Is it safe to use?

It adds extra review steps to your session. The part to watch is cross-model review, which sends your code to another AI tool and has Claude run shell commands once you approve them. Say skip if the code is private, and check any command Claude proposes before it runs.

Information

updated Nov 2, 2026

Repository: addyosmani/agent-skills
Folder: skills/doubt-driven-development

addyosmani/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 2

doubt-driven-development SKILL.md · github.com
addyosmani/agent-skills README · github.com