@vodailoc/kilo-kit-mcp 1.1.0 → 1.2.0

package/skills/kilo-kit/debugging/systematic/SKILL.md

@@ -1,339 +1,339 @@
----
-name: systematic-debugging
-description: >-
-  Comprehensive 4-phase debugging methodology for complex bugs.
-  Use for bugs that aren't immediately obvious or have resisted quick fixes.
-  Keywords: bug, error, fix, debug, broken, crash, fail, exception
-version: 1.0.0
-behaviors: [parse_error, search_code, reason, validate, write_file]
-dependencies: []
-token_estimate:
-  min: 1500
-  typical: 3500
-  max: 8000
----
-
-# 🔍 Systematic Debugging Skill
-
-> **Philosophy:** Understand before you fix. Verify before you celebrate.
-
-## When to Use
-
-Use this skill when:
-- Bug is not immediately obvious
-- Previous quick fixes have failed
-- Error involves multiple components
-- Need to ensure no regression from fix
-- Production issue requiring careful handling
-
-**Do NOT use this skill when:**
-- Bug is trivial (typo, missing import)
-- Just need a quick syntax check
-- Issue is really a feature request
-
----
-
-## Prerequisites
-
-Before starting:
-- [ ] Have access to the codebase
-- [ ] Can reproduce the bug OR have error logs
-- [ ] Understand the expected behavior
-- [ ] Know which environment is affected
-
----
-
-## Process
-
-### Phase 1: ROOT CAUSE INVESTIGATION 🔬
-
-**Goal:** Find the TRUE cause, not just symptoms.
-
-**Steps:**
-
-1. **Reproduce the Bug**
-   ```
-   Ask yourself:
-   - Can I make this happen consistently?
-   - What are the exact steps?
-   - What input causes it?
-   ```
-
-2. **Gather Evidence**
-   - Error messages (complete, not truncated)
-   - Stack traces
-   - Relevant logs
-   - Recent changes (git log, blame)
-
-3. **Trace the Flow**
-   ```
-   Start from: Error location
-   Work backward: How did we get here?
-   Find: Where does expected != actual?
-   ```
-
-4. **Identify the Root Cause**
-   - Not "it crashed" but "WHY it crashed"
-   - Not "wrong output" but "WHAT produced wrong output"
-
-**Output:** Clear statement of root cause.
-
-**Red Flags (STOP if you find yourself doing these):**
-- ❌ Immediately jumping to code changes
-- ❌ Assuming you know the cause without evidence
-- ❌ Changing things randomly hoping they'll work
-- ❌ Ignoring the stack trace
-
----
-
-### Phase 2: PATTERN ANALYSIS 📊
-
-**Goal:** Understand the shape of the problem.
-
-**Steps:**
-
-1. **Scope Assessment**
-   - Is this isolated or systemic?
-   - Does it affect other components?
-   - Has this happened before?
-
-2. **Similar Pattern Search**
-   ```bash
-   # Search for similar patterns in codebase
-   grep -r "similar_pattern" src/
-   ```
-
-3. **Dependency Check**
-   - What depends on the broken code?
-   - What does the broken code depend on?
-
-4. **Risk Assessment**
-   - What could break if we fix this?
-   - Are there other places with same bug?
-
-**Output:** Understanding of bug's scope and risk.
-
----
-
-### Phase 3: HYPOTHESIS & TESTING 🧪
-
-**Goal:** Develop and test fix hypothesis.
-
-**Steps:**
-
-1. **Form Hypothesis**
-   ```
-   "If I change X to Y, then Z should work because..."
-   ```
-   
-   **Good hypothesis includes:**
-   - Specific change
-   - Expected outcome
-   - Reasoning
-
-2. **Design the Fix**
-   - Minimal change principle
-   - Don't fix what isn't broken
-   - Consider edge cases
-
-3. **Mental/Paper Test**
-   - Walk through the code with fix
-   - Does it address root cause?
-   - Any side effects?
-
-4. **Create Test Case**
-   - Before implementing fix, write test that fails
-   - Test should pass after fix
-   - Include edge cases
-
-**Output:** Tested hypothesis ready for implementation.
-
----
-
-### Phase 4: IMPLEMENTATION & VERIFICATION ✅
-
-**Goal:** Apply fix and verify it works.
-
-**Steps:**
-
-1. **Implement the Fix**
-   - Apply minimal necessary changes
-   - Add comments explaining WHY (not just what)
-   - Follow project coding standards
-
-2. **Run Existing Tests**
-   ```bash
-   # All tests must pass
-   npm test    # or pytest, etc.
-   ```
-
-3. **Run New Test Case**
-   - Test you wrote in Phase 3 should now pass
-   - Verify fix addresses root cause
-
-4. **Verify No Regression**
-   - Related functionality still works
-   - No new errors introduced
-   - Performance not degraded
-
-5. **Documentation**
-   - Update relevant docs if needed
-   - Consider adding to known issues/patterns
-
-**Output:** Verified fix with passing tests.
-
----
-
-## Debugging Decision Tree
-
-```
-Bug Report Received
-        │
-        ▼
-┌─────────────────┐
-│ Can reproduce?  │
-└────────┬────────┘
-    YES  │  NO
-         │  └──► Gather more info, check logs, ask for steps
-         ▼
-┌─────────────────┐
-│ Error obvious?  │
-└────────┬────────┘
-    YES  │  NO
-         │  └──► Phase 1: Root Cause Investigation
-         ▼
-Quick fix
-         │
-         ▼
-┌─────────────────┐
-│ Fix verified?   │
-└────────┬────────┘
-    YES  │  NO
-         │  └──► Return to investigation
-         ▼
-    Complete ✓
-```
-
----
-
-## Guidelines
-
-### DO ✅
-- Read the full stack trace
-- Reproduce before fixing
-- Change one thing at a time
-- Test after each change
-- Keep notes during investigation
-- Ask "WHY" at least 3 times
-
-### DON'T ❌
-- Assume you know the cause
-- Make multiple changes at once
-- Skip testing
-- Ignore "unrelated" errors
-- Rush to deploy fix
-- Delete old code without understanding it
-
----
-
-## Common Patterns
-
-### Pattern: Off-by-One Error
-
-**When:** Array/loop issues, boundary conditions
-
-**Detection:**
-- Works for most cases, fails at edges
-- Index out of bounds errors
-- Missing first/last item
-
-**Solution:**
-- Check `<` vs `<=`
-- Check starting index (0 vs 1)
-- Verify array length handling
-
-### Pattern: Async/Timing Issue
-
-**When:** Race conditions, inconsistent failures
-
-**Detection:**
-- Works sometimes, fails other times
-- Different behavior in different environments
-- Issues with "slow" operations
-
-**Solution:**
-- Add proper await/promises
-- Check for missing error handling
-- Consider operation ordering
-
-### Pattern: Null/Undefined Reference
-
-**When:** Missing data, optional fields
-
-**Detection:**
-- "Cannot read property of undefined"
-- Works with some data, not others
-- Fails after recent data changes
-
-**Solution:**
-- Add null checks
-- Use optional chaining (?.)
-- Validate data at entry points
-
----
-
-## Anti-Patterns (AVOID)
-
-### Anti-Pattern: "It Works on My Machine"
-
-**Problem:** Not investigating environment differences.
-
-**Instead:** 
-- Compare environments systematically
-- Check versions, configs, dependencies
-- Document environment requirements
-
-### Anti-Pattern: "Shotgun Debugging"
-
-**Problem:** Changing random things hoping something works.
-
-**Instead:**
-- Form hypothesis first
-- Test ONE change at a time
-- Keep track of what you tried
-
-### Anti-Pattern: "It's Fixed Now" (No Verification)
-
-**Problem:** Assuming fix works without testing.
-
-**Instead:**
-- Always run tests
-- Verify the exact scenario that failed
-- Check for regressions
-
----
-
-## Success Criteria
-
-Before claiming the bug is fixed:
-
-- [ ] Root cause identified and documented
-- [ ] Fix addresses root cause (not just symptom)
-- [ ] Test case written that would catch this bug
-- [ ] All existing tests pass
-- [ ] New test passes
-- [ ] No regressions in related functionality
-- [ ] Fix is reviewable (clear, minimal, documented)
-- [ ] User can verify the fix works
-
----
-
-## Related Skills
-
-- `skills/kilo-kit/debugging/root-cause/` - For deeper root cause analysis
-- `skills/kilo-kit/debugging/verification/` - For thorough verification
-- `skills/kilo-kit/quality/testing/` - For writing better tests
-
----
-
-*Systematic Debugging Skill v1.0.0 — Understand before you fix*
+---
+name: systematic-debugging
+description: >-
+  Comprehensive 4-phase debugging methodology for complex bugs.
+  Use for bugs that aren't immediately obvious or have resisted quick fixes.
+  Keywords: bug, error, fix, debug, broken, crash, fail, exception
+version: 1.0.0
+behaviors: [parse_error, search_code, reason, validate, write_file]
+dependencies: []
+token_estimate:
+  min: 1500
+  typical: 3500
+  max: 8000
+---
+
+# 🔍 Systematic Debugging Skill
+
+> **Philosophy:** Understand before you fix. Verify before you celebrate.
+
+## When to Use
+
+Use this skill when:
+- Bug is not immediately obvious
+- Previous quick fixes have failed
+- Error involves multiple components
+- Need to ensure no regression from fix
+- Production issue requiring careful handling
+
+**Do NOT use this skill when:**
+- Bug is trivial (typo, missing import)
+- Just need a quick syntax check
+- Issue is really a feature request
+
+---
+
+## Prerequisites
+
+Before starting:
+- [ ] Have access to the codebase
+- [ ] Can reproduce the bug OR have error logs
+- [ ] Understand the expected behavior
+- [ ] Know which environment is affected
+
+---
+
+## Process
+
+### Phase 1: ROOT CAUSE INVESTIGATION 🔬
+
+**Goal:** Find the TRUE cause, not just symptoms.
+
+**Steps:**
+
+1. **Reproduce the Bug**
+   ```
+   Ask yourself:
+   - Can I make this happen consistently?
+   - What are the exact steps?
+   - What input causes it?
+   ```
+
+2. **Gather Evidence**
+   - Error messages (complete, not truncated)
+   - Stack traces
+   - Relevant logs
+   - Recent changes (git log, blame)
+
+3. **Trace the Flow**
+   ```
+   Start from: Error location
+   Work backward: How did we get here?
+   Find: Where does expected != actual?
+   ```
+
+4. **Identify the Root Cause**
+   - Not "it crashed" but "WHY it crashed"
+   - Not "wrong output" but "WHAT produced wrong output"
+
+**Output:** Clear statement of root cause.
+
+**Red Flags (STOP if you find yourself doing these):**
+- ❌ Immediately jumping to code changes
+- ❌ Assuming you know the cause without evidence
+- ❌ Changing things randomly hoping they'll work
+- ❌ Ignoring the stack trace
+
+---
+
+### Phase 2: PATTERN ANALYSIS 📊
+
+**Goal:** Understand the shape of the problem.
+
+**Steps:**
+
+1. **Scope Assessment**
+   - Is this isolated or systemic?
+   - Does it affect other components?
+   - Has this happened before?
+
+2. **Similar Pattern Search**
+   ```bash
+   # Search for similar patterns in codebase
+   grep -r "similar_pattern" src/
+   ```
+
+3. **Dependency Check**
+   - What depends on the broken code?
+   - What does the broken code depend on?
+
+4. **Risk Assessment**
+   - What could break if we fix this?
+   - Are there other places with same bug?
+
+**Output:** Understanding of bug's scope and risk.
+
+---
+
+### Phase 3: HYPOTHESIS & TESTING 🧪
+
+**Goal:** Develop and test fix hypothesis.
+
+**Steps:**
+
+1. **Form Hypothesis**
+   ```
+   "If I change X to Y, then Z should work because..."
+   ```
+   
+   **Good hypothesis includes:**
+   - Specific change
+   - Expected outcome
+   - Reasoning
+
+2. **Design the Fix**
+   - Minimal change principle
+   - Don't fix what isn't broken
+   - Consider edge cases
+
+3. **Mental/Paper Test**
+   - Walk through the code with fix
+   - Does it address root cause?
+   - Any side effects?
+
+4. **Create Test Case**
+   - Before implementing fix, write test that fails
+   - Test should pass after fix
+   - Include edge cases
+
+**Output:** Tested hypothesis ready for implementation.
+
+---
+
+### Phase 4: IMPLEMENTATION & VERIFICATION ✅
+
+**Goal:** Apply fix and verify it works.
+
+**Steps:**
+
+1. **Implement the Fix**
+   - Apply minimal necessary changes
+   - Add comments explaining WHY (not just what)
+   - Follow project coding standards
+
+2. **Run Existing Tests**
+   ```bash
+   # All tests must pass
+   npm test    # or pytest, etc.
+   ```
+
+3. **Run New Test Case**
+   - Test you wrote in Phase 3 should now pass
+   - Verify fix addresses root cause
+
+4. **Verify No Regression**
+   - Related functionality still works
+   - No new errors introduced
+   - Performance not degraded
+
+5. **Documentation**
+   - Update relevant docs if needed
+   - Consider adding to known issues/patterns
+
+**Output:** Verified fix with passing tests.
+
+---
+
+## Debugging Decision Tree
+
+```
+Bug Report Received
+        │
+        ▼
+┌─────────────────┐
+│ Can reproduce?  │
+└────────┬────────┘
+    YES  │  NO
+         │  └──► Gather more info, check logs, ask for steps
+         ▼
+┌─────────────────┐
+│ Error obvious?  │
+└────────┬────────┘
+    YES  │  NO
+         │  └──► Phase 1: Root Cause Investigation
+         ▼
+Quick fix
+         │
+         ▼
+┌─────────────────┐
+│ Fix verified?   │
+└────────┬────────┘
+    YES  │  NO
+         │  └──► Return to investigation
+         ▼
+    Complete ✓
+```
+
+---
+
+## Guidelines
+
+### DO ✅
+- Read the full stack trace
+- Reproduce before fixing
+- Change one thing at a time
+- Test after each change
+- Keep notes during investigation
+- Ask "WHY" at least 3 times
+
+### DON'T ❌
+- Assume you know the cause
+- Make multiple changes at once
+- Skip testing
+- Ignore "unrelated" errors
+- Rush to deploy fix
+- Delete old code without understanding it
+
+---
+
+## Common Patterns
+
+### Pattern: Off-by-One Error
+
+**When:** Array/loop issues, boundary conditions
+
+**Detection:**
+- Works for most cases, fails at edges
+- Index out of bounds errors
+- Missing first/last item
+
+**Solution:**
+- Check `<` vs `<=`
+- Check starting index (0 vs 1)
+- Verify array length handling
+
+### Pattern: Async/Timing Issue
+
+**When:** Race conditions, inconsistent failures
+
+**Detection:**
+- Works sometimes, fails other times
+- Different behavior in different environments
+- Issues with "slow" operations
+
+**Solution:**
+- Add proper await/promises
+- Check for missing error handling
+- Consider operation ordering
+
+### Pattern: Null/Undefined Reference
+
+**When:** Missing data, optional fields
+
+**Detection:**
+- "Cannot read property of undefined"
+- Works with some data, not others
+- Fails after recent data changes
+
+**Solution:**
+- Add null checks
+- Use optional chaining (?.)
+- Validate data at entry points
+
+---
+
+## Anti-Patterns (AVOID)
+
+### Anti-Pattern: "It Works on My Machine"
+
+**Problem:** Not investigating environment differences.
+
+**Instead:** 
+- Compare environments systematically
+- Check versions, configs, dependencies
+- Document environment requirements
+
+### Anti-Pattern: "Shotgun Debugging"
+
+**Problem:** Changing random things hoping something works.
+
+**Instead:**
+- Form hypothesis first
+- Test ONE change at a time
+- Keep track of what you tried
+
+### Anti-Pattern: "It's Fixed Now" (No Verification)
+
+**Problem:** Assuming fix works without testing.
+
+**Instead:**
+- Always run tests
+- Verify the exact scenario that failed
+- Check for regressions
+
+---
+
+## Success Criteria
+
+Before claiming the bug is fixed:
+
+- [ ] Root cause identified and documented
+- [ ] Fix addresses root cause (not just symptom)
+- [ ] Test case written that would catch this bug
+- [ ] All existing tests pass
+- [ ] New test passes
+- [ ] No regressions in related functionality
+- [ ] Fix is reviewable (clear, minimal, documented)
+- [ ] User can verify the fix works
+
+---
+
+## Related Skills
+
+- `skills/kilo-kit/debugging/root-cause/` - For deeper root cause analysis
+- `skills/kilo-kit/debugging/verification/` - For thorough verification
+- `skills/kilo-kit/quality/testing/` - For writing better tests
+
+---
+
+*Systematic Debugging Skill v1.0.0 — Understand before you fix*