debug

Enforce root-cause investigation before fixes using the Iron Law and Investigation Move.

Updated Mar 3, 2026
One-click install
npx skills add https://github.com/tesserine/groundwork --skill debug-tesserine
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: debug
Source: https://github.com/tesserine/groundwork/tree/main/skills/debug
Command: npx skills add https://github.com/tesserine/groundwork --skill debug-tesserine

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Root-cause investigation discipline. Use when a test fails, behavior is unexpected, or any failure occurs — before proposing fixes. Enforces structured investigation before fix attempts. Fires at any stage when failures appear. If you are about to fix something without understanding why it broke, this skill applies.

Core Features & Use Cases

  • The Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
  • The Investigation Move: five steps (Stop, Read, Reproduce, Trace, Hypothesize and test)
  • The 3-Fix Escalation Rule: count fix attempts; escalate to reckon if needed
  • Pattern Analysis and Recognition Index: guardrails that steer investigation toward root cause
  • Cross-protocol coordination: ties investigate activity to implement, verify, reckon, and resolve

Quick Start

Begin root-cause investigation on a failure by following the Iron Law and Investigation Move steps.

Frequently Asked Questions about debug

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

FAQPage Schema
How do I find the root cause of a failing test before attempting a fix?

To find the root cause of a failing test, enforce structured investigation before fix attempts using the Iron Law and the five-step Investigation Move: Stop, Read, Reproduce, Trace, and Hypothesize. This prevents symptom fixes and ensures reliable defect resolution.

What is evidence-based debugging and when should I apply it?

Evidence-based debugging is a discipline that requires understanding why a failure occurred before proposing fixes. Apply it whenever a test fails, behavior is unexpected, or any defect appears during planning, execution, or verification phases.

How do I investigate unexpected software behavior step by step?

Investigate unexpected behavior by executing the Investigation Move: stop immediate fixes, read the failure output, reproduce the defect consistently, trace execution paths, and formulate testable hypotheses to validate the suspected root cause.

What should I do when my initial fix attempts for a defect keep failing?

When initial fix attempts for a defect keep failing, apply the 3-Fix Escalation Rule to count attempts and escalate to a reckoning phase, preventing repeated symptom patches and forcing a deeper root-cause analysis.

Can I use this debugging process across different development phases?

Yes, you can use this debugging process across planning, execution, verification, and landing phases. It coordinates investigation activity with implementation and verification protocols to maintain quality assurance throughout.