diagnose

Diagnose software bugs through a structured six-phase hypothesis-driven workflow.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Ad-hoc, unguided debugging of hard bugs and performance regressions wastes engineering time with random hypothesis testing and missed root causes, leading to recurring defects and slow incident resolution.

Core Features & Use Cases

  • 6-Phase Disciplined Loop: Enforces a repeatable workflow of building a feedback loop, reproducing the bug, generating ranked falsifiable hypotheses, targeted instrumentation, fixing with regression tests, and post-mortem cleanup to avoid unproductive debugging.
  • Reproduction Loop Guidance: Provides 10 prioritized strategies to build fast, deterministic, agent-runnable reproduction loops for even non-deterministic and hard-to-trigger bugs, including human-in-the-loop scenarios.
  • Use Case: When a production service has an intermittent crash or a performance regression that only appears under specific load conditions, use this skill to systematically isolate the root cause instead of guessing at code changes.

Quick Start

Use the diagnose skill to work through the reported intermittent timeout bug in the data ingestion pipeline by following the structured 6-phase diagnosis loop.

Frequently Asked Questions about diagnose

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

FAQPage Schema
What is a systematic diagnosis workflow for hard software bugs?

A systematic diagnosis workflow enforces a repeatable, hypothesis-driven debug process to find root causes. It replaces ad-hoc guessing with a structured loop involving deterministic reproduction, targeted instrumentation, and regression testing to resolve hard software bugs.

How do I debug intermittent crashes and non-deterministic failures in production services?

To debug intermittent crashes and non-deterministic failures, build a fast deterministic reproduction loop. Rank falsifiable hypotheses, apply targeted instrumentation to isolate the root cause, and verify the fix with mandatory regression tests to prevent recurrence.

What is the best way to troubleshoot a performance regression under specific load conditions?

The best way to troubleshoot a performance regression is following a disciplined 6-phase debug loop. It guides you through reproducing the slowdown, generating ranked hypotheses, and adding targeted instrumentation to systematically isolate the root cause.

How do I build a reproduction loop for hard-to-reproduce defects in data pipelines?

Build a reproduction loop for hard-to-reproduce defects using prioritized strategies to create fast, deterministic, agent-runnable tests. This includes techniques for triggering elusive bugs and handling human-in-the-loop scenarios within data pipelines.

Does this structured debugging approach work for web services and client applications?

Yes, this structured debugging approach applies to web services, data pipelines, and client applications. It handles intermittent crashes, non-deterministic failures, and performance slowdowns across these environments by enforcing a repeatable diagnosis workflow.

Why should I use a hypothesis-driven debug process instead of testing random code changes?

A hypothesis-driven debug process eliminates inefficient, unproductive debugging by testing ranked falsifiable hypotheses. This prevents missed root causes and recurring defects, saving engineering time compared to randomly guessing at code changes.