Add new methodology skills for enhanced development workflows

.claude/skills/methodology/systematic-debugging/SKILL.md

@@ -0,0 +1,258 @@
+# Systematic Debugging
+
+## Description
+
+Four-phase debugging methodology centered on finding root causes before implementing fixes. The foundational principle: **"NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST"**
+
+## When to Use
+
+- Bug reports with unclear cause
+- Errors appearing in production
+- Tests failing unexpectedly
+- Intermittent/flaky issues
+- Complex multi-component failures
+
+---
+
+## The Four Phases
+
+### Phase 1: Root Cause Investigation
+
+**Goal**: Understand what's happening before attempting to fix.
+
+**Steps**:
+
+1. **Read error messages carefully**
+   ```markdown
+   - What is the exact error message?
+   - What is the stack trace?
+   - What line numbers are mentioned?
+   - What values are shown?
+   ```
+
+2. **Reproduce consistently**
+   ```markdown
+   - Can you trigger the bug reliably?
+   - What exact steps reproduce it?
+   - What environment is required?
+   - Document the reproduction steps
+   ```
+
+3. **Track recent changes**
+   ```markdown
+   - What changed recently?
+   - git log --oneline -20
+   - When did it last work?
+   - What was deployed?
+   ```
+
+4. **Gather evidence**
+   ```markdown
+   - Collect logs
+   - Check monitoring/metrics
+   - Review related code
+   - Note any patterns
+   ```
+
+5. **Add instrumentation** (for multi-component systems)
+   ```typescript
+   // Add diagnostic logging at each boundary
+   console.error('[DEBUG] Input received:', JSON.stringify(input));
+   console.error('[DEBUG] After validation:', JSON.stringify(validated));
+   console.error('[DEBUG] Before database call:', JSON.stringify(query));
+   console.error('[DEBUG] Database result:', JSON.stringify(result));
+   ```
+
+---
+
+### Phase 2: Pattern Analysis
+
+**Goal**: Find comparable working code to identify differences.
+
+**Steps**:
+
+1. **Find working code**
+   ```markdown
+   - Is there similar functionality that works?
+   - What did this code look like before?
+   - Are there reference implementations?
+   ```
+
+2. **Study reference thoroughly**
+   ```markdown
+   - How does the working version handle this case?
+   - What dependencies does it use?
+   - What assumptions does it make?
+   ```
+
+3. **Identify differences**
+   ```markdown
+   - What's different between working and broken?
+   - Configuration differences?
+   - Data differences?
+   - Environment differences?
+   ```
+
+4. **Understand dependencies**
+   ```markdown
+   - What does this code depend on?
+   - What depends on this code?
+   - Are dependencies behaving correctly?
+   ```
+
+---
+
+### Phase 3: Hypothesis and Testing
+
+**Goal**: Form and test a specific theory about the cause.
+
+**Steps**:
+
+1. **Form specific hypothesis**
+   ```markdown
+   Write it down explicitly:
+   "The bug occurs because [X] causes [Y] when [Z]"
+
+   Example:
+   "The bug occurs because the cache returns stale data
+    when the user's session expires during an active request"
+   ```
+
+2. **Test with minimal changes**
+   ```markdown
+   - Change ONE variable at a time
+   - Don't combine multiple fixes
+   - Verify results after each change
+   ```
+
+3. **Validate hypothesis**
+   ```markdown
+   - Does the fix address the hypothesis?
+   - Can you explain WHY it works?
+   - Does it make the bug impossible, not just unlikely?
+   ```
+
+---
+
+### Phase 4: Implementation
+
+**Goal**: Fix properly with verification.
+
+**Steps**:
+
+1. **Write failing test first**
+   ```typescript
+   it('should handle expired session during request', () => {
+     // Reproduce the bug scenario
+     const session = createExpiredSession();
+     const result = processRequest(session);
+
+     // This should fail before the fix
+     expect(result.error).toBe('SESSION_EXPIRED');
+   });
+   ```
+
+2. **Implement single targeted fix**
+   ```typescript
+   // Fix addresses root cause, not symptom
+   function processRequest(session: Session) {
+     if (session.isExpired()) {
+       return { error: 'SESSION_EXPIRED' };
+     }
+     // ... rest of logic
+   }
+   ```
+
+3. **Verify fix works**
+   ```bash
+   npm test -- --grep "expired session"
+   # Should pass
+   ```
+
+4. **Verify no regressions**
+   ```bash
+   npm test
+   # All tests should pass
+   ```
+
+---
+
+## The Three-Fix Rule
+
+**If three or more fixes fail consecutively, STOP.**
+
+This signals an architectural problem, not a simple bug:
+
+```markdown
+Fix attempt 1: Failed
+Fix attempt 2: Failed
+Fix attempt 3: Failed
+
+STOP: This is not a bug - this is a design problem.
+
+Action: Discuss with user/team before proceeding
+- Explain what's been tried
+- Explain why it's not working
+- Propose architectural changes
+```
+
+---
+
+## Key Principles
+
+### Never Skip Error Details
+
+```markdown
+BAD: "There's an error somewhere"
+GOOD: "TypeError: Cannot read property 'id' of undefined
+       at UserService.getUser (user-service.ts:42)"
+```
+
+### Reproduce Before Investigating
+
+```markdown
+BAD: "I think I know what's wrong" (starts coding)
+GOOD: "Let me reproduce this first" (writes repro steps)
+```
+
+### Trace Backward to Origin
+
+```markdown
+BAD: Fix where error appears
+GOOD: Trace data backward to find where it became invalid
+```
+
+### One Change Per Test
+
+```markdown
+BAD: "I changed A, B, and C - now it works!"
+     (Which one fixed it? Are the others safe?)
+
+GOOD: "I changed A - still broken.
+       I reverted A and changed B - now it works.
+       B was the fix."
+```
+
+---
+
+## Debugging Checklist
+
+Before attempting any fix:
+
+- [ ] Error message fully read and understood
+- [ ] Bug reproduced consistently
+- [ ] Recent changes reviewed
+- [ ] Evidence gathered (logs, traces)
+- [ ] Hypothesis written down
+- [ ] Similar working code identified
+- [ ] Root cause identified (not just symptom)
+
+Before declaring fixed:
+
+- [ ] Failing test written
+- [ ] Fix implemented
+- [ ] Test passes
+- [ ] No regressions (full test suite passes)
+- [ ] Fix explained (can articulate why it works)
+
+---