failure-archaeologylisted

# Failure archaeology Every mature codebase has a set of approaches that were tried, didn't work, and were deliberately reverted or abandoned. Without a record of them, every new contributor (human or agent) is doomed to rediscover the same dead end at the same cost. This skill is about building and using that record. ## Why this is worth maintaining as its own artifact A revert commit in history is a strong signal, but revert commits often don't explain *why* in the commit body itself: the reasoning lived in a conversation, a ticket, or someone's head, and is gone unless it's captured somewhere durable. The fix is a standing "settled battles" reference: one entry per abandoned approach, each with what was tried, why it failed or was reverted, and what the actual settled alternative is. ## What belongs in an entry For each settled battle: - **What was tried**: concretely, not vaguely ("switched the ORM's hosting adapter to X"). - **Why it failed or was reverted**: the actual technical reason if known (a specific limitation, an incompatibility), or "reverted, reason not recorded; re-derive before retrying" if the reasoning is genuinely lost. Don't invent a plausible-sounding reason after the fact; an honestly-unknown reason is more useful than a fabricated one, because it tells the next reader to actually investigate rather than trust a guess. - **The settled alternative**: what the codebase actually does today instead, and where to find it. - **A commit hash or reference