ai-agents-debugging-playbooksolid

# ai-agents Debugging Playbook <!-- 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) --> Symptom-first triage for this repository's known failure modes. Every row below was earned by a real incident; the retro path is cited so you can read the full story. The playbook answers one question: given this symptom, what is the FIRST command to run, what experiment discriminates between causes, and what trap has already cost someone real time here? Vocabulary used once: a "guard" is a PreToolUse or pre-push hook that can block an action (exit 2 blocks, exit 0 allows). A "drift gate" is a CI check that fails when a generated tree no longer matches its canonical source. A "discriminating experiment" is one cheap action whose outcome splits the hypothesis space in two. ## Triggers - `triage this failure` - `why is my push blocked` - `debug this CI red` - `what does this gate failure mean` - `hook blocked my tool call` ## When NOT To Use This Skill | You want | Use instead | |----------|-------------| | The full history of an incident (root cause, evidence, what changed) | `ai-agents-failure-archaeology` | | To measure something (budgets, telemetry, drift as a number) | `ai-agents-diagnostics-toolkit` | | Evidence standards, test layout, how to write the missing test | `ai-agents-v