Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    Debug by Hypothesis: Find the Cause Before You Fix

    1

    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

    Secure checkout via Stripe

    Money-back guarantee

    Converts to your local currency at checkout

    Security scanned
    Debug by Hypothesis: Find the Cause Before You Fix

    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

    CategoryDetails
    ObservationExpected: Successful transaction processing. Actual: 500 Internal Server Error (Database Timeout).
    ScopeProduction environment only; limited to worker-node-04 and 07.
    TimelineLast Normal: 08:55 UTC. First Abnormal: 09:02 UTC (Peak load start).
    EvidenceFailure 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_size and active_connections.

    Next steps

    1. Check the production database configuration to confirm max_connections limits.
    2. 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

    1. Provide the agent with available logs, documentation, or observation data.
    2. The agent analyzes the last known normal stage against the first abnormal stage.
    3. It generates a structured diagnosis card containing evidence, hypotheses, and conclusions.
    4. 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.

    Does not execute repairs or experiments. Requires manual provision of logs/context. Will not invent missing data or timestamps.

    How to use

    1. 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. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before any payment.

    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

    Listed7 days ago

    What's inside

    Frequently Asked Questions

    Generic prompts often jump straight to suggesting code changes, whereas this skill enforces a disciplined 'diagnose-before-fix' workflow that focuses on falsifiable hypotheses and evidence isolation to prevent masking symptoms.

    This skill is platform-agnostic and works with any stack, from distributed backend APIs to CI/CD pipelines, as long as you can provide logs, stack traces, or system observations.

    No, the skill is designed for safe root-cause analysis; it identifies the mechanism of failure and proposes read-only experiments, but it will never modify your codebase or execute scripts automatically.

    You will receive the 'Hypothesis Led Diagnosis' skill package, which includes the structured diagnostic logic, templates for evidence cards, and documentation on how to integrate it into your existing AI agent workflow.

    The skill requires raw diagnostic data such as error logs, timestamps, or system documentation; it cannot 'invent' data and will flag a status as 'undetermined' if the provided context is insufficient to prove a hypothesis.

    New in Testing & Debugging