ai-agents-failure-archaeology
The chronicle of this repo's settled battles. Maps each major incident to symptom, root cause, evidence path, and the artifact that fixed it, so nobody re-fights a decided question. Use when you say `has this failed before`, `why does this rule exist`, `failure archaeology`, `what happened with issue 2205`. Do NOT use for triaging a live failure (use `ai-agents-debugging-playbook`) or for extracting learnings from the current session (use `retrospective`).
rjmurillo · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add rjmurillo/ai-agents --skill ai-agents-failure-archaeology技能说明
name: ai-agents-failure-archaeology
description: The chronicle of this repo's settled battles. Maps each major incident to symptom, root cause, evidence path, and the artifact that fixed it, so nobody re-fights a decided question. Use when you say has this failed before, why does this rule exist, failure archaeology, what happened with issue 2205. Do NOT use for triaging a live failure (use ai-agents-debugging-playbook) or for extracting learnings from the current session (use retrospective).
version: 1.0.0
license: MIT
metadata:
routing:
role: conditional-adjunct
invoker: ai-agents-change-control
trigger: ai-agents-change-control points here for the deep history behind a settled incident
user-facing: false
ai-agents Failure Archaeology
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 .project-toolkit/retrospective/ and
.serena/memories/; the provenance table below carries the commands that count
both. 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 beforewhy does this rule existfailure archaeologywhat happened with issue 2205are 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 retro (in .project-toolkit/retrospective/) | Status |
|---|---|---|---|
| #2205 customer wedge | Bare ./hooks/... paths + Copilot CLI running hooks from the USER's cwd wedged every plugin customer for 33 days (v0.3.0 to v0.5.6); recovery was uninstall. First fix added 3 new defects; session 1873 fixed it with an empirical probe of Copilot CLI 1.0.57 | 2026-06-02-pr-2205-customer-wedge-incident.md | Settled; gated by scripts/validation/validate_hook_anchoring.py + tests/build_scripts/test_generate_hooks_runtime_contract.py |
| #2290 payload casing | Copilot CLI payload field names depend on event-key casing: camelCase sends toolName/toolArgs (toolArgs is a JSON string); PascalCase sends tool_name/tool_input. FM-11 second occurrence | 2026-06-02-issue-2290-copilot-hook-payload-format.md | Settled (PascalCase + dual-format shim); exit-143 timeout flagged P0, unresolved in that retro |
| #1887 iteration paradox | Guard framework built to cut review iteration took 69 commits / 254 conversations; Phase-6 audit showed the guards would have prevented 0 of its own 35 fix commits | 2026-05-05-pr-1887-iteration-paradox.md | Settled diagnosis: bot concurrency (60-70% overlap) + reviewThreads(first: 100) pagination cliff drove the cost |
| #1989 recursive failure | The mitigation PR reproduced the failure modes it mitigated; M1 built on a false premise (pagination already existed), M4 threshold 6 vs repo max 4 could never fire, M5 guard never run on its own branch | 2026-05-10-pr-1989-recursive-failure.md | Settled: 3 process rules (self-application, memory contradiction check, threshold calibration) |
| Session 1187 trust incident | SKIP_PREPUSH abused 3x within hours of creation; git checkout --ours corrupted main's session log; user: "You can't be trusted in the least bit." | 2026-02-08-session-1187-skip-prepush-abuse.md | Settled: SKIP_PREPUSH removed; session-merge rule binding |
| PR #908 scope explosion | 59 commits / 95 files; unscoped markdownlint --fix reformatted 53 unrelated memory files into the diff | 2026-01-15-pr-908-comprehensive-retrospective.md | Settled: birthed scripts/validation/pre_pr.py, commit caps, scoped lint |
| 2025-12-15 drift inversion | Agent edited the SOURCE (Claude agents) to match the GENERATED (templates); commit ddb76e0 reverted | 2025-12-15-drift-detection-disaster.md | Settled: drift shows difference, never direction; always ask which side is canonical |
| PR #1965 silent defaults | Verdict parser defaulted a missing VERDICT: line to non-blocking; 3 fix rounds because parser, exit-code translator, and workflow gate each had their own silent default | 2026-05-10-pr-1965-review-axes-convergence.md + FM-10 in FAILURE-MODES.md | Settled: "there is no neutral default for a missing signal" |
Also settled, no dedicated retro: PR #1942 stale plugin cache. It deleted the
deprecated workflow skill from .claude/skills/ but left plugin.json at
0.3.0; installed plugin caches key off the version, so installs kept shipping
the dead /workflow until the gap was hand-caught in PR #2114. Record and gate:
build/scripts/validate_plugin_version_bump.py docstring (lines 1-20).
Phase 2: Check the Settled Battles List
These are decided. Re-opening one requires new evidence plus the change-control
path in ai-agents-change-control, not a fresh opinion.
| Settled position | Verdict | Evidence |
|---|---|---|
| Launcher-level fail-open wrapper | REJECTED. Exiting 0 on a broken launcher silently disables the hook; prevent the bad launcher at generation time, fail closed and loud if one e |