ai-agents-failure-archaeology

# ai-agents Failure Archaeology <!-- vendor-portability: contributor-facing knowledge pack for the rjmurillo/ai-agents repo itself; intentionally references upstream paths (.agents/, .claude/, scripts/, build/) because its audience is repo contributors, not plugin consumers (issue #2050) --> This repo's rules are fossils of incidents. Before you challenge a gate, weaken a guard, or propose a "simpler" approach, check whether that battle was already fought and what it cost. The canon lives in `.agents/retrospective/` (95 files as of 2026-07-02) and `.serena/memories/` (122 files). Full local history is present (`git rev-list --count HEAD` = ~1471 as of 2026-07-03), but retro-cited short SHAs (e.g. `ddb76e0`, `01e76615a`) may not resolve locally, so archaeology still routes through the retros and memories as primary sources, not `git log`. Depth per incident lives in `references/incidents.md` (read it when a table row below is not enough). This file is the index and the verdict list. ## Triggers - `has this failed before` - `why does this rule exist` - `failure archaeology` - `what happened with issue 2205` - `are we re-litigating a settled decision` ## Process ### Phase 1: Check the Major Incidents Table If your question touches hooks, generators, drift, review iteration, escape hatches, or silent defaults, it is probably one of these eight. Read the matching subsection in `references/incidents.md` before doing anything else. | Incident | One-line summary | Primary ret...