跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

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 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.

IncidentOne-line summaryPrimary retro (in .project-toolkit/retrospective/)Status
#2205 customer wedgeBare ./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.572026-06-02-pr-2205-customer-wedge-incident.mdSettled; gated by scripts/validation/validate_hook_anchoring.py + tests/build_scripts/test_generate_hooks_runtime_contract.py
#2290 payload casingCopilot 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 occurrence2026-06-02-issue-2290-copilot-hook-payload-format.mdSettled (PascalCase + dual-format shim); exit-143 timeout flagged P0, unresolved in that retro
#1887 iteration paradoxGuard 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 commits2026-05-05-pr-1887-iteration-paradox.mdSettled diagnosis: bot concurrency (60-70% overlap) + reviewThreads(first: 100) pagination cliff drove the cost
#1989 recursive failureThe 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 branch2026-05-10-pr-1989-recursive-failure.mdSettled: 3 process rules (self-application, memory contradiction check, threshold calibration)
Session 1187 trust incidentSKIP_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.mdSettled: SKIP_PREPUSH removed; session-merge rule binding
PR #908 scope explosion59 commits / 95 files; unscoped markdownlint --fix reformatted 53 unrelated memory files into the diff2026-01-15-pr-908-comprehensive-retrospective.mdSettled: birthed scripts/validation/pre_pr.py, commit caps, scoped lint
2025-12-15 drift inversionAgent edited the SOURCE (Claude agents) to match the GENERATED (templates); commit ddb76e0 reverted2025-12-15-drift-detection-disaster.mdSettled: drift shows difference, never direction; always ask which side is canonical
PR #1965 silent defaultsVerdict 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 default2026-05-10-pr-1965-review-axes-convergence.md + FM-10 in FAILURE-MODES.mdSettled: "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 positionVerdictEvidence
Launcher-level fail-open wrapperREJECTED. Exiting 0 on a broken launcher silently disables the hook; prevent the bad launcher at generation time, fail closed and loud if one e
阅读完整来源 ↗