debugging

Trace software failures from symptoms to root-cause hypotheses and apply verified fixes.

Updated Apr 20, 2026
One-click install
npx skills add https://github.com/thistleknot/skills --skill debugging-thistleknot
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: debugging
Source: https://github.com/thistleknot/skills/tree/main/debugging
Command: npx skills add https://github.com/thistleknot/skills --skill debugging-thistleknot

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Debugging eliminates recurring software failures by enforcing root-cause investigation before any fix, so fixes don’t turn into whack-a-mole symptom patches.

Core Features & Use Cases

  • Root-cause-first protocol: Applies the Iron Law and a 5-phase workflow (evidence → pattern recognition → hypothesis testing → implementation → verification) to convert uncertainty into testable claims.
  • Isolation and repair-surface selection: Uses zoom-out/zoom-in isolation plus hierarchical repair-surface selection to patch the highest layer that can eliminate the defect class.
  • Autonomous self-repair loop: Runs bounded run→observe→patch→rerun retries with explicit contracts, plateau detection, and escalation when repeated error classes suggest an approach-level issue.
  • Conversation state tracking: Tracks error types across turns and distinguishes independent events to avoid false causal inferences.

Quick Start

Use the debugging skill when you have a failing test, stack trace, or deterministic error to systematically isolate the fault, confirm the root cause, and apply the smallest regression-backed fix.

Frequently Asked Questions about debugging

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

FAQPage Schema
How do I find the root cause of failing unit tests instead of just patching symptoms?

Root cause analysis for failing unit tests follows a 5-phase protocol: evidence gathering, pattern recognition, hypothesis testing, implementation, and verification. This workflow converts failure uncertainty into testable claims so you apply the smallest regression-backed fix that eliminates the entire defect class.

What is the best way to isolate a deterministic crash from a stack trace?

Isolating a deterministic crash from a stack trace uses zoom-out/zoom-in isolation and hierarchical repair-surface selection. This method patches the highest architectural layer capable of removing the defect class, ensuring the fix addresses the actual fault rather than localized symptoms.

Why does my error keep recurring across multiple agent turns during debugging?

Errors recurring across turns happen when repeated error classes suggest an approach-level issue rather than a localized fault. Conversation state tracking distinguishes independent events to avoid false causal inferences, triggering escalation and plateau stopping when an autonomous self-repair loop stalls.

How do I automate a self-repair loop for compiler and lint errors without infinite retries?

Automating self-repair for compiler and lint errors requires a bounded run-observe-patch-rerun loop with explicit contracts. Plateau detection stops the autonomous retries when repeated error classes appear, escalating the issue instead of looping infinitely on approach-level problems.

When do I need regression testing documentation after fixing a software defect?

Regression testing documentation is needed immediately after post-fix verification confirms the smallest patch removes the defect class. Documenting the regression prevents the same error class from recurring in future iterations by locking the verified fix behind a test.

Can I use this debugging workflow for error isolation on any software engineering platform?

Yes, this error isolation workflow applies to any platform with available error evidence such as stack traces, failing tests, lint/compiler errors, or deterministic crashes. It requires no specific dependencies or external components to execute the structured 5-phase protocol.