debug-issue

Diagnose repository bugs through a six-phase root-cause workflow with falsifiable hypotheses and regression tests.

7|3|Updated Sep 23, 2025
One-click install
npx skills add https://github.com/islamu-ngo/Event --skill debug-issue-islamu-ngo
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: debug-issue
Source: https://github.com/islamu-ngo/Event/tree/main/.agents/skills/debug-issue
Command: npx skills add https://github.com/islamu-ngo/Event --skill debug-issue-islamu-ngo

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Debugging often devolves into speculative code reading and untested fixes. This Skill enforces a disciplined diagnosis loop that reproduces the exact symptom with a deterministic failing test before any fix is attempted, ensuring the true root cause is found and verified. ## Core Features & Use Cases - Deterministic Red Feedback Loop: Builds one fast (<2s) failing command—TUnit test, HTTP request, or throwaway harness—that goes red on the bug and green when fixed. - Ranked Falsifiable Hypotheses: Requires 3-5 hypotheses with concrete testable predictions before any probing begins. - Knowledge-Graph Tracing: Uses callers/callees queries and affected-flow analysis to trace execution paths, with tagged [DEBUG-...] logs guaranteeing clean removal. - Use Case: A MediatR handler returns wrong results in production. The Skill guides you to write a failing regression test at the handler seam, minimise inputs, test ranked hypotheses, apply the minimal fix, and verify the original scenario passes. ## Quick Start Ask the AI to debug the failing checkout flow using the debug-issue workflow, starting by building a failing test that reproduces the exact reported symptom.

Frequently Asked Questions about debug-issue

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

FAQPage Schema
How do I debug a bug with an unknown root cause in a repository?▼

Start by building one fast, deterministic command that reproduces the exact symptom and fails, such as a targeted TUnit test or HTTP request. Then minimise inputs, rank 3-5 falsifiable hypotheses, probe with knowledge-graph tracing, and fix only after the failing test exists.

How to write a regression test for a MediatR handler bug?▼

Write the regression test at the public seam, meaning the MediatR handler or API route, using a --treenode-filter to run it in isolation. If no clean public interface exists without shallow mocking, that missing seam is recorded as an architectural deficiency.

What is a falsifiable hypothesis in debugging?▼

A falsifiable hypothesis states a concrete, testable prediction: if X is the root cause, then changing Y makes the bug disappear or changing Z makes it worse. Hypotheses without such predictions are invalid and must not be tested.

Does this debugging workflow work without a failing test first?▼

No. The workflow forbids reading code to form speculative theories or applying fixes before a deterministic red feedback loop exists. This hypothesis gate ensures the fix is verified against the actual reported symptom, not an adjacent error.

How do I remove temporary debug logs before merging?▼

Tag every temporary debug log with a unique prefix like [DEBUG-4a1f] when adding it. Before merging, run grep for the [DEBUG- pattern and confirm it returns zero matches, guaranteeing complete cleanup.