diagnose

Diagnose hard bugs and performance regressions through a structured reproduce-hypothesise-fix workflow.

Updated Nov 23, 2024
One-click install
npx skills add https://github.com/tokisakiyuu/dotfiles --skill diagnose-tokisakiyuu
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: diagnose
Source: https://github.com/tokisakiyuu/dotfiles/tree/main/home/dot_claude/skills/diagnose
Command: npx skills add https://github.com/tokisakiyuu/dotfiles --skill diagnose-tokisakiyuu

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Hard bugs and performance regressions stall when developers stare at code without a reliable reproduction signal. This Skill enforces a disciplined six-phase loop — build a feedback loop, reproduce, hypothesise, instrument, fix with regression test, and clean up — so debugging converges on the real root cause instead of guesses. ## Core Features & Use Cases - Feedback-loop construction: Ten ranked strategies for building a deterministic pass/fail signal, from failing tests and curl scripts to headless browser runs, trace replay, fuzz loops, and git bisect harnesses. - Ranked falsifiable hypotheses: Generates 3–5 hypotheses with explicit predictions before testing, and tags all debug instrumentation with unique prefixes for one-grep cleanup. - Regression testing and post-mortem: Writes the regression test before the fix at a correct seam, verifies the original repro no longer fails, and records the confirmed root cause in the commit message. - Use Case: A user reports that an export endpoint intermittently returns corrupted data. The Skill builds a loop that replays the failing request 100 times, ranks hypotheses, instruments the boundary between serialization and transport, and lands a fix guarded by a regression test. ## Quick Start Ask the agent to diagnose the bug where the export endpoint intermittently returns corrupted data and follow the structured diagnosis loop.

Frequently Asked Questions about diagnose

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

FAQPage Schema
How do I debug an intermittent or flaky bug?▼

Raise the reproduction rate instead of chasing a clean repro: loop the trigger 100 times, parallelise, add stress, narrow timing windows, or inject sleeps. A bug that fails 50% of the time is debuggable; at 1% it is not, so keep increasing the rate until hypotheses can be tested against it.

How to diagnose a performance regression in code?▼

Establish a baseline measurement first using a timing harness, profiler, or query plan, then bisect between known-good and known-bad states. Logs are usually the wrong tool for performance work; measure first and fix second.

What should I do when a bug cannot be reproduced locally?▼

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

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

Write the regression test before the fix, but only at a correct seam where the test exercises the real bug pattern as it occurs at the call site. If no correct seam exists, that absence is itself a finding about the codebase architecture and should be flagged.

Why generate multiple hypotheses before testing a bug?▼

Generating 3-5 ranked falsifiable hypotheses prevents anchoring on the first plausible idea. Each hypothesis must state a testable prediction, and showing the ranked list to the user lets domain knowledge re-rank it before time is spent testing.