systematic-debugging
A four-phase debugging process focused on reproduction and evidence-gathering before applying any code fixes.
Install
mkdir -p .claude/skills/systematic-debugging-communitiesuk && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/15019" && unzip -o skill.zip -d .claude/skills/systematic-debugging-communitiesuk && rm skill.zipInstalls to .claude/skills/systematic-debugging-communitiesuk
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Use when encountering any bug, test failure, or unexpected behavior. Requires root cause investigation before proposing fixes.Key capabilities
- →Reproduce the failure with a specific command
- →Record exact output including error message and stack trace
- →Gather evidence from stack traces, logs, and project files
- →Form and test a hypothesis about the root cause
- →Make a minimal fix and verify it with tests
How it works
This skill guides through four phases: reproducing the issue, gathering evidence, forming and testing a hypothesis, and finally fixing and verifying the solution.
Inputs & outputs
When to use systematic-debugging
- →Diagnose failing unit tests
- →Investigate unexpected runtime errors
- →Debug build pipeline failures
- →Analyze integration issues
About this skill
Systematic Debugging
Core principle: Find root cause before attempting fixes. Symptom fixes are failure.
When to Use
Use for ANY technical issue: test failures, bugs, unexpected behaviour, build failures, integration issues.
Use ESPECIALLY when:
- "Just one quick fix" seems obvious
- You have already tried multiple fixes
- Previous fix did not work
The Four Phases
Complete each phase before proceeding to the next.
Phase 1: Reproduce and Observe
-
Reproduce the failure with a specific command:
PowerShell:
.\gradlew test --tests "uk.gov.communities.prsdb.webapp.FailingTest" --console=plainBash:
./gradlew test --tests "uk.gov.communities.prsdb.webapp.FailingTest" --console=plain -
Record exact output: error message, stack trace, exit code
-
Identify the failing assertion: what was expected vs actual?
Phase 2: Gather Evidence
Use these project-specific evidence sources:
| Source | Tool | What It Shows |
|---|---|---|
| Stack trace | Test output | Call chain to failure point |
| Spring logs | JetBrains console / test output | Request handling, bean wiring |
| Controller mapping | jetbrains-search_symbol for handler method | URL routing |
| Service logic | jetbrains-read_file with line ranges | Business logic flow |
| Thymeleaf rendering | Template file + model attributes | View layer issues |
| Journey step flow | Step config + StepId enum | Navigation/routing logic |
| Form validation | @ValidatedBy annotations + validator classes | Validation chain |
| Database state | Migration files + entity definitions | Schema/data issues |
| Integration test page objects | src/test/.../integration/pageObjects/ | Expected page structure |
| JetBrains inspections | jetbrains-get_file_problems | Compile errors, type issues |
Do NOT skip this phase. Gather at least 3 pieces of evidence before forming a hypothesis.
Phase 3: Form and Test Hypothesis
- State the hypothesis explicitly: "The failure occurs because..."
- Identify what evidence supports it
- Identify what evidence would disprove it
- Test the hypothesis with a targeted check (read code, add logging, evaluate expression in debugger)
If hypothesis is wrong: return to Phase 2 with new evidence.
Phase 4: Fix and Verify
-
Make the minimal fix that addresses root cause
-
Run the original failing test — must now pass
-
Run related tests to check for regressions:
PowerShell:
.\gradlew test --tests "uk.gov.communities.prsdb.webapp.related.*" --console=plainBash:
./gradlew test --tests "uk.gov.communities.prsdb.webapp.related.*" --console=plain -
If fixing a bug: add a regression test that would have caught it
Using the Debugger
For complex issues, use JetBrains MCP debugging tools:
- Set breakpoint:
jetbrains-xdebug_set_breakpoint - Start debug session:
jetbrains-xdebug_start_debugger_session - Wait for pause:
jetbrains-xdebug_control_session(WAIT_FOR_PAUSE) - Inspect variables:
jetbrains-xdebug_get_frame_values - Evaluate expressions:
jetbrains-xdebug_evaluate_expression - Step through:
jetbrains-xdebug_control_session(STEP_OVER / STEP_INTO)
Anti-Patterns
- Changing code without understanding why it failed
- Fixing the test instead of the code (unless the test was wrong)
- Adding try/catch to suppress errors
- "It works now" without understanding what changed
- Guessing and checking repeatedly
When not to use it
- →When changing code without understanding why it failed
- →When fixing the test instead of the code
- →When adding try/catch to suppress errors
Limitations
- →This skill requires root cause investigation before proposing fixes
- →This skill is for any bug, test failure, or unexpected behavior
- →This skill is not for changing code without understanding why it failed
How it compares
This skill enforces a systematic, evidence-based approach to debugging, prioritizing root cause identification over speculative fixes, unlike trial-and-error methods.
Compared to similar skills
systematic-debugging side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| systematic-debugging (this skill) | 0 | 2mo | Review | Intermediate |
| python-testing-patterns | 77 | 2mo | Review | Intermediate |
| chrome-devtools | 41 | 7mo | Review | Intermediate |
| bats | 9 | 7mo | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
python-testing-patterns
wshobson
Implement comprehensive testing strategies with pytest, fixtures, mocking, and test-driven development. Use when writing Python tests, setting up test suites, or implementing testing best practices.
chrome-devtools
mrgoonie
Browser automation, debugging, and performance analysis using Puppeteer CLI scripts. Use for automating browsers, taking screenshots, analyzing performance, monitoring network traffic, web scraping, form automation, and JavaScript debugging.
bats
OleksandrKucherenko
Bash Automated Testing System (BATS) for TDD-style testing of shell scripts. Use when: (1) Writing unit or integration tests for Bash scripts, (2) Testing CLI tools or shell functions, (3) Setting up test infrastructure with setup/teardown hooks, (4) Mocking external commands (curl, git, docker), (5) Generating JUnit reports for CI/CD, (6) Debugging test failures or flaky tests, (7) Implementing test-driven development for shell scripts.
browser-daemon
noiv
Persistent browser automation via Playwright daemon. Keep a browser window open and send it commands (navigate, execute JS, inspect console). Perfect for interactive debugging, development, and testing web applications. Use when you need to interact with a browser repeatedly without opening/closing it.
performance-profiling
davila7
Performance profiling principles. Measurement, analysis, and optimization techniques.
obsidian-local-dev-loop
jeremylongshore
Configure Obsidian plugin development with hot-reload and fast iteration. Use when setting up development workflow, configuring test vaults, or establishing a rapid development cycle. Trigger with phrases like "obsidian dev loop", "obsidian hot reload", "obsidian development workflow", "develop obsidian plugin".