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.mdindex 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 tests2. **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 Impactdiff --git a/skills/condition-based-waiting/example.ts b/skills/systematic-debugging/condition-based-waiting-example.tssimilarity index 100%rename from skills/condition-based-waiting/example.tsrename to skills/systematic-debugging/condition-based-waiting-example.tsdiff --git a/skills/condition-based-waiting/SKILL.md b/skills/systematic-debugging/condition-based-waiting.mdsimilarity index 88%rename from skills/condition-based-waiting/SKILL.mdrename to skills/systematic-debugging/condition-based-waiting.mdindex 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 Mistakesdiff --git a/skills/defense-in-depth/SKILL.md b/skills/systematic-debugging/defense-in-depth.mdsimilarity index 93%rename from skills/defense-in-depth/SKILL.mdrename to skills/systematic-debugging/defense-in-depth.mdindex 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## Overviewdiff --git a/skills/root-cause-tracing/find-polluter.sh b/skills/systematic-debugging/find-polluter.shsimilarity index 100%rename from skills/root-cause-tracing/find-polluter.shrename to skills/systematic-debugging/find-polluter.shdiff --git a/skills/root-cause-tracing/SKILL.md b/skills/systematic-debugging/root-cause-tracing.mdsimilarity index 93%rename from skills/root-cause-tracing/SKILL.mdrename to skills/systematic-debugging/root-cause-tracing.mdindex 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'