diagnose

Diagnose hard bugs and performance regressions through a reproduce-minimise-hypothesise-fix loop.

Updated Apr 6, 2026
One-click install
npx skills add https://github.com/toderian/project_template --skill diagnose-toderian
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: diagnose
Source: https://github.com/toderian/project_template/tree/main/plugins/agents-core/skills/diagnose
Command: npx skills add https://github.com/toderian/project_template --skill diagnose-toderian

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Hard bugs and performance regressions stall when developers jump straight to code-reading and guesswork without a reproducible signal. This Skill enforces a disciplined diagnosis loop — reproduce, minimise, hypothesise, instrument, fix, regression-test — so the root cause is found systematically instead of by luck. ## Core Features & Use Cases - Feedback-loop construction: Builds a fast, deterministic, agent-runnable red-capable command (failing test, curl script, headless browser, replay harness, bisection, fuzz loop) before any hypothesis work begins. - Structured hypothesis testing: Generates 3-5 ranked, falsifiable hypotheses, then instruments with tagged debug logs or profiling to test one variable at a time. - Regression locking and cleanup: Turns the minimised repro into a regression test at a correct seam, removes all debug instrumentation, and records the confirmed root cause in the commit message. - Use Case: A user reports that an export endpoint intermittently returns empty files. The Skill builds a loop that replays the failing request 100 times to raise the reproduction rate, minimises the input, tests ranked hypotheses with tagged logs, and lands a fix guarded by a regression test. ## Quick Start Ask the agent to diagnose the bug you are seeing, describing the exact symptom and how to trigger it, and let it build a reproduction loop first.

Frequently Asked Questions about diagnose

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, parallelise, add stress, or inject sleeps. A 50%-flake bug is debuggable; a 1% flake is not, so keep increasing the rate until the loop is usable.

How to reproduce a bug before fixing it?

Build one agent-runnable command — a failing test, curl script, CLI invocation, or headless browser script — that drives the actual bug code path and asserts the exact symptom. It must be red-capable, deterministic, fast, and runnable unattended before any hypothesis work begins.

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

Stop and say so explicitly rather than guessing. List what you tried, then ask for environment access, a redacted captured artifact such as a HAR file or log dump, or permission to add temporary production instrumentation.

Why write the regression test before the fix?

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

Can this approach handle performance regressions?

Yes. For performance issues, replace log-based probing with measurement: establish a baseline with a timing harness, profiler, or query plan, then bisect to find the regression. Measure first, fix second.