ai-agents-debugging-playbooklisted

# ai-agents Debugging Playbook <!-- vendor-portability: contributor-facing knowledge pack for the rjmurillo/ai-agents repo itself; intentionally references upstream paths (.agents/governance/, .agents/retrospective/, .agents/schemas/session-log.schema.json, .claude/lib/, .github/, build/generate_agents.py, build/scripts/, scripts/ci/, scripts/sync_plugin_lib.py, scripts/validate_session_json.py, scripts/validation/, templates/agents/) 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,