| name | research-failures-first |
| description | Before building anything non-trivial, research real-world failure modes from production post-mortems and issue trackers and produce a committed symptom→cause→fix→URL map, instead of donating your own debugging time or asking the model to hallucinate what could break. |
Research Failures First
What this is
A protocol that inverts the default workflow. Instead of searching for the happy path
("how to use X") and discovering its sharp edges by stepping on them, you hunt for
other people's already-debugged pain first and turn it into a committed reference: a
symptom → root-cause → fix → source-URL table for the specific thing you're about to
build. Most non-trivial implementation pain is somebody else's solved problem. Finding
their bruises before donating your own runs about 5× return on the time spent looking.
Why it beats the default
The default happy-path search optimizes for "make it work once" and hides every failure at
the boundaries: empty input, the second concurrent writer, the migration that runs twice,
the auth token that expires mid-request. Those are exactly what people who hit production
already documented. You want their post-mortems, not a tutorial.
When it gates implementation
Mandatory before writing code for:
- Native dependency adoption: any new package (npm/pip/cargo/brew/gem/go) not already in the repo.
- Schema migrations: DB or content, especially anything backfilling or irreversible.
- Auth flow changes: login, tokens, sessions, OAuth, permissions.
- Sync protocol work: OTA, websockets, event sourcing, conflict resolution.
- Store / marketplace submission gates: App Store, Play Store, extension marketplaces.
- Cross-cutting refactors: more than ~5 files, or multi-module.
- Framework upgrades that change the public API surface.
