Doubt-Driven Development

Overview

The first workable idea gets defended; a better second idea never gets considered. This skill institutionalizes doubt at the moments it pays: before committing to a decision that is expensive to reverse, deliberately attack it — enumerate failure modes, steelman one alternative, and try to break the plan on paper where breaking is free. Doubt is a tool applied at decision points, not a mood applied to everything.

When to Use

• Architecture decisions: module boundaries, offline/sync model, state management approach (see android-architecture)
• Data migrations: Room schema changes, DataStore format changes — anything touching persisted user data (see android-data-persistence)
• Adopting or replacing a dependency the codebase will grow around
• Public or cross-team API contracts (see api-and-interface-design)
• minSdk/targetSdk bumps and platform-behavior migrations (see deprecation-and-migration)

Skip when: The decision is cheap to reverse (naming, private helpers, a screen's internal layout). Applying this to every choice is procrastination with extra steps.

Core Process

Step 1: Write the Decision Down First

1. One paragraph, falsifiable: what is being decided, what it optimizes for, what it deliberately gives up. If it can't be written down, it can't be attacked.

Decision: store sync state in a Room table per entity (not a global
DataStore flag). Optimizes for per-item retry and conflict tracking.
Gives up: simpler global "is syncing" UI state.

Step 2: Attack It

2. Enumerate concrete failure modes — Android-specific ones first:

- Process death mid-sync: is a row ever stuck in SYNCING forever?
- Migration: what happens to existing rows when the enum gains a value?
- Doze: WorkManager retry backoff vs. per-row retry counts — double retry?
- 10k tasks: does the per-row model create N WorkRequests?

3. Steelman exactly one alternative. Argue for it as its best advocate would — not a strawman you can dismiss:

Alternative: single sync journal table (append-only ops log).
Best case for it: trivially answers "what happened", replay-safe after
process death, one WorkRequest drains the log. Our chosen model has to
reinvent ordering; the journal gets it for free.

4. Try to kill your plan on paper: for each failure mode, either show why it can't happen, change the design, or accept it explicitly with a mitigation. "Probably fine" is not one of the three options.

Step 3: Decide and Record

5. Make the call and record it as an ADR (see documentation-and-adrs) — including the failure modes considered and why the steelmanned alternative lost. The doubt is only worth its cost if the reasoning survives for the next person.
6. Convert surviving risks into checks: each accepted failure mode becomes a test, an assertion, or a monitored metric (see observability-and-instrumentation) — doubt that doesn't turn into a check evaporates.

// Failure mode "row stuck in SYNCING after process death" → a test
@Test
fun `rows in SYNCING older than timeout are reset to PENDING on start`() { ... }

Common Rationalizations

Red Flags

• An ADR whose "alternatives considered" section is one dismissive sentence
• Room schema migration merged with no process-death or downgrade discussion
• New dependency adopted with no note on its abandonment/replacement cost
• Failure modes listed but none converted into tests or metrics
• The steelman reads like a strawman (weakest version of the alternative)
• Doubt applied to a trivial reversible choice while a migration ships unexamined

Verification

• Decision written down in falsifiable form (optimizes for / gives up)
• Concrete failure modes enumerated, including process death, migration, and background-limits cases where relevant
• Exactly one alternative steelmanned in writing
• Every failure mode: refuted, designed away, or accepted with mitigation
• ADR recorded with the losing alternative's best case (see documentation-and-adrs)
• Surviving risks exist as tests, assertions, or monitored metrics — point to them