diagnosing-bugs

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

Updated Jul 31, 2026
One-click install
npx skills add https://github.com/julianckt/adoptarun --skill diagnosing-bugs-julianckt
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: diagnosing-bugs
Source: https://github.com/julianckt/adoptarun/tree/main/.agents/skills/diagnosing-bugs
Command: npx skills add https://github.com/julianckt/adoptarun --skill diagnosing-bugs-julianckt

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Hard bugs and performance regressions resist casual code reading; without a reproducible failing signal, debugging devolves into guesswork. This Skill enforces a disciplined diagnosis loop that builds a tight, red-capable feedback signal before any hypothesis is tested. ## Core Features & Use Cases - Feedback Loop Construction: Builds a deterministic pass/fail signal via failing tests, curl scripts, CLI fixtures, headless browser runs, trace replays, fuzz loops, or bisection harnesses. - Structured Six-Phase Process: Guides reproduction, minimization, ranked falsifiable hypotheses, targeted instrumentation with tagged debug logs, regression testing, and cleanup with post-mortem. - Human-in-the-Loop Fallback: Ships a bash template (scripts/hitl-loop.template.sh) that drives a human through manual reproduction steps and captures structured output. - Use Case: A user reports that an export button intermittently throws an error. The Skill builds a Playwright loop that reproduces the failure, minimizes the scenario, tests ranked hypotheses one variable at a time, and lands a fix with a regression test. ## Quick Start Ask the agent to diagnose the bug where the export button throws an error, and have it build a failing reproduction loop before proposing any fix.

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 sometimes?

For non-deterministic bugs, raise the reproduction rate instead of chasing a clean repro: loop the trigger 100 times, parallelize, add stress, and narrow timing windows. A 50%-flake bug is debuggable; keep increasing the rate until the failure is frequent enough to instrument.

How to reproduce a bug before fixing it?

Build a tight feedback loop first: a failing test, curl script, CLI fixture, or headless browser run 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 is tested.

What is the best way to debug performance regressions?

For performance regressions, establish a baseline measurement first using a timing harness, performance.now(), a profiler, or query plans, then bisect between known states. Measure first and fix second; scattered logging is usually the wrong tool for perf work.

When should I write a regression test for a bug fix?

Write the regression test before the fix, but only if a correct seam exists where the test exercises the real bug pattern as it occurs at the call site. If no correct seam exists, document that architectural gap instead of writing a shallow test that gives false confidence.

What if I cannot reproduce the bug at all?

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