diagnose

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

11|2|Updated Dec 29, 2025
One-click install
npx skills add https://github.com/oskrgab/petrodb --skill diagnose-oskrgab
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: diagnose
Source: https://github.com/oskrgab/petrodb/tree/main/.agents/skills/diagnose
Command: npx skills add https://github.com/oskrgab/petrodb --skill diagnose-oskrgab

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, and clean up — so root causes are found systematically instead of by guesswork. ## Core Features & Use Cases - Feedback-loop construction: Ten ranked strategies for building a deterministic pass/fail signal, from failing tests and curl scripts to replayed traces, fuzz loops, and git bisect harnesses. - Ranked hypothesis testing: Generates 3-5 falsifiable hypotheses with explicit predictions before any probing, and tags all debug logs 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 documents the confirmed root cause. - Use Case: A user reports intermittent 500 errors after a deploy. The Skill guides building a replay harness from a captured request, reproducing the failure at a high rate, bisecting hypotheses, and landing a fix with a regression test. ## Quick Start Ask the agent to diagnose the bug you are seeing and describe the exact symptom, error message, or performance regression you observed.

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?

Non-deterministic bugs are handled by raising the reproduction rate rather than seeking a clean repro. Loop the trigger 100 times, parallelise, add stress, narrow timing windows, or inject sleeps until the failure rate is high enough to debug against.

How to diagnose a performance regression in code?

Performance regressions skip log-based probing. Establish a baseline measurement with a timing harness, profiler, or query plan, then bisect between known states to isolate the cause. Measure first, fix second.

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

Stop and say so explicitly rather than guessing. Ask for environment access, a captured artifact such as a HAR file, log dump, or core dump, or permission to add temporary production instrumentation before forming hypotheses.

Why write the regression test before the fix?

Writing the test first proves it captures the real bug pattern by watching it fail, then confirms the fix by watching it pass. If no correct test seam exists, that architectural gap is itself documented as a finding.

When should this diagnosis workflow not be used?

The full six-phase loop is overkill for trivial, obvious bugs with known causes. Phases may be skipped only with explicit justification; the workflow targets hard bugs where the cause is genuinely unknown.