ai-agents-debugging-playbook
Symptom-to-triage playbook for this repo's recurring failures. Blocked pushes, drift gate reds, plugin bump reds, coverage pin trips, hook exit 143, session NON_COMPLIANT. Maps each symptom to a first command, discriminating experiment, fix path, and trap. Use when you say `triage this failure`, `why is my push blocked`, `debug this CI red`. Do NOT use for incident history (use `ai-agents-failure-archaeology`) or measurement tools (use `ai-agents-diagnostics-toolkit`).
rjmurillo · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add rjmurillo/ai-agents --skill ai-agents-debugging-playbookAbout this skill
name: ai-agents-debugging-playbook
version: 1.0.0
license: MIT
description: Symptom-to-triage playbook for this repo's recurring failures. Blocked pushes, drift gate reds, plugin bump reds, coverage pin trips, hook exit 143, session NON_COMPLIANT. Maps each symptom to a first command, discriminating experiment, fix path, and trap. Use when you say triage this failure, why is my push blocked, debug this CI red. Do NOT use for incident history (use ai-agents-failure-archaeology) or measurement tools (use ai-agents-diagnostics-toolkit).
metadata:
routing:
role: conditional-adjunct
invoker: ai-agents-validation-and-qa
trigger: ai-agents-validation-and-qa points here to triage a red CI check or a blocked push
user-facing: false
ai-agents Debugging Playbook
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 failurewhy is my push blockeddebug this CI redwhat does this gate failure meanhook 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-validation-and-qa |
| The catalog of every env var, marker, and escape hatch | ai-agents-config-catalog |
| How the harness itself behaves (payload shapes, plugin roots) | agent-harness-reference |
| Fix a NON_COMPLIANT session log | Hand-edit against .agents/schemas/session-log.schema.json, re-run scripts/validate_session_json.py |
| Resolve merge conflicts | Agent: merge-resolver |
| Query agent JSONL event logs | observability |
Process
Phase 1: Match the symptom
Find your symptom in the master table. Run the first command exactly as written (from repo root). Do not guess at fixes before the discriminating experiment tells you which cause you have.
Before guessing at a symptom the table does not cover, search this repo's memory corpus and ADRs first (.claude/skills/programming-advisor/references/search-before-building.md, "diagnosing a failure" trigger). It covers CI, git, and PR-gate quirks densely, so the cause is often already written down; re-deriving it is the expensive miss.
Local blocks (a hook stopped you)
| Symptom | First command | Discriminating experiment | Fix path | Trap |
|---|---|---|---|---|
Push rejected by a guard, stderr shows EVENT={...} | Read the EVENT JSON on stderr; the guard field names which of .claude/hooks/PreToolUse/invoke_*_guard.py fired | Is outcome a block or fail_open? A block means the guard did its job; fail_open means guard infra broke | Fix the underlying violation, then re-push. No tier-classifier consumes this telemetry today; the guard-maturity skill that did was retired under ADR-084 (issue #5154) | Bypassing instead of fixing. SKIP_PREPUSH was abused 3x within an hour of creation and removed (retro 2026-02-08-session-1187-skip-prepush-abuse.md) |
ModuleNotFoundError: No module named 'yaml' running a skill script | Re-run with uv run python <script> | Does uv run python -c "import yaml" succeed while python3 -c "import yaml" fails? Then it is interpreter resolution, not a missing dep | Always use uv run python for .claude/skills/*/scripts/; they import github_core which needs PyYAML from the project venv | Bare pip install fails under PEP 668 on this machine. Everything goes through uv |
markdown-autofix/markdown-check blocks the commit, or lint "fixed" files you never touched | git status to see the blast radius | Did you run markdownlint --fix '**/*.md' (unscoped)? | Revert unrelated files; lint ONLY changed files. The Lefthook job itself is scoped to staged .md files (lefthook.yml markdown-autofix/markdown-check, glob: "**/*.md" against {staged_files}) | PR #908: an unscoped markdownlint --fix **/*.md reformatted memory files repo-wide; the PR hit 59 commits / 95 files (retro 2026-01-15-pr-908-comprehensive-retrospective.md). The PreToolUse markdownlint guard that originally enforced this was removed under ADR-084 (issue #5154); the same scoping now lives in the two Lefthook jobs named above |
| Bot review thread flags an em-dash or en-dash | grep -rnP '[\x{2013}\x{2014}]' <your changed files> | Is the hit under tests/hooks/fixtures/? That prefix is exempt | Replace with comma, colon, parentheses, or hyphen (.claude/rules/universal.md MUST NOT 4; validator scripts/validation/checks_dash.py) | Each dash costs one or more bot threads per PR. Fix all occurrences, not just the flagged one |