diagnosing-bugs

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

1|Updated Mar 2, 2025
One-click install
npx skills add https://github.com/marjorg/setup --skill diagnosing-bugs-marjorg
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: diagnosing-bugs
Source: https://github.com/marjorg/setup/tree/main/home/.agents/skills/archive/0-matt/diagnosing-bugs
Command: npx skills add https://github.com/marjorg/setup --skill diagnosing-bugs-marjorg

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 signal, debugging devolves into guessing. This Skill enforces a disciplined diagnosis loop that builds a tight, red-capable feedback command 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 git bisect harnesses. - Structured Six-Phase Process: Guides reproduction, minimization, ranked falsifiable hypotheses, targeted instrumentation with tagged debug logs, regression testing, and cleanup. - Human-in-the-Loop Fallback: Ships a bash template (scripts/hitl-loop.template.sh) that drives a human through manual reproduction steps and captures observations for the agent. - Use Case: A user reports that the export button intermittently throws an error. The Skill builds a Playwright loop that reproduces the failure at a high rate, 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 intermittently throws an error and have it build a reproducible feedback loop first.

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 your feedback loop reliably goes red.

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. Then minimize the scenario by removing inputs and steps one at a time until every remaining element is load-bearing for the failure.

What is the best way to debug a performance regression?

For performance regressions, avoid log-based debugging. Establish a baseline measurement with a timing harness, profiler, or query plan, then bisect between known-good and known-bad states. Measure first, fix second.

Can I debug an issue when I cannot reproduce it locally?

Yes, as a last resort use the human-in-the-loop bash template to drive a person through structured reproduction steps while capturing their observations. You can also request redacted artifacts like HAR files, log dumps, or screen recordings with timestamps.

Why should I write a regression test before the fix?

Writing the regression test first proves the test actually catches the bug by watching it fail, then confirms the fix by watching it pass. If no correct seam exists for the test, that absence itself is a finding about the codebase architecture.