# Diagnose and Fix Tough Software Bugs

Debugging complex bugs often leads to wasted time with unstructured trial and error. This skill provides a systematic phased methodology to build feedback loops, reproduce issues, and fix problems efficiently.

## Install

```bash
npx skillstore add mattpocock/diagnosing-bugs
```

## Metadata

- - Slug: mattpocock-diagnosing-bugs
- - Version: 1.0.0
- - Author: mattpocock
- - GitHub username: mattpocock
- - License: MIT
- - Repository: https://github.com/mattpocock/skills/tree/main/skills/engineering/diagnosing-bugs/
- - Ref: main
- - Supported tools: Claude, Codex, Claude Code
- - Risk level: low
- - Risk factors: network, external\_commands
- - Quality score: 76
- - Public page: https://skillstore.pages.dev/skills/mattpocock-diagnosing-bugs
- - Manifest: https://skillstore.pages.dev/api/skills/mattpocock-diagnosing-bugs/manifest

## Capabilities

- Guides the AI through a structured 6-phase debugging process from reproduction to fix
- Builds tight feedback loops that reliably reproduce bugs with deterministic signals
- Creates minimal reproduction cases by systematically removing non-load-bearing elements
- Generates and ranks 3 to 5 falsifiable hypotheses before testing any single theory
- Establishes performance baselines and uses targeted instrumentation for regression analysis
- Creates regression tests and documents root cause findings for future reference

## Use Cases

- Fix a Production Regression: A web application started failing after a recent deployment. The skill guides the AI to build a reproduction loop, bisect the change, and create a fix with a regression test.
- Optimize Slow Database Queries: A feature became unusable after a schema change. The skill helps establish a performance baseline, measure query plans, and identify the bottleneck through targeted instrumentation.
- Debug an Intermittent UI Bug: A UI component sometimes renders with incorrect state. The skill helps build a loop with higher reproduction rate, narrow timing windows, and inject conditions to make the flaky bug debuggable.

## Prompt Templates

### Diagnose a Simple Bug

```
I am seeing an error when I submit the form on my website. The form does not save data to the database. Can you help me diagnose and fix this issue?
```

### Debug a Performance Regression

```
The search feature on my app used to return results in under 200ms but now takes over 5 seconds. The change was deployed yesterday. Can you help me identify what caused the regression?
```

### Investigate a Complex Multi-Step Bug

```
Users report that their session expires randomly during checkout. The error only appears in production and I cannot reproduce it locally. Please help me build a feedback loop and diagnose the root cause.
```

### Full Debugging Workflow

```
Our CI pipeline has been failing intermittently for the past week. The failure is not consistent across runs. I need a systematic approach to build a reliable reproduction, identify the root cause, and implement a fix with proper regression tests.
```

## Limitations

- Cannot build a feedback loop when the bug environment is inaccessible or cannot be replicated
- Cannot fix bugs that require changes in parts of the system outside the AI modification scope
- Does not replace domain knowledge about the specific codebase framework or business logic
- May not help with bugs that have extremely low reproduction rates and no available instrumentation

## Best Practices

- Build the feedback loop first before forming any hypotheses about the root cause of the bug
- Minimize the reproduction case to only load-bearing elements before moving to hypothesis generation
- Tag all debug instrumentation with unique prefixes so cleanup is systematic and thorough

## Anti Patterns

- Jumping straight to a hypothesis without first building a working reproduction feedback loop
- Changing multiple variables at once during the instrumentation phase of investigation
- Adding untagged debug logs that accumulate in the codebase and are never cleaned up

## Security Audit

- - Safe to publish: true
- - Audited at: 2026-06-24T09:18:13.773\+00:00
- - Summary: All 13 static analysis findings were evaluated as FALSE POSITIVES. The 'Ruby/shell backtick execution' detections \(9 instances\) are Markdown inline-code backticks in SKILL.md - not actual shell execution. The 'Weak cryptographic algorithm' detections \(2 instances\) matched on YAML front matter and a checklist item - no cryptographic code exists. The 'Hardcoded URL' points to http://localhost:3000 in a user-editable template script. The 'System reconnaissance' detection is a human-in-the-loop debugging question. The skill is a debugging methodology document and a bash template for structured user interaction. No malicious intent, data exfiltration, or obfuscation detected.

## Stats

- - Views: 0
- - Downloads: 6
- - Favorites: 1
- - Popularity score: 0