doubt-driven-development

Doubt-driven development

Long sessions turn assumptions into facts without anyone noticing. This skill puts a reviewer in front of each non-trivial decision while it is still cheap to change, and points that reviewer at disproving it. It complements the merge gate: pr-gate judges the finished PR; doubt-driven checks the decisions on the way there.

Non-trivial means at least one of

• new or changed branching logic;
• a module, service or repository boundary is crossed;
• a property the compiler cannot check (thread safety, idempotence, ordering, "this is safe", "this scales");
• correctness depends on context a future reader will not see;
• the step is hard to undo (deploy, data migration, merge to main, public claim, money path).

Skip it for renames, formatting, moves, reading code, running tests, and clear instructions with obvious correctness.

The cycle

1. Claim. Write the decision and why it matters in two or three lines. If you cannot, you have a vibe; settle it first.

2. Extract. Isolate the smallest reviewable unit: the diff or function, or the proposal in three to five sentences plus its constraints. Strip your reasoning, keep the evidence, including any caller, guard or test that contradicts you. Over about 300 lines, split it.

3. Doubt. Send only the artifact and the contract, never the claim, with an adversarial prompt:

   Adversarial review. Find what is wrong. Assume the author is overconfident. Look for unstated assumptions, unhandled edge cases, hidden coupling or shared state, ways the contract breaks, estate conventions it violates, and failure under unexpected input. Do not validate or summarise. List issues, or state that you found none after a thorough check.

4. Reconcile. You stay the decision owner. Re-read the artifact against each finding and classify, first match wins: contract unclear (fix the contract), valid and actionable (change the artifact, loop), valid trade-off (document it where the user sees it), noise (note what context would have prevented it).

5. Stop. When findings turn trivial, after three cycles (then escalate to Frank), or when he says ship. If three cycles still produce substantive findings, the artifact is not ready; say so.