diagnosing-bugs

Diagnose hard bugs and performance regressions through a structured six-phase feedback-loop workflow.

Updated Aug 13, 2026
One-click install
npx skills add https://github.com/Evolutionary-Leadership/harness --skill diagnosing-bugs-evolutionary-leadership
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: diagnosing-bugs
Source: https://github.com/Evolutionary-Leadership/harness/tree/main/.claude/skills/diagnosing-bugs
Command: npx skills add https://github.com/Evolutionary-Leadership/harness --skill diagnosing-bugs-evolutionary-leadership

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Hard bugs and flaky failures resist casual code reading; without a reproducible signal, debugging devolves into guessing. This Skill enforces a disciplined diagnosis loop that builds a tight pass/fail feedback signal first, then reproduces, minimizes, hypothesizes, instruments, fixes, and cleans up. ## Core Features & Use Cases - Feedback loop construction: Builds a red-capable, deterministic, fast reproduction command using failing tests, curl scripts, CLI fixtures, headless browsers, trace replay, fuzz loops, or bisection harnesses. - Structured hypothesis testing: Generates 3-5 ranked falsifiable hypotheses, then instruments with tagged debug logs or debugger breakpoints, changing one variable at a time. - Regression and post-mortem: Writes the regression test before the fix at a correct seam, removes all debug instrumentation, and records the confirmed root cause in the commit message. - Use Case: A user reports that the export button intermittently throws an error in production. The Skill guides building a replay loop from a captured request, minimizing the failing scenario, testing ranked hypotheses, and landing a fix with a regression test. ## Quick Start Diagnose why the export endpoint intermittently returns a 500 error by building a reproduction loop and following the phased debugging workflow.

Frequently Asked Questions about diagnosing-bugs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug a bug that only happens intermittently?

For non-deterministic bugs, raise the reproduction rate instead of chasing a clean repro: loop the trigger 100 times, parallelize, add stress, narrow timing windows, or inject sleeps. A 50%-flake bug is debuggable; keep increasing the rate until the loop reliably goes red.

How to reproduce a bug before fixing it?

Build a tight feedback loop first: a failing test, curl script, CLI invocation, headless browser script, or replayed trace that asserts the user's exact symptom. The loop must be deterministic, fast, and able to go red on this specific bug before any hypothesis work begins.

What should I do when I cannot reproduce a bug locally?

Stop and say so explicitly rather than guessing. Ask the user for environment access, a redacted captured artifact such as a HAR file or log dump, or permission to add temporary production instrumentation. Do not proceed to hypothesizing without a working loop.

Why should the regression test be written before the fix?

Writing the test first at a correct seam proves it actually captures the bug: you watch it fail, apply the fix, then watch it pass. If no correct seam exists, that absence is itself a finding about the codebase architecture worth flagging.

How do I debug a performance regression?

For performance regressions, skip log-based probing. Establish a baseline measurement with a timing harness, performance.now(), a profiler, or query plans, then bisect between known states. Measure first, fix second.