ha-debug

Diagnose code failures by ranking falsifiable hypotheses and fixing root causes.

1.6k|149|Updated Mar 13, 2026
One-click install
npx skills add https://github.com/shiwenwen/hope-agent --skill ha-debug
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: ha-debug
Source: https://github.com/shiwenwen/hope-agent/tree/main/skills/ha-debug
Command: npx skills add https://github.com/shiwenwen/hope-agent --skill ha-debug

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Debugging often stalls when developers jump to the first plausible explanation instead of working from evidence. This Skill provides a disciplined decision process for code failures, regressions, crashes, flaky behavior, and bad output: characterize the failure, bound the fault, rank falsifiable hypotheses, fix the smallest root cause, and prove the failing path.

Core Features & Use Cases

  • Evidence-First Characterization: Captures exact symptoms, reproduction steps, stack traces, and determinism properties before theorizing, with explicit handling for cases where reproduction is unsafe or impossible.
  • Hypothesis Ranking: Keeps one or two active hypotheses, each with a disproving observation and the cheapest discriminating check, preventing shotgun debugging.
  • Root-Cause Fixing with Proof: Patches the smallest ownership boundary, stops after two failed fix attempts to re-challenge assumptions, and requires a regression check that would have failed before the fix.
  • Use Case: A test fails intermittently in CI. Use this Skill to characterize the timing sensitivity, bound the fault across async and concurrency boundaries, run the cheapest discriminating check, fix the root cause, and add a focused regression test.

Quick Start

Ask the agent to debug an intermittent test failure by finding and fixing the root cause from the failing logs.

Frequently Asked Questions about ha-debug

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

FAQPage Schema
How do I debug an intermittent test failure?

Characterize whether the failure is timing-sensitive, data-specific, or platform-specific, then bound the fault across async ordering, locks, and concurrency boundaries. Rank one or two falsifiable hypotheses and run the cheapest discriminating check before editing code.

How to find the root cause of a regression instead of patching symptoms?

Trace the smallest credible path through inputs, state transitions, persistence, and outputs, comparing what crosses each component boundary. Patch only the smallest ownership boundary that restores the contract, and stop after two failed attempts to re-challenge your assumptions.

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

Characterize the failure from logs, fixtures, persisted state, and code paths instead of live reproduction, and state the evidence gap explicitly. Never mark an unreproduced hypothesis as confirmed; report the strongest substitute evidence and remaining uncertainty.

Does passing compilation prove a runtime bug is fixed?

No. Passing compilation alone does not prove a runtime bug is fixed. Use a focused regression test, a deterministic failing command, a before/after database or log query, or manual reproduction that would have failed before the fix.

When should a debugging session stop and ask for human input?

Pause only when progress requires inaccessible user state, an external system change, a destructive action, or a product decision. Do not invent data or broaden scope into speculative rewrites before the fault is proven.