Research Failures First

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.

NOT required for: typo and copy fixes, comment changes, single-file bug fixes inside familiar code, or test additions to an existing suite.

The channel ranking

Empirically ranked by unique-find rate: how often a channel surfaces a failure no other channel did (from a controlled run of parallel research agents, each locked to one channel on identical topics):

| Channel | What it is | Unique-find rate | Run? | |---|---|---|---| | Production case studies: engineering-blog post-mortems, incident write-ups | 78% | always | | Issue tracker: the project's OWN GitHub/GitLab issues, open + closed | 47% | always | | Forums: Reddit, Hacker News, Stack Overflow | 29% | optional supplement, if the issue tracker returns .md in your durable notes store. Subsequent work cites specific row numbers from it. The full fill-in-the-blank format (frontmatter, TL;DR, failure-mode table, pre-flight checklist) is in [reference/failure-map-template.md`](./reference/failure-map-template.md).

Minimum ~10 unique entries. Below 10 usually means the channels weren't queried hard enough. Expand the search or add the forums channel before declaring the map done.

The hard rule: cite sources, never hallucinate failures

Never ask the model what could go wrong. Foundation models confidently invent failure modes that don't exist for your specific version, and omit the real ones. Every row needs a resolving source URL: a real post-mortem, issue, or thread you can open. No URL, no row. The map is only as trustworthy as its weakest citation.

Optional parallel orchestration

When you have sub-agents, run it as a sprint and keep raw research out of the orchestrator's context:

1. Pre-log a PENDING row per channel before spawning, so a dropped agent is visible.
2. Spawn the two top channels in parallel (single dispatch, isolated worktrees if you

have them). Each writes to research/-channel-.md.

1. Cap each return summary at a couple hundred words: the deliverable is on disk.
2. Verify by file, not by receipt. Open the file the agent claims it wrote. Missing

file or still-PENDING row → re-spawn that one channel (max one retry).

1. Merge both files into canonical research/.md. Dedupe overlapping rows,

citing both source URLs in the merged entry.

Anti-patterns

• Skipping research because "this is quick." The cheap-research → expensive-rebuild loop is exactly what this kills (~5× ROI).
• Asking the model what breaks instead of searching. Hallucinated, version-wrong, no URL.
• Running the generic "gotchas" search alone. 15% unique. Spend the time on the top two.
• Treating the map as ephemeral. It's committed reference; later work cites its rows.
• Letting a receipt stand in for a file. No map on disk = the protocol didn't run.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ariaxhan
• Source: ariaxhan/the-agent-library
• License: MIT

Install and usage instructions live in the source repository linked above.