# Debug Complex Issues with a Structured Diagnosis Loop

When bugs resist diagnosis or performance mysteriously degrades, use a disciplined six-phase loop: reproduce, minimise, hypothesise, instrument, fix, and regression-test. This skill provides the exact methodology to avoid guesswork and solve hard problems systematically.

## Install

```bash
npx skillstore add mattpocock/diagnose
```

## Metadata

- - Slug: mattpocock-diagnose
- - Version: 1.0.0
- - Author: mattpocock
- - GitHub username: mattpocock
- - License: MIT
- - Repository: https://github.com/mattpocock/skills/tree/main/skills/engineering/diagnose/
- - Ref: main
- - Supported tools: Claude, Codex, Claude Code
- - Risk level: safe
- - Quality score: 78
- - Quality tier: bronze
- - Public page: https://skillstore.pages.dev/skills/mattpocock-diagnose
- - Manifest: https://skillstore.pages.dev/api/skills/mattpocock-diagnose/manifest

## Capabilities

- Build deterministic feedback loops for any bug or performance regression
- Reproduce issues with high confidence before attempting fixes
- Generate and rank multiple falsifiable hypotheses to avoid anchoring
- Instrument code with targeted probes that map to specific predictions
- Write regression tests at the correct seam before applying fixes
- Clean up debugging artifacts and document findings for future developers

## Use Cases

- Debugging Intermittent Failures: A flaky test or race condition that only fails 20% of the time. Use the methodology to raise the reproduction rate through stress testing and parallelisation until the bug is debuggable.
- Performance Regression Investigation: A feature that worked fast six months ago is now slow. Build a timing harness, establish a baseline, then bisect to find which change introduced the regression.
- Root Cause Analysis for Production Bugs: A production issue with no clear cause. Capture a HAR file or log dump, build a minimised repro from real data, then apply the hypothesis-test loop to find the root cause.

## Prompt Templates

### Basic Bug Diagnosis

```
Use the diagnose skill. My application is throwing an error: [describe error]. The bug appears when [describe trigger]. I want you to build a feedback loop and work through the diagnosis phases.
```

### Performance Investigation

```
Use the diagnose skill for a performance regression. The [feature name] endpoint has gotten slower over the last [timeframe]. Current response time is [X]ms. Help me build a timing harness and find the root cause.
```

### Non-deterministic Failure

```
Use the diagnose skill. This test fails randomly about [X]% of the time. I cannot reproduce it locally. Help me increase the reproduction rate and identify the root cause.
```

### Production Issue Analysis

```
Use the diagnose skill. We have a production issue: [describe]. I have captured [logs/HAR file/core dump]. Help me replay the trace, build a minimised repro, and apply the diagnosis loop.
```

## Limitations

- Cannot build feedback loops for issues where no reproducible environment exists
- Performance debugging requires baseline measurements - cannot work without them
- Non-deterministic bugs with reproduction rates below 1% may remain undebuggable
- Cannot help if codebase architecture prevents writing meaningful regression tests

## Best Practices

- Spend disproportionate time building the feedback loop - a 2-second deterministic loop beats a 30-second flaky one every time
- Always generate 3-5 ranked hypotheses before testing any of them to avoid anchoring on the first plausible idea
- Tag all debug instrumentation with unique prefixes like \[DEBUG-a4f2\] so cleanup becomes a single grep operation

## Anti Patterns

- Proceeding to hypothesis generation without a working feedback loop - this leads to guesswork, not debugging
- Testing multiple hypotheses simultaneously instead of changing one variable at a time
- Skipping the regression test step when no correct seam exists - document the architecture gap instead

## Security Audit

- - Safe to publish: true
- - Audited at: 2026-05-01T08:49:47.161\+00:00
- - Summary: All 12 static analysis findings are false positives. The skill is a documentation/guide describing debugging methodology with no actual code execution. The hitl-loop.template.sh is a passive user instruction template with no real network calls or shell execution. No security concerns identified.

## Stats

- - Views: 80
- - Downloads: 2
- - Favorites: 0
- - Popularity score: 0