debugging-specialist
/debugging-specialist
Diagnoses defects with a hypothesis-driven method: reproduce, isolate, form falsifiable hypotheses, test them with evidence, fix the root cause with a failing test first. Use for bugs, failing tests and unexpected behaviour.
- Author
- arijeetganguli ↗
- Repository
- ai-kaarkhana ↗
- Licence
- MIT
- Last repository change
- 02.11.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 02.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Diagnoses defects with a hypothesis-driven method: reproduce, isolate, form falsifiable hypotheses, test them with evidence, fix the root cause with a failing test first. Use for bugs, failing tests and unexpected behaviour.
Original author description
Diagnoses defects with a hypothesis-driven method: reproduce, isolate, form falsifiable hypotheses, test them with evidence, fix the root cause with a failing test first. Use for bugs, failing tests and unexpected behaviour.
How it works
- Purpose
- When to invoke
- Required input
- Execution instructions
- Expected output
- Validation checklist
- Example usage
- Sample prompts
- Common mistakes
- Related skills
SKILL.md preview
--- name: debugging-specialist description: "Diagnoses defects with a hypothesis-driven method: reproduce, isolate, form falsifiable hypotheses, test them with evidence, fix the root cause with a failing test first. Use for bugs, failing tests and unexpected behaviour." license: MIT metadata: activity: debugging difficulty: intermediate frameworks: "any" version: "1.0" --- # Debugging Specialist ## Purpose Replace trial-and-error edits with a disciplined loop so that the root cause is found, the fix is minimal and the defect cannot silently return. ## When to invoke - A bug report, failing test, stack trace or incorrect output needs diagnosis. - An AI assistant has proposed a fix without explaining the cause. - A fix "worked" but nobody knows why. ## Required input - Observed behaviour versus expected behaviour. - Steps, inputs, environment and version that reproduce it, or logs and stack trace. - Relevant code and recent changes. If a required input is missing, ask for it. Do not guess. ## Execution instructions 1. Write the symptom precisely: input, actual output, expected output, environment. 2. Reproduce it reliably, ideally as an automated failing test. If you cannot reproduce it, say so and list what evidence is missing. 3. List two to four hypotheses, each with a prediction that would prove it false. 4. Test hypotheses with the cheapest evidence first: read the code path, add temporary logging, inspect data, bisect commits, minimise the input. 5. Identify the root cause and distinguish it from the symptom and the trigger. 6. Write or finalise the failing test, make the smallest fix, run the full relevant suite. 7. Check for the same defect pattern elsewhere and add regression tests for neighbouring cases. 8. Remove temporary instrumentation and record the cause in the PR. ## Expected output - Symptom statement and reproduction. - Hypotheses with predictions and the evidence that decided each. - Root cause explanation. - Failing test, fix and test run results. - Search for similar defects. ## Validation checklist - [ ] The defect was reproduced, or the lack of reproduction is stated. - [ ] The root cause is explained, not just the changed line. - [ ] A test failed before the fix and passes after. - [ ] Hypotheses were falsifiable and evidence is recorded. - [ ] Temporary debugging code was removed. ## Example usage Input: > Intermittent `NullPointerException` in `InvoiceService.total` after deploy. Illustrative output (abridged, hand-written for this guide, not captured from a model run): ```text H1: `customer.region` is null for imported customers. Prediction: failing rows have null region. Evidence: query shows 312 imported rows with null region -> confirmed. Root cause: import job skips region; `total()` assumes non-null. Fix: validate at import and handle absent region explicitly in `total()`. Tests for both. Search for other uses of `region`: 2 found. ``` ## Sample prompts ```text Act as the Debugging Specialist. Symptom: [SYMPTOM]. Evidence: [LOGS/STACK TRACE]. Propose 2-4 hypotheses with a prediction that would falsify each, rank them by cheapest evidence, and tell me what to run or inspect first. Do not propose a fix until the root cause is confirmed. Code: [CODE] ``` ## Common mistakes - Changing code until the symptom disappears. - Accepting an AI-suggested null check that hides the underlying data problem. - Fixing without a failing test. - Leaving debug output or feature toggles in place. ## Related skills - [Regression Analyst](../regression-analyst/SKILL.md) - [TDD Engineer](../tdd-engineer/SKILL.md) - [Performance Analyst](../performance-analyst/SKILL.md) ## Related resources Handbook: - [Chapter 4: AI Assisted Development](../../handbook/04_ai_assisted_development/README.md) - [Chapter 11: Engineering Delivery and Operations](../../handbook/11_delivery_and_operations/README.md) Prompts: - [Hypothesis Driven Debugging](../../prompts/debugging/hypothesis-driven-debugging.md) - [Stack Trace Analysis](../../prompts/debugging/stack-trace-analysis.md) - [Root Cause Analysis](../../prompts/debugging/root-cause-analysis.md) - [Log Analysis](../../prompts/debugging/log-analysis.md) Workflows: - [Fix a defect](../../workflows/02_defect_fix.md) - [Handle a production incident](../../workflows/08_production_incident.md) Examples: - [examples/broken_code_lab/README.md](../../examples/broken_code_lab/README.md)
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · arijeetganguli/ai-kaarkhana | 100 | MIT |
| arijeetganguli/ai-kaarkhana | 100 | MIT |
Database snapshot: 13.11.2026 · package version a3d5d18b839c (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90debugging-root-cause
Use to reproduce failures, gather evidence, test hypotheses, isolate faults across system boundaries, and identify evidence-supported root causes. - 100debug
Diagnose a failing test, build, crash, regression, or unexpected behavior without editing source. Reproduce the symptom, test hypotheses, identify the supported root cause, and hand off a repair. Use for /debug, root-cause investigation, or questions about why something is broken. - 100systematic-debugging
Find the root cause before changing anything: read the error, reproduce, gather evidence, rank hypotheses, test one at a time, then fix at the source with a failing test first. Use for any bug, test failure, build failure, flaky or intermittent behavior, performance regression… - 100systematic-debugging
Finds the root cause of bugs with a disciplined reproduce, isolate, hypothesize, verify loop (including git bisect) instead of guess-and-patch, then locks the fix in with a regression test. Use when the user reports a bug, crash, failing test, flaky behavior, regression, or "it works on my machine". - 100systematic-debugging
Find root causes with evidence, not guesses: reproduce, isolate, hypothesize, test, fix, prevent. Use for bugs, flaky tests, regressions, crashes, wrong output, or 'it works on my machine'. - 100debugging
Finds the root cause of an error, failing test, or wrong behaviour, then fixes it with proof. Use when something is broken, a test fails, or output is unexpected.