Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

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

About 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 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 wantUse 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 testai-agents-validation-and-qa
The catalog of every env var, marker, and escape hatchai-agents-config-catalog
How the harness itself behaves (payload shapes, plugin roots)agent-harness-reference
Fix a NON_COMPLIANT session logHand-edit against .agents/schemas/session-log.schema.json, re-run scripts/validate_session_json.py
Resolve merge conflictsAgent: merge-resolver
Query agent JSONL event logsobservability

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)

SymptomFirst commandDiscriminating experimentFix pathTrap
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 firedIs outcome a block or fail_open? A block means the guard did its job; fail_open means guard infra brokeFix 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 scriptRe-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 depAlways use uv run python for .claude/skills/*/scripts/; they import github_core which needs PyYAML from the project venvBare 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 touchedgit status to see the blast radiusDid 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-dashgrep -rnP '[\x{2013}\x{2014}]' <your changed files>Is the hit under tests/hooks/fixtures/? That prefix is exemptReplace 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

CI reds (a gate failed on the PR)

Read the complete source ↗