- Home
- Skills
- Testing & Debugging
- Debug by Hypothesis: Find the Cause Before You Fix
Works with the AI Agents you already use
Debug by Hypothesis: Find the Cause Before You Fix
Use when something broke and the cause is unclear. Finds the last stage that worked and the first that failed, compares the likely causes, and names the one observation that tells them apart.
$5
Debug by Hypothesis: Find the Cause Before You Fix
Example session with this skill installed
The payment worker is failing with 500 errors on production but not staging. Here are the logs showing a timeout in the database pool during peak hours. Diagnose this.
- Read your context and instructions
- Compiled the debug by hypothesis
I have analyzed the payment worker logs and environmental differences to isolate the failure mechanism.
Diagnosis Card: Payment Worker Timeout
| Category | Details |
|---|---|
| Observation | Expected: Successful transaction processing. Actual: 500 Internal Server Error (Database Timeout). |
| Scope | Production environment only; limited to worker-node-04 and 07. |
| Timeline | Last Normal: 08:55 UTC. First Abnormal: 09:02 UTC (Peak load start). |
| Evidence | Failure count: 142. Error: ConnectionPoolTimeoutException at db_client.js:42. No duration split available (missing timestamps). |
Hypotheses
Connection Exhaustion |
Refuting Condition: Available idle connections in pool during peak. |
Support: High failure count correlates with 2x traffic spike.
2.
Environment Mismatch |
Refuting Condition: Identical pool sizing in Staging. |
Support: Staging uses max: 20 while Production logs suggest max: 5 config drift.
Conclusion
Likely (Strong correlation between load and timeout; mechanism identified but pool configuration not yet verified via read-only query).
Next Step: Minimal Discriminating Experiment
Action: Run DESCRIBE CONFIG on the Production DB pool via the management console.
- Result A (Config = 5): Supports Environment Mismatch; excludes code-level leak.
- Result B (Config = 20): Excludes config drift; supports Connection Exhaustion due to slow queries.
- Completion Signal: Output of configuration keys
pool_sizeandactive_connections.
Next steps
- Check the production database configuration to confirm
max_connectionslimits. - Audit recent infrastructure-as-code commits for changes to the worker environment variables.
Connects securely to your tools. The creator never sees your data.
About this skill
Software systems fail in ways that logs alone cannot explain. This skill forces a disciplined, hypothesis-led approach to root-cause analysis, preventing premature "fixes" that only mask symptoms. It focuses on isolating mechanisms and identifying discriminating evidence before any code is changed.
What it does
- Evidence isolation filters raw logs into specific windows, counts, and original error text while masking secrets.
- Hypothesis formulation generates falsifiable explanations paired with specific refuting conditions.
- Certainty grading classifies findings as located, likely, or undetermined based on evidence strength rather than intuition.
- Experiment design proposes minimal, read-only discriminating tests to exclude competing theories.
- State preservation ensures diagnosis does not destroy the failure scene or rely on simple restarts as a root cause.
How it works
- Provide the agent with available logs, documentation, or observation data.
- The agent analyzes the last known normal stage against the first abnormal stage.
- It generates a structured diagnosis card containing evidence, hypotheses, and conclusions.
- It suggests one specific A/B experiment to support or exclude current theories.
Frameworks & tools
This skill is platform-agnostic and applies to distributed systems, backend APIs, frontend states, and CI/CD pipelines. It works with any stack where error logs, stack traces, or system observations are available.
Why this beats prompting it yourself
Generic prompts often lead to "fix it" mode where the AI suggests code changes immediately. This skill enforces a hard boundary that prevents repairs until a falsifiable hypothesis is proven, stopping the cycle of "flaky" labels and temporary mitigations.
Use cases
- Diagnosing why a local build passes but the target environment fails.
- Separating correlation from causation in high-traffic service degradations.
- Identifying the specific mechanism behind intermittent 500 errors.
- Analyzing complex side effects when the original state is unknown.
Known limitations
Does not automatically execute repairs or run suggested experiments. Relies entirely on provided material and will not invent logs or timestamps if they are missing from the context.
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Testing & Debugging.
Does not execute repairs or experiments. Requires manual provision of logs/context. Will not invent missing data or timestamps.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before buying a skill.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 7 days ago
Permissions
No special permissions declared or detected