Debugging

Overview

The recursive-debugging subskill inserts a mandatory Phase 1.5 between Phase 1 (AS-IS) and Phase 2 (TO-BE Plan) whenever a requirement involves fixing a bug, investigating a test failure, or understanding unexpected behavior. It enforces systematic root cause analysis before any fix is attempted.

npx skills add try-works/recursive-mode --skill recursive-debugging --full-depth

Core principle: Always find the root cause before attempting fixes. Symptom fixes are failure.

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.Skipping Phase 1.5 to attempt a quick fix is not faster — it creates rework, new bugs, and thrashing. Systematic debugging is faster than guess-and-check, even under time pressure.

When to Use

Insert Phase 1.5 whenever:

A requirement is a bug fix
Tests are failing and you need to understand why
Behavior is unexpected or intermittent
A performance problem needs investigation
Integration issues are reported

Use it especially when you feel pressure to skip it: emergencies, “obvious” fixes, and repeated failed fix attempts are all signs that the process matters more, not less.

How Phase 1.5 Fits

Phase 1.5 sits between AS-IS analysis and planning:

Phase 1:   01-as-is.md          (captures current behavior)
               ↓
Phase 1.5: 01.5-root-cause.md   (this subskill)
               ↓
Phase 2:   02-to-be-plan.md     (fix plan based on confirmed root cause)

Lock Phase 1 first. Then create 01.5-root-cause.md with Status: DRAFT and work through the four steps below. Lock Phase 1.5 when root cause is confirmed. Phase 2 then consumes the findings from Phase 1.5.

The Four Steps

Error Analysis

Read error messages and stack traces completely before doing anything else. They often contain the exact location of the problem.Record in the artifact:

## Error Analysis

**Error Message:** [verbatim]
**Stack Trace:** [key frames]
**File:Line:** [locations]
**Error Code:** [if applicable]
**Key Insight:** [what the error is telling you]

Then verify you can reproduce the issue reliably. If you cannot reproduce it, gather more data — do not guess.

## Reproduction Verification

**Steps:**
1. [exact step]
2. [exact step]

**Reproducible:** Yes / No / Intermittent
**Frequency:** [X out of Y attempts]
**Deterministic:** Yes / No

Pattern Analysis

Find the difference between working and broken code before proposing any fix.

Locate similar working code in the same codebase
Compare the working and broken paths line by line
Check recent commits, dependency changes, and config changes for what could have introduced the problem
Trace data flow backward through the call stack to find where the bad value originates

Record in the artifact:

## Pattern Analysis

**Working Example:** [file:location]
**Broken Code:** [file:location]

**Key Differences:**
| Aspect | Working | Broken |
|--------|---------|--------|
| [X]    | [value] | [value] |

**Likely Cause:** [difference that explains the bug]
**Dependencies:** [what the code needs to work]

Hypothesis Testing

Form one clear hypothesis. Make the smallest possible change to test it. One variable at a time.

## Hypothesis Testing

### Hypothesis 1
**Statement:** I think X is the root cause because Y
**Rationale:** [why you think this]
**Test:** [minimal change to verify]
**Result:** confirmed / rejected
**Evidence:** [output or observation]

If the hypothesis is rejected, form a new one. Do not stack multiple fixes on top of each other to see if something works.

If you genuinely don’t understand something, say so. Do not pretend to know the root cause. Research more or ask for help.

Fix Summary

Once root cause is confirmed, write a summary that Phase 2 can build directly from.

## Root Cause Summary

**Root Cause:** [one sentence]
**Location:** [file:line]
**Explanation:** [paragraph explaining why]
**Fix Approach:** [high-level]
**Test Strategy:** [how to verify the fix]

This summary becomes the input to Phase 2’s fix plan and test strategy. Do not begin fixing until Phase 1.5 is locked.

Output Artifact

Write the artifact to:

/.recursive/run/<run-id>/01.5-root-cause.md

The artifact must close with a Coverage Gate and Approval Gate before it can be locked:

## Coverage Gate

- [ ] Error messages analyzed
- [ ] Reproduction verified
- [ ] Recent changes reviewed
- [ ] Data flow traced to source
- [ ] Pattern analysis completed
- [ ] Hypothesis tested and confirmed
- [ ] Root cause documented
- [ ] Fix strategy defined

Coverage: PASS / FAIL

## Approval Gate

- [ ] Root cause identified (not just symptom)
- [ ] Fix approach clear
- [ ] Test strategy defined
- [ ] No "quick fixes" attempted
- [ ] Ready to proceed to Phase 2

Approval: PASS / FAIL

Red Flags

Stop and return to the systematic process if you catch yourself thinking any of the following:

Thoughts that mean you're about to skip process

“Quick fix for now, investigate later”
“Just try changing X and see if it works”
“Add multiple changes, run tests”
“It’s probably X, let me fix that”
“I don’t fully understand but this might work”
You are proposing solutions before tracing data flow
You are on your third failed fix attempt

If you have made three or more failed fix attempts, stop fixing. The pattern indicates an architectural problem. Document the attempts in Phase 1.5, question whether the approach is sound, and decide whether a deeper refactor is needed before continuing.

Common Shortcuts to Reject

Excuse	Why It’s Wrong
”Issue is simple, don’t need process”	Simple issues have root causes too. The process is fast for simple bugs.
”Emergency, no time for process”	Systematic debugging is faster than guess-and-check thrashing.
”I see the problem, let me fix it”	Seeing symptoms is not the same as understanding root cause.
”Multiple fixes at once saves time”	You can’t isolate what worked. Multiple simultaneous changes cause new bugs.
”One more fix attempt” (after 2+ failures)	Three or more failures indicate an architectural problem. Question the pattern.

Get Started

Core Concepts

Subskills

Scripts

Guides

Overview

The Iron Law

When to Use

How Phase 1.5 Fits

The Four Steps

Output Artifact

Red Flags

Common Shortcuts to Reject

​Overview

​The Iron Law

​When to Use

​How Phase 1.5 Fits

​The Four Steps

​Output Artifact

​Red Flags

​Common Shortcuts to Reject

Overview

The Iron Law

When to Use

How Phase 1.5 Fits

The Four Steps

Output Artifact

Red Flags

Common Shortcuts to Reject