Lar

Skill

Produtividade e fluxo de trabalho

doubt-driven-development

addyosmani/agent-skills

Submete todas as decisões não triviais a uma revisão adversária em um novo contexto antes de serem aprovadas, priorizando a precisão em detrimento da velocidade no caso de código de alto risco ou desconhecido.

...Expandir tudo

Tempo atualizado 3 de Setembro de 2026

# debugging # planning # security audit # code review # decision making # adversarial review

Quando estiver prestes a tomar uma decisão arquitetônica em situação de incerteza
Quando estiver prestes a fazer o commit de um código não trivial

Quando estiver prestes a afirmar um fato não óbvio (“isso é seguro”, “isso é escalável”, “isso está de acordo com a especificação”)

Ao trabalhar com código que você não compreende totalmente

Quando NÃO usar:

Operações mecânicas (renomeação, formatação, movimentação de arquivos)

Seguindo uma instrução clara e inequívoca do usuário

Ler ou resumir código existente

Alterações de uma linha com correção óbvia

Operações puramente técnicas (execução de testes, listagem de arquivos)

O usuário solicitou explicitamente que a velocidade fosse priorizada em relação à verificação

Se você duvidar de cada tecla digitada, não vai lançar nada. Essa habilidade se aplica apenas a decisões não triviais, conforme definido acima.

Restrições de carregamento

Essa habilidade foi projetada para o orquestrador da sessão principal, onde a Etapa 3 (DÚVIDA, detalhada abaixo) pode gerar um revisor de contexto novo.

NÃO adicione esta habilidade às habilidades de uma persona : frontmatter. Uma persona que siga a Etapa 3 geraria outra persona — o antipadrão de orquestração explicitamente proibido por references/orchestration-patterns.md (“personas não invocam outras personas”).
Se você se deparar com a necessidade de aplicar essa habilidade de dentro do contexto de um subagente (onde o Código Claude impede a geração aninhada de subagentes): o caminho preferencial é informar ao usuário que o modo “doubt-driven” não pode ser executado de forma aninhada e deixar que a sessão principal cuide disso. Somente como último recurso, existe um plano alternativo de autoquestionamento degradado — reescreva ARTIFACT + CONTRACT como um novo auto-prompt com uma separação mental rígida em relação ao seu raciocínio anterior e siga as Etapas 1 a 5. Isso não é uma revisão em um contexto novo (você carrega seu próprio contexto consigo), portanto, marque o resultado como degradado e opte pela escalonamento sempre que o usuário estiver disponível.

O Processo

Copie esta lista de verificação ao aplicar a habilidade:

Ciclo de dúvida:
- [ ] Etapa 1: AFIRMAÇÃO — redigi a afirmação + por que ela é importante
- [ ] Etapa 2: EXTRAÇÃO — isolei o artefato + contrato, removi o raciocínio
- [ ] Etapa 3: DÚVIDA — convoquei um revisor com contexto novo por meio de uma solicitação adversária
- [ ] Etapa 4: RECONCILIAR — classificou cada descoberta em relação ao texto do artefato
- [ ] Etapa 5: PARAR — atingiu a condição de parada (descobertas triviais, 3 ciclos ou anulação pelo usuário)

Etapa 1: ALEGAÇÃO — Identificar o que se destaca

Descreva a decisão em duas ou três linhas:

AFIRMAÇÃO: “A nova camada de cache é thread-safe sob a
        carga de trabalho com muitas leituras descrita na especificação.”
POR QUE ISSO É IMPORTANTE: uma corrida de acesso aqui corrompe os dados do usuário e é
                  difícil de detectar no controle de qualidade.

Se você não conseguir escrever a afirmação de forma tão concisa, você tem uma intuição, não uma decisão. Coloque isso à tona antes de analisá-la minuciosamente.

Etapa 2: EXTRAIR — A menor unidade revisável

Um revisor com um contexto novo precisa do artefato e do contrato, não da trajetória.

Código: a diferença ou a função — não o arquivo inteiro
Decisão: a proposta em 3 a 5 frases, além das restrições que ela deve satisfazer
Afirmação: a alegação mais as evidências que supostamente a sustentam (mantidas distintas do bloco ALEGAÇÃO da Etapa 1, que é a hipótese do orquestrador sob análise)

Simplifique seu raciocínio. Se você apresentar conclusões, receberá em troca a validação dessas conclusões. A unidade deve ser pequena o suficiente para que um revisor consiga mantê-la em mente em uma única leitura — se for um PR de 500 linhas, decomponha-o primeiro.

Etapa 3: DÚVIDA — Recorra a um revisor com uma perspectiva nova

A orientação dada ao revisor deve ser adversária. A forma como a questão é formulada determina a resposta.

Revisão contraditória. Descubra o que há de errado com este artefato.
Presuma que o autor está excessivamente confiante. Procure por:
- Suposições não declaradas
- Casos extremos não tratados
- Acoplamento oculto ou estado compartilhado
- Maneiras pelas quais o contrato poderia ser violado
- Convenções existentes que isso possa infringir
- Modos de falha sob entradas inesperadas

NÃO valide. NÃO resuma. Encontre problemas ou declare
explicitamente que não conseguiu encontrar nenhum após uma análise minuciosa.

ARTIFATO: 
CONTRATO:

Apresente APENAS o ARTIFATO + o CONTRATO. NÃO apresente a ALEGAÇÃO. Apresentar sua conclusão ao revisor influencia-o a concordar com ela. O revisor deve determinar de forma independente se o artefato satisfaz o contrato.

No Claude Code, os revisores baseados em funções em agents/ começam com um contexto isolado por padrão e podem ser utilizados aqui — consulte agents/ para ver a lista e a correspondência por domínio.

O prompt adversarial acima tem precedência sobre o formato de resposta padrão da persona. Personas como o revisor de código são programadas para produzir veredictos equilibrados, com pontos fortes e fracos; uma abordagem orientada pela dúvida requer uma saída que apresente apenas as questões. Cole o prompt adversarial literalmente na invocação para que ele substitua o padrão da persona. Se o formato de resposta de uma persona não puder ser substituído de forma clara, recorra a um subagente genérico com o prompt adversarial.

Escalonamento entre modelos

Um revisor de modelo único compartilha pontos cegos com o autor original — um modelo mais imparcial, com arquitetura diferente, os identifica. O modelo “orientado por dúvidas” já é ativado por padrão para decisões não triviais; portanto, dentro desse escopo, oferecer a escalonamento entre modelos faz parte do valor da habilidade, não um atrito opcional.

Sessões interativas: sempre ofereça. Nunca pule silenciosamente.

Passo 1: Pergunte ao usuário

Após a revisão do modelo único na Etapa 3 acima, mas antes de RECONCILIAR, faça uma pausa e pergunte:

“Revisão de modelo único concluída. Deseja uma segunda opinião comparativa entre modelos? Opções: Gemini CLI, Codex CLI, revisão externa manual (você cola o texto em outro lugar) ou pular.”

Essa pergunta é obrigatória em todo ciclo interativo de dúvidas — mesmo em artefatos que pareçam ter baixo risco. O usuário — e não o agente — decide se o custo vale a pena. A função do agente é apresentar a opção.

Etapa 2: Se o usuário escolher uma CLI — verifique e, em seguida, execute

Verifique se a ferramenta está no PATH (gemini, codex).
Teste se ela funciona (gemini --version ou equivalente) antes de passar o prompt completo — um binário desatualizado ou com defeito pode passar no teste, mas falhar com uma entrada real.
Confirme a invocação exata com o usuário, incluindo flags obrigatórios, autenticação e variáveis de ambiente (por exemplo, chaves de API). As implementações variam; nunca presuma nada.
Passe APENAS o ARTIFATO + o CONTRATO + o prompt adversarial. Sem contexto de sessão, sem CLAIM.
Preste atenção ao escape do shell. Se o artefato contiver aspas, $(...) ou crases, prefira stdin (echo … | gemini) ou um heredoc em vez de -p "…". Em caso de dúvida, peça ao usuário para confirmar a invocação antes de executá-la.
Leve a saída para a Etapa 4 (RECONCILIAR).

Nunca interpola o artefato em um argumento entre aspas de shell. Prompts de código, markdown e revisão costumam conter backticks, $(...) e caracteres de aspas que podem truncar o prompt ou executar o shell incorporado. Escreva o prompt completo em um arquivo e encaminhe-o por meio de stdin.

Exemplos de formatos (verifique os sinalizadores com a ferramenta instalada — a sintaxe varia entre implementações e versões):

# Grave primeiro o prompt adversarial + ARTIFATO + CONTRATO em um arquivo temporário.
# Em seguida, encaminhe por stdin para que os metacaracteres do shell no artefato permaneçam inativos.

# Codex (a sandbox somente leitura impede que a CLI grave em sua área de trabalho):
codex exec --sandbox read-only -C  - < /tmp/doubt-prompt.md

# Gemini (o ‘--approval-mode plan’ é somente leitura; ‘-p ""’ aciona o modo não interativo
# e o prompt é lido da stdin):
gemini --approval-mode plan -p "" < /tmp/doubt-prompt.md

Uma sandbox somente leitura é o detalhe fundamental: um artefato de dúvida pode, por si só, conter instruções (injeção intencional ou acidental de prompt) que, de outra forma, a CLI entre modelos executaria em seu espaço de trabalho.

Etapa 3: Se a CLI estiver indisponível ou falhar

Destaque a falha explicitamente. Sugira: execute manualmente, tente uma ferramenta diferente ou pule essa etapa. Não recorra silenciosamente ao modo de modelo único — o usuário deve saber que a execução entre modelos não ocorreu.

Etapa 4: Se o usuário pular

Confirme a omissão na saída (“Prosseguindo apenas com os resultados do modelo único”) e continue para a RECONCILIAÇÃO. Pular essa etapa é aceitável; pular silenciosamente, não.

Contextos não interativos (CI, /loop, autonomous-loop, execuções agendadas):

A análise entre modelos é ignorada, e essa omissão deve ser anunciada na saída: “Análise entre modelos ignorada: contexto não interativo.”
Nunca invoque uma CLI externa sem autorização explícita do usuário — essa é uma propriedade de segurança fundamental.

O Cross-model aumenta o custo, a latência e a fragilidade da ferramenta. O agente apresenta a opção a cada ciclo; o usuário decide se esse artefato justifica sua utilização.

Etapa 4: RECONCILIAR — Incorporar as descobertas

O resultado do revisor são dados, não um veredicto. Você ainda é o orquestrador. Releia o texto do artefato à luz de cada descoberta antes de classificá-lo — simplesmente aprovar o revisor sem questionar é o mesmo erro que ignorá-lo.

Para cada constatação, classifique nesta ordem de prioridade (a primeira classe que corresponder prevalece):

Interpretação incorreta do contrato — o revisor sinalizou algo especificamente porque o CONTRATO que você forneceu estava pouco claro ou incompleto. Corrija o contrato primeiro e reclassifique no próximo ciclo.
Válido + passível de ação — problema real que exige uma alteração no artefato. Altere-o e repita o ciclo.
Compromisso válido — o problema é real, mas o custo da correção excede o custo de aceitá-lo. Documente o compromisso explicitamente para que o usuário o veja.
Ruído — o revisor sinalizou algo que, na verdade, está correto dentro de um contexto que ele não conhecia. Anote isso, siga em frente e pergunte-se: adicionar esse contexto ao contrato teria evitado a sinalização indevida?

Um revisor novo pode estar errado por falta de contexto. Não adie a decisão apenas porque ele é “novo”.

Etapa 5: PARE — Laço limitado, não recursão

Pare quando:

A próxima iteração retornar apenas resultados triviais ou já considerados, ou
3 ciclos forem concluídos (escale para o usuário, não tente um quarto sozinho), ou
O usuário disser explicitamente “lançar”

Se, após 3 ciclos, o revisor ainda levantar questões substanciais, o artefato pode não estar pronto. Leve isso ao conhecimento do usuário — três ciclos não resolvidos são informações sobre o artefato, não um motivo para continuar repetindo o ciclo.

Se 3 ciclos forem “obviamente insuficientes” porque o artefato é grande: o artefato é grande demais — volte à Etapa 2 e decomponha-o. Não aumente o limite.

Racionalizações comuns

Racionalização	Realidade
“Estou confiante, vou pular a etapa da dúvida”	A confiança tem pouca correlação com a precisão em problemas novos. Os momentos de certeza são exatamente aqueles em que os pontos cegos se escondem.
“Contratar um revisor é caro”	Depurar um commit incorreto em produção é mais caro. A verificação tem limites; o bug, não.
“O revisor vai ficar só procurando defeitos”	Só se não houver limites definidos. Restrinja a solicitação a “problemas que fariam com que isso falhasse de acordo com o contrato”.
“Vou deixar as dúvidas para o final com `/review`”	`O /review` é uma etapa final. A verificação orientada por dúvidas detecta rumos errados logo no início, quando a correção de rumo ainda é barata. Na hora do PR, já é tarde demais.
“Se eu questionar cada etapa, nunca vou lançar”	Essa técnica se aplica a decisões não triviais, não a cada tecla digitada. Releia “Quando NÃO usar”.
“Duas opiniões são sempre melhores do que uma”	Não quando a segunda tem menos contexto e gera ruído. Conciliar, não adiar.
“O revisor discordou, então eu estava errado”	O revisor não tem o seu contexto — a discordância é informação, não um veredicto. Releia o artefato, classifique e, então, decida.
“A análise entre modelos é sempre melhor”	A abordagem entre modelos detecta pontos cegos que um único modelo compartilha consigo mesmo, mas acrescenta custo e fragilidade à ferramenta. Ofereça-a a cada ciclo interativo de dúvida — o usuário decide se o artefato justifica isso. O papel do agente é apresentar a opção, não impedi-la.
“O usuário disse sim uma vez, então posso continuar invocando a CLI”	Cada invocação é uma autorização à parte. O artefato, o prompt e os parâmetros mudam entre as chamadas — reconfirme o comando exato com o usuário antes de cada execução.

Sinais de alerta

Iniciar um revisor com contexto novo para uma renomeação de uma linha ou alteração de formatação
Tratar a saída do revisor como definitiva sem reler o texto do artefato
Repetir o processo por mais de três ciclos sem escalar o problema para o usuário
Perguntar ao revisor “isso está bom?” em vez de “identifique problemas”
Ignorar dúvidas sob pressão de tempo em uma decisão de alto risco
Geração repetida de um contexto novo para um artefato inalterado (você obterá as mesmas conclusões; está apenas ganhando tempo)
Teatro da dúvida (sinal verificável): ao longo de dois ou mais ciclos em que o revisor apresentou resultados substanciais, nenhum resultado foi classificado como passível de ação. Você está validando, não duvidando. Pare e encaminhe para um nível superior.
Duvidar somente após o commit — isso é /review, não desenvolvimento orientado por dúvidas
Codificar diretamente uma chamada de CLI externa sem confirmar com o usuário se a ferramenta existe, está configurada e aceita exatamente essa sintaxe
Ignorar silenciosamente a verificação entre modelos em um ciclo interativo de dúvida. Mesmo quando não for recomendado, a opção deve estar visível. Ignorar está tudo bem; ignorar silenciosamente, não.
Recorrer silenciosamente a um plano alternativo quando uma CLI externa apresenta erro ou está ausente — exponha a falha e permita que o usuário redirecione
Remover o contrato da entrada do revisor
Encaminhar a ALEGAÇÃO ao revisor (tendência à concordância)

Interação com outras habilidades

revisão-de-código-e-qualidade / /revisão: complementar. /revisão é um veredicto pós-facto sobre o PR; a abordagem orientada pela dúvida ocorre durante o processo, a cada decisão. Use ambas.
desenvolvimento-orientado-pelo-código-fonte: o SDD verifica fatos sobre frameworks em relação à documentação oficial. A abordagem orientada pela dúvida verifica seu raciocínio sobre o artefato. O SDD verifica se a API existe; a abordagem orientada pela dúvida verifica se você a utilizou corretamente de acordo com o contrato.
desenvolvimento-orientado-por-testes: a etapa RED do TDD é a concretização da dúvida — um teste com falha é uma tentativa de refutação. Quando o TDD é aplicado, esse teste com falha é a etapa de dúvida para afirmações comportamentais.
depuração-e-recuperação-de-erros: quando o revisor identifica um modo de falha real, recorra à habilidade de depuração para localizar e corrigir.
Regras de orquestração do repositório (references/orchestration-patterns.md): essa habilidade orquestra a partir da sessão principal. Uma persona chamando outra persona é o antipadrão B — veja “Restrições de carregamento” acima.

Verificação

Após aplicar o desenvolvimento orientado pela dúvida:

Cada decisão não trivial (conforme a definição acima) foi explicitamente denominada como uma AFIRMAÇÃO antes de ser validada
Pelo menos uma revisão em contexto novo por artefato não trivial (um teste com falha produzido pela etapa RED do TDD satisfaz esse requisito para reivindicações comportamentais, conforme Interação com Outras Habilidades)
O revisor recebeu o ARTIFATO + o CONTRATO — NÃO a ALEGAÇÃO, NÃO o seu raciocínio
A orientação do revisor era adversária (“encontre problemas”), não validativa (“isso está bom?”)
As constatações foram classificadas em relação ao texto do artefato (não foram simplesmente aprovadas sem análise) usando a seguinte prioridade: interpretação incorreta do contrato / ação necessária / compromisso / ruído
Uma condição de parada foi atendida (conclusões triviais, 3 ciclos ou anulação pelo usuário)
No modo interativo, a análise entre modelos foi explicitamente oferecida ao usuário (independentemente da importância do artefato) e a resposta foi reconhecida na saída
No modo não interativo, a análise entre modelos foi ignorada e o fato de ter sido ignorada foi anunciado
Qualquer invocação externa da CLI foi precedida por uma verificação do PATH, um teste de binário funcional, confirmação da sintaxe com o usuário e autorização explícita para execução

Ver no GitHub

---
name: doubt-driven-development
description: Subjects every non-trivial decision to a fresh-context adversarial review before it stands, prioritizing correctness over speed for high-stakes or unfamiliar code.
---

# Doubt-Driven Development

## 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 `/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.

## 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 is designed for the **main-session orchestrator**, where Step 3 (DOUBT, detailed below) can spawn a fresh-context reviewer.

- **Do NOT add this skill to a persona's `skills:` frontmatter.** A persona that follows Step 3 would spawn another persona — the orchestration anti-pattern explicitly forbidden by `references/orchestration-patterns.md` ("personas do not invoke other personas").
- **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: <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.

In Claude Code, the role-based reviewers in `agents/` start with isolated context by design and are usable here — see `agents/` for the roster and per-domain match.

**The adversarial prompt above takes precedence over the persona's default response shape.** Personas like `code-reviewer` are written to produce balanced verdicts with both strengths and weaknesses; doubt-driven needs issues-only output. Paste the adversarial prompt verbatim into the invocation so it overrides the persona's default. If a persona's response shape can't be overridden cleanly, fall back to a generic subagent with the adversarial prompt.

#### 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):

```bash
# 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 <repo-path> - < /tmp/doubt-prompt.md

# Gemini ('--approval-mode plan' is read-only; '-p ""' triggers non-interactive
# mode and the prompt is read from stdin):
gemini --approval-mode plan -p "" < /tmp/doubt-prompt.md
```

A read-only sandbox is the load-bearing detail: a doubt artifact may itself contain instructions (intentional or accidental prompt injection) that the cross-model CLI would otherwise execute against your workspace.

**Step 3: If the CLI is unavailable or fails**

Surface the failure explicitly. Offer: run it manually, try a different tool, or skip. Do not silently fall back to single-model — the user should know cross-model didn't happen.

**Step 4: If the user skips**

Acknowledge the skip in the output (*"Proceeding with single-model findings only"*) and continue to RECONCILE. Skipping is fine; silent skipping is not.

**Non-interactive contexts** (CI, `/loop`, autonomous-loop, scheduled runs):

- Cross-model is **skipped**, and the skip must be **announced** in the output: *"Cross-model skipped: non-interactive context."*
- **Never invoke an external CLI without explicit user authorization** — this is a load-bearing safety property.

Cross-model adds cost, latency, and tool fragility. The agent surfaces the choice every cycle; the user decides whether this artifact warrants it.

### 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):

1. **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.
2. **Valid + actionable** — real issue requiring a change to the artifact. Change it, re-loop.
3. **Valid trade-off** — issue is real but cost of fixing exceeds cost of accepting. Document the trade-off explicitly so the user sees it.
4. **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 `/review`" | `/review` is a final gate. Doubt-driven catches wrong directions early when course-correction is cheap. By PR time 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. |
| "Cross-model is always better" | Cross-model catches blind spots a single model shares with itself, but it adds cost and tool fragility. Offer it every interactive doubt cycle — the user decides whether the artifact warrants it. The agent's job is to surface the choice, not to gate it. |
| "User said yes once, so I can keep invoking the CLI" | Each invocation is its own authorization. The artifact, the prompt, and the flags change between calls — re-confirm the exact command with the user before every run. |

## 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 `/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-and-quality` / `/review`**: complementary. `/review` 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

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