feat: add verification methodology and writing plans skills

2026-06-11 20:54:56 +03:00 · 2025-11-29 23:23:04 +07:00
parent 96d9217c31
commit 3c224790f9
80 changed files with 30860 additions and 0 deletions
@@ -0,0 +1,312 @@
+---
+title: /debug
+description: Analyze and debug errors, exceptions, and unexpected behavior
+---
+
+# /debug - Debug Command
+
+## Purpose
+
+Analyze and debug errors, exceptions, or unexpected behavior with systematic investigation and root cause analysis. This is a streamlined version of `/fix` focused on diagnosis and investigation.
+
+## Usage
+
+```bash
+/debug [error message or description]
+```
+
+## Arguments
+
+- `[error message]` - Stack trace or error output
+- `[description]` - Natural language description of unexpected behavior
+
+## How It Works
+
+The `/debug` command follows a systematic 3-step debugging process:
+
+### Step 1: Analyze Error
+
+1. **Parse Error Message and Stack Trace**
+   - Extracts error type (TypeError, ValueError, etc.)
+   - Identifies file and line number
+   - Reads stack trace for execution path
+
+2. **Identify Error Location**
+   - Pinpoints the exact failing line
+   - Examines surrounding code
+   - Checks function context
+
+3. **Understand Error Type**
+   - Categorizes error (logic, runtime, type, etc.)
+   - Identifies common causes for this error type
+   - Notes relevant language-specific behavior
+
+### Step 2: Investigate
+
+1. **Trace Execution Path**
+   - Follows code flow from entry to error
+   - Maps variable states at each step
+   - Identifies where state becomes invalid
+
+2. **Check Related Code**
+   - Examines caller functions
+   - Reviews recent changes to area
+   - Searches for similar patterns
+
+3. **Form Hypotheses**
+   - Lists possible root causes
+   - Ranks by likelihood
+   - Identifies tests to validate each hypothesis
+
+### Step 3: Fix
+
+1. **Implement Minimal Fix**
+   - Addresses root cause
+   - Keeps changes focused
+   - Preserves existing behavior
+
+2. **Verify Fix Works**
+   - Tests the specific error case
+   - Runs related tests
+   - Checks for side effects
+
+3. **Add Regression Test**
+   - Creates test that would catch this bug
+   - Documents the error scenario
+   - Ensures test fails without fix
+
+## Debug Output Format
+
+```markdown
+## Debug Report
+
+### Error
+```
+TypeError: Cannot read property 'email' of undefined
+  at getUserEmail (src/services/UserService.ts:45)
+  at processUser (src/api/users.ts:23)
+```
+
+### Analysis
+The error occurs when trying to access `user.email` but `user` is undefined.
+
+### Location
+**File**: `src/services/UserService.ts`
+**Line**: 45
+**Function**: `getUserEmail`
+
+### Execution Trace
+1. API receives request → `processUser()`
+2. Calls `getUserEmail(userId)`
+3. Inside getUserEmail:
+   ```typescript
+   const user = this.fetchUser(userId); // Missing await!
+   return user.email; // user is a Promise, not User object
+   ```
+
+### Root Cause
+**Missing `await` keyword** - `fetchUser()` is async but wasn't awaited, so `user` is a Promise object instead of a User object.
+
+### Hypotheses Tested
+1. ✅ Missing await - Confirmed by checking function signature
+2. ❌ User doesn't exist - Would be null, not undefined
+3. ❌ Database error - Would throw different error
+
+### Fix
+```typescript
+// Before
+async getUserEmail(userId: string) {
+  const user = this.fetchUser(userId);
+  return user.email;
+}
+
+// After
+async getUserEmail(userId: string) {
+  const user = await this.fetchUser(userId);
+  if (!user) {
+    throw new NotFoundError(`User ${userId} not found`);
+  }
+  return user.email;
+}
+```
+
+### Verification
+```bash
+# Test the fix
+pnpm test src/services/UserService.test.ts
+
+# Run full suite
+pnpm test
+```
+
+### Prevention
+Added regression test: `test_getUserEmail_awaits_user_fetch`
+```
+
+## Common Debug Patterns
+
+### Null/Undefined Errors
+
+```typescript
+// Symptom
+Cannot read property 'X' of undefined
+
+// Common Causes
+- Missing await on async function
+- Object not initialized
+- API returned null
+- Array/object access out of bounds
+
+// Investigation
+1. Check if value should exist
+2. Trace where it's set
+3. Verify async operations
+```
+
+### Type Errors
+
+```python
+# Symptom
+TypeError: unsupported operand type(s) for +: 'int' and 'str'
+
+# Common Causes
+- Mixed types in operation
+- Missing type conversion
+- Unexpected input type
+
+# Investigation
+1. Print types at error line
+2. Check input sources
+3. Verify type conversions
+```
+
+### Race Conditions
+
+```typescript
+// Symptom
+Intermittent failures, works sometimes
+
+// Common Causes
+- Async operations out of order
+- Shared state without locking
+- Component unmounted during async
+
+// Investigation
+1. Add logging to trace timing
+2. Check for missing awaits
+3. Look for shared mutable state
+```
+
+### Infinite Loops/Recursion
+
+```python
+# Symptom
+RecursionError: maximum recursion depth exceeded
+
+# Common Causes
+- Missing base case
+- Base case never reached
+- Infinite loop condition
+
+# Investigation
+1. Check base/termination condition
+2. Verify condition can be met
+3. Add iteration counter logging
+```
+
+## Flags
+
+| Flag | Description | Example |
+|------|-------------|---------|
+| `--depth=[1-5]` | Investigation depth (1=quick, 5=exhaustive) | `--depth=4` |
+| `--trace` | Show detailed execution trace | `--trace` |
+| `--hypothesis` | Show all hypotheses considered | `--hypothesis` |
+| `--format=[fmt]` | Output format (concise/detailed) | `--format=concise` |
+
+### Flag Examples
+
+```bash
+# Quick debug with minimal output
+/debug --depth=1 --format=concise "error message"
+
+# Deep investigation with full trace
+/debug --depth=5 --trace --hypothesis "intermittent failure"
+
+# Detailed analysis
+/debug --format=detailed "TypeError in auth.ts"
+```
+
+## Examples
+
+### Runtime Error
+
+**Input:**
+```bash
+/debug IndexError: list index out of range in process_items at line 42
+```
+
+**Output:**
+1. Identifies array access issue
+2. Traces loop bounds
+3. Finds off-by-one error
+4. Suggests fix with correct range
+
+### Unexpected Behavior
+
+**Input:**
+```bash
+/debug "User authentication succeeds but session not created"
+```
+
+**Output:**
+1. Traces auth flow
+2. Finds session creation after response sent
+3. Identifies async timing issue
+4. Recommends await before response
+
+### Intermittent Issue
+
+**Input:**
+```bash
+/debug --depth=5 "Test fails randomly, passes on retry"
+```
+
+**Output:**
+1. Analyzes for race conditions
+2. Checks for time-dependent logic
+3. Reviews shared state access
+4. Identifies missing await in test setup
+
+## When to Use
+
+Use `/debug` when you need to:
+
+- **Investigate an error** without immediately fixing it
+- **Understand why** something breaks
+- **Diagnose intermittent** issues
+- **Trace execution** paths
+- **Form hypotheses** about root causes
+
+Use `/fix` instead when you want to:
+
+- Fix the issue immediately
+- Add regression tests
+- Complete the full fix workflow
+
+## Deliverables
+
+After running `/debug`, you receive:
+
+1. **Error Analysis** - Detailed breakdown of the error
+2. **Execution Trace** - Step-by-step flow to error
+3. **Root Cause** - Explanation of why it fails
+4. **Hypotheses** - Tested theories about cause
+5. **Fix Recommendation** - Suggested solution (optional)
+6. **Prevention Strategy** - How to avoid similar issues
+
+## Related Commands
+
+- [/fix](/claudekit/commands/fix) - Complete fix workflow with tests
+- [/test](/claudekit/commands/test) - Generate tests after debugging
+- [/review](/claudekit/commands/review) - Review code for potential issues
+- [/refactor](/claudekit/commands/refactor) - Improve code after fix