Skip to content

An agentic skills framework & software development methodology that works.

Consolidate debugging techniques into systematic-debugging skill

Jesse Vincent5845b52747a0
diff --git a/skills/systematic-debugging/SKILL.md b/skills/systematic-debugging/SKILL.md
index 15050052c..a6790bd59 100644
--- a/skills/systematic-debugging/SKILL.md
+++ b/skills/systematic-debugging/SKILL.md
@@ -111,7 +111,7 @@ You MUST complete each phase before proceeding to the next.
**WHEN error is deep in call stack:**
- **REQUIRED SUB-SKILL:** Use superpowers:root-cause-tracing for backward tracing technique
+ See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
**Quick version:**
- Where does bad value originate?
@@ -176,7 +176,7 @@ You MUST complete each phase before proceeding to the next.
- Automated test if possible
- One-off test script if no framework
- MUST have before fixing
- - **REQUIRED SUB-SKILL:** Use superpowers:test-driven-development for writing proper failing tests
+ - Use the `superpowers:test-driven-development` skill for writing proper failing tests
2. **Implement Single Fix**
- Address the root cause identified
@@ -275,16 +275,17 @@ If systematic investigation reveals issue is truly environmental, timing-depende
**But:** 95% of "no root cause" cases are incomplete investigation.
-## Integration with Other Skills
+## Supporting Techniques
-**This skill requires using:**
-- **root-cause-tracing** - REQUIRED when error is deep in call stack (see Phase 1, Step 5)
-- **test-driven-development** - REQUIRED for creating failing test case (see Phase 4, Step 1)
+These techniques are part of systematic debugging and available in this directory:
-**Complementary skills:**
-- **defense-in-depth** - Add validation at multiple layers after finding root cause
-- **condition-based-waiting** - Replace arbitrary timeouts identified in Phase 2
-- **verification-before-completion** - Verify fix worked before claiming success
+- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
+- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
+- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
+
+**Related skills:**
+- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)
+- **superpowers:verification-before-completion** - Verify fix worked before claiming success
## Real-World Impact
diff --git a/skills/condition-based-waiting/example.ts b/skills/systematic-debugging/condition-based-waiting-example.ts
similarity index 100%
rename from skills/condition-based-waiting/example.ts
rename to skills/systematic-debugging/condition-based-waiting-example.ts
diff --git a/skills/condition-based-waiting/SKILL.md b/skills/systematic-debugging/condition-based-waiting.md
similarity index 88%
rename from skills/condition-based-waiting/SKILL.md
rename to skills/systematic-debugging/condition-based-waiting.md
index 1684a5741..70994f777 100644
--- a/skills/condition-based-waiting/SKILL.md
+++ b/skills/systematic-debugging/condition-based-waiting.md
@@ -1,8 +1,3 @@
----
-name: condition-based-waiting
-description: Use when tests have race conditions, timing dependencies, or inconsistent pass/fail behavior - replaces arbitrary timeouts with condition polling to wait for actual state changes, eliminating flaky tests from timing guesses
----
-
# Condition-Based Waiting
## Overview
@@ -84,7 +79,7 @@ async function waitFor<T>(
}
```
-See @example.ts for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.
+See `condition-based-waiting-example.ts` in this directory for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.
## Common Mistakes
diff --git a/skills/defense-in-depth/SKILL.md b/skills/systematic-debugging/defense-in-depth.md
similarity index 93%
rename from skills/defense-in-depth/SKILL.md
rename to skills/systematic-debugging/defense-in-depth.md
index 08d69930b..e2483354d 100644
--- a/skills/defense-in-depth/SKILL.md
+++ b/skills/systematic-debugging/defense-in-depth.md
@@ -1,8 +1,3 @@
----
-name: defense-in-depth
-description: Use when invalid data causes failures deep in execution, requiring validation at multiple system layers - validates at every layer data passes through to make bugs structurally impossible
----
-
# Defense-in-Depth Validation
## Overview
diff --git a/skills/root-cause-tracing/find-polluter.sh b/skills/systematic-debugging/find-polluter.sh
similarity index 100%
rename from skills/root-cause-tracing/find-polluter.sh
rename to skills/systematic-debugging/find-polluter.sh
diff --git a/skills/root-cause-tracing/SKILL.md b/skills/systematic-debugging/root-cause-tracing.md
similarity index 93%
rename from skills/root-cause-tracing/SKILL.md
rename to skills/systematic-debugging/root-cause-tracing.md
index 823ed1eee..948477497 100644
--- a/skills/root-cause-tracing/SKILL.md
+++ b/skills/systematic-debugging/root-cause-tracing.md
@@ -1,8 +1,3 @@
----
-name: root-cause-tracing
-description: Use when errors occur deep in execution and you need to trace back to find the original trigger - systematically traces bugs backward through call stack, adding instrumentation when needed, to identify source of invalid data or incorrect behavior
----
-
# Root Cause Tracing
## Overview
@@ -103,7 +98,7 @@ npm test 2>&1 | grep 'DEBUG git init'
If something appears during tests but you don't know which test:
-Use the bisection script: @find-polluter.sh
+Use the bisection script `find-polluter.sh` in this directory:
```bash
./find-polluter.sh '.git' 'src/**/*.test.ts'