SKILL GUIDE
Debugging Code
Reproduce a defect, test focused hypotheses, and fix its root cause. Verify the original failure and add regression coverage where practical.
debugging-codeOn this page
When to use it
- A test fails, an exception occurs, or behavior differs from expectations.
- You are investigating a regression, integration failure, or performance anomaly.
- The cause is unclear, intermittent, or specific to an environment.
Workflow
Define and reproduce the failure
Record expected and actual behavior, relevant input, and the narrowest repeatable test, request, command, or interaction.
Collect relevant evidence
Inspect the failing path, logs, assertions, runtime wiring, and configuration. Keep observations separate from hypotheses.
Test focused hypotheses
Change one meaningful variable at a time and choose small tests that distinguish plausible causes.
Fix the responsible boundary
Explain the cause-to-failure chain and make the smallest correction that preserves contracts and unrelated behavior.
Verify the original failure
Add regression coverage when practical, rerun the reproduction and nearby checks, and remove temporary diagnostics.
Practical use cases and prompts
Investigating a failing test
A test that previously passed now fails, and the cause is not established.
Use debugging-code. Investigate the failing test provided in this task. Reproduce it before editing, trace the failing execution path, and test focused hypotheses. Fix the root cause without weakening assertions, add regression coverage if needed, and rerun the original failure.Expected output: Reproduction evidence, a justified root cause, a minimal fix, and verification results.
Diagnose an API exception
An endpoint crashes for a specific input or stored-data condition.
Use debugging-code. Reproduce the reported API exception with the smallest input. Trace the request and data to the responsible boundary, distinguish the crash location from the root cause, and verify a minimal fix with a regression test.Expected output: An input-to-failure explanation and a verified correction that preserves the endpoint contract.
Investigate an intermittent regression
A failure appears only under a particular timing or environment.
Use debugging-code. Compare the working and failing environments for the intermittent behavior described here. Control relevant inputs, state, and timing; record hypotheses and distinguishing tests. Report reproduction limits and avoid speculative retries or timeout changes.Expected output: Controlled evidence, tested hypotheses, and an honest account of what can and cannot be reproduced.
Expected outputs
- A precise failure description and root-cause explanation supported by evidence.
- A scoped fix and an automated regression test when practical.
- Results for the original reproduction and relevant checks, including any remaining uncertainty.
Requirements and optional helpers
- A coding agent with Agent Skills support and permission to read the target repository.
- Shell access is recommended for reproductions, tests, and repository inspection.
- Provide the failing test, error, logs, or reproduction steps when available. If reproduction cannot be established, the report must say so.
Debug context collector
Optional collect-debug-context.mjs needs Node.js 18+ and accepts --root. It gathers objective project and repository context; failed or unavailable runtime probes return null. It does not diagnose the root cause.
Installation
Open a terminal in your target project and install this package. Project scope is the default; choose your agent when prompted.
npx skills add https://github.com/GiovanniL30/ai-skills/tree/main/skills --skill debugging-codeRefresh your agent session, confirm the skill is available, and give it a concrete task. Keep the whole package, including references and helpers.
Choose an agent and installation scope →Source and focused references
This guide summarizes the original package. Read its complete workflow and supporting references on GitHub.
Read the original SKILL.md ↗