aigroup-workflow 2.1.2 → 2.2.1

package/skills/backend/debugging-wizard/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: debugging-wizard
+description: Parses error messages, traces execution flow through stack traces, correlates log entries to identify failure points, and applies systematic hypothesis-driven methodology to isolate and resolve bugs. Use when investigating errors, analyzing stack traces, finding root causes of unexpected behavior, troubleshooting crashes, or performing log analysis, error investigation, or root cause analysis.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: quality
+  triggers: debug, error, bug, exception, traceback, stack trace, troubleshoot, not working, crash, fix issue
+  role: specialist
+  scope: analysis
+  output-format: analysis
+  related-skills: test-master, fullstack-guardian, monitoring-expert
+---
+
+# Debugging Wizard
+
+Expert debugger applying systematic methodology to isolate and resolve issues in any codebase.
+
+## Core Workflow
+
+1. **Reproduce** - Establish consistent reproduction steps
+2. **Isolate** - Narrow down to smallest failing case
+3. **Hypothesize and test** - Form testable theories, verify/disprove each one
+4. **Fix** - Implement and verify solution
+5. **Prevent** - Add tests/safeguards against regression
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+<!-- Systematic Debugging row adapted from obra/superpowers by Jesse Vincent (@obra), MIT License -->
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Debugging Tools | `references/debugging-tools.md` | Setting up debuggers by language |
+| Common Patterns | `references/common-patterns.md` | Recognizing bug patterns |
+| Strategies | `references/strategies.md` | Binary search, git bisect, time travel |
+| Quick Fixes | `references/quick-fixes.md` | Common error solutions |
+| Systematic Debugging | `references/systematic-debugging.md` | Complex bugs, multiple failed fixes, root cause analysis |
+
+## Constraints
+
+### MUST DO
+- Reproduce the issue first
+- Gather complete error messages and stack traces
+- Test one hypothesis at a time
+- Document findings for future reference
+- Add regression tests after fixing
+- Remove all debug code before committing
+
+### MUST NOT DO
+- Guess without testing
+- Make multiple changes at once
+- Skip reproduction steps
+- Assume you know the cause
+- Debug in production without safeguards
+- Leave console.log/debugger statements in code
+
+## Common Debugging Commands
+
+**Python (pdb)**
+```bash
+python -m pdb script.py          # launch debugger
+# inside pdb:
+# b 42          — set breakpoint at line 42
+# n             — step over
+# s             — step into
+# p some_var    — print variable
+# bt            — print full traceback
+```
+
+**JavaScript (Node.js)**
+```bash
+node --inspect-brk script.js     # pause at first line, attach Chrome DevTools
+# In Chrome: open chrome://inspect → click "inspect"
+# Sources panel: add breakpoints, watch expressions, step through
+```
+
+**Git bisect (regression hunting)**
+```bash
+git bisect start
+git bisect bad                   # current commit is broken
+git bisect good v1.2.0           # last known good tag/commit
+# Git checks out midpoint — test, then:
+git bisect good   # or: git bisect bad
+# Repeat until git identifies the first bad commit
+git bisect reset
+```
+
+**Go (delve)**
+```bash
+dlv debug ./cmd/server           # build & attach
+# (dlv) break main.go:55
+# (dlv) continue
+# (dlv) print myVar
+```
+
+## Output Templates
+
+When debugging, provide:
+1. **Root Cause**: What specifically caused the issue
+2. **Evidence**: Stack trace, logs, or test that proves it
+3. **Fix**: Code change that resolves it
+4. **Prevention**: Test or safeguard to prevent recurrence

package/skills/backend/debugging-wizard/references/common-patterns.md

@@ -0,0 +1,132 @@
+# Common Bug Patterns
+
+## Pattern Recognition
+
+| Pattern | Symptom | Likely Cause |
+|---------|---------|--------------|
+| Race condition | Intermittent failures | Missing await, async timing |
+| Off-by-one | Missing first/last item | `<` vs `<=`, array bounds |
+| Null reference | "undefined is not..." | Missing null check |
+| Memory leak | Growing memory | Uncleaned listeners/intervals |
+| N+1 queries | Slow with more data | Fetching in loop |
+| Type coercion | Unexpected behavior | `==` instead of `===` |
+| Closure issue | Wrong variable value | Loop variable capture |
+| Stale state | Old value used | React state closure |
+
+## Race Condition
+
+```typescript
+// BUG: Race condition
+let data;
+fetchData().then(result => { data = result; });
+console.log(data); // undefined!
+
+// FIX: Await the result
+const data = await fetchData();
+console.log(data);
+```
+
+## Off-by-One
+
+```typescript
+// BUG: Skips last element
+for (let i = 0; i < array.length - 1; i++) { }
+
+// FIX: Include last element
+for (let i = 0; i < array.length; i++) { }
+
+// BUG: Array index out of bounds
+const last = array[array.length]; // undefined
+
+// FIX: Correct index
+const last = array[array.length - 1];
+```
+
+## Null Reference
+
+```typescript
+// BUG: Crashes if user is null
+const name = user.profile.name;
+
+// FIX: Optional chaining
+const name = user?.profile?.name ?? 'Unknown';
+
+// FIX: Guard clause
+if (!user?.profile) {
+  return 'Unknown';
+}
+return user.profile.name;
+```
+
+## Memory Leak
+
+```typescript
+// BUG: Listener never removed
+useEffect(() => {
+  window.addEventListener('resize', handleResize);
+}, []);
+
+// FIX: Cleanup function
+useEffect(() => {
+  window.addEventListener('resize', handleResize);
+  return () => window.removeEventListener('resize', handleResize);
+}, []);
+
+// BUG: Interval never cleared
+setInterval(pollData, 1000);
+
+// FIX: Store and clear
+const intervalId = setInterval(pollData, 1000);
+return () => clearInterval(intervalId);
+```
+
+## Closure in Loop
+
+```typescript
+// BUG: All callbacks use i = 5
+for (var i = 0; i < 5; i++) {
+  setTimeout(() => console.log(i), 100);
+}
+
+// FIX: Use let (block scoped)
+for (let i = 0; i < 5; i++) {
+  setTimeout(() => console.log(i), 100);
+}
+
+// FIX: Capture in closure
+for (var i = 0; i < 5; i++) {
+  ((j) => setTimeout(() => console.log(j), 100))(i);
+}
+```
+
+## React Stale State
+
+```typescript
+// BUG: count is stale in closure
+const [count, setCount] = useState(0);
+useEffect(() => {
+  setInterval(() => {
+    setCount(count + 1); // Always uses initial count
+  }, 1000);
+}, []);
+
+// FIX: Use functional update
+setCount(prev => prev + 1);
+
+// FIX: Include in dependency array with cleanup
+useEffect(() => {
+  const id = setInterval(() => setCount(c => c + 1), 1000);
+  return () => clearInterval(id);
+}, []);
+```
+
+## Quick Reference
+
+| Symptom | First Check |
+|---------|-------------|
+| "undefined is not..." | Null check missing |
+| Works sometimes | Race condition |
+| Wrong value in callback | Closure/stale state |
+| Gets slower over time | Memory leak, N+1 |
+| Off by one item | Loop bounds, array index |
+| Type mismatch | `==` vs `===`, coercion |

package/skills/backend/debugging-wizard/references/debugging-tools.md

@@ -0,0 +1,140 @@
+# Debugging Tools
+
+## Debuggers by Language
+
+| Language | Debugger | Start Command |
+|----------|----------|---------------|
+| TypeScript/JS | Node Inspector | `node --inspect` |
+| Python | pdb/ipdb | `python -m pdb` |
+| Go | Delve | `dlv debug` |
+| Rust | rust-gdb/lldb | `rust-gdb ./target/debug/app` |
+| Java | JDB/IDE | IDE debugger |
+
+## Node.js / TypeScript
+
+```bash
+# Start with inspector
+node --inspect dist/main.js
+
+# Break on first line
+node --inspect-brk dist/main.js
+
+# With ts-node
+node --inspect -r ts-node/register src/main.ts
+```
+
+```typescript
+// In code
+debugger; // Breakpoint
+
+// Quick print
+console.log({ variable }); // Shows name and value
+console.table(arrayOfObjects); // Table format
+console.trace('Called from'); // Stack trace
+```
+
+## Python
+
+```bash
+# Start debugger
+python -m pdb script.py
+
+# Post-mortem on exception
+python -m pdb -c continue script.py
+```
+
+```python
+# In code
+breakpoint()  # Python 3.7+
+import pdb; pdb.set_trace()  # Older Python
+
+# Quick print
+print(f"{variable=}")  # Python 3.8+ shows name and value
+
+# Rich debugging
+from rich import inspect
+inspect(object, methods=True)
+```
+
+### pdb Commands
+
+| Command | Action |
+|---------|--------|
+| `n` | Next line |
+| `s` | Step into |
+| `c` | Continue |
+| `l` | List code |
+| `p expr` | Print expression |
+| `pp expr` | Pretty print |
+| `w` | Where (stack) |
+| `q` | Quit |
+
+## Go
+
+```bash
+# Start delve
+dlv debug ./cmd/app
+
+# Attach to running process
+dlv attach <pid>
+
+# Debug test
+dlv test ./pkg/...
+```
+
+```go
+// Quick print
+log.Printf("%+v", variable) // With field names
+fmt.Printf("%#v\n", variable) // Go syntax representation
+
+// Spew for complex structures
+import "github.com/davecgh/go-spew/spew"
+spew.Dump(variable)
+```
+
+### Delve Commands
+
+| Command | Action |
+|---------|--------|
+| `break main.go:42` | Set breakpoint |
+| `continue` | Continue |
+| `next` | Next line |
+| `step` | Step into |
+| `print var` | Print variable |
+| `goroutines` | List goroutines |
+
+## VS Code Debug Config
+
+```json
+// .vscode/launch.json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug TypeScript",
+      "program": "${workspaceFolder}/src/main.ts",
+      "preLaunchTask": "tsc: build",
+      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
+    },
+    {
+      "type": "python",
+      "request": "launch",
+      "name": "Debug Python",
+      "program": "${workspaceFolder}/main.py",
+      "console": "integratedTerminal"
+    }
+  ]
+}
+```
+
+## Quick Reference
+
+| Need | Tool |
+|------|------|
+| Breakpoint in code | `debugger;` / `breakpoint()` |
+| Print with name | `console.log({x})` / `print(f"{x=}")` |
+| Stack trace | `console.trace()` / `traceback.print_stack()` |
+| Inspect object | `console.dir(obj)` / `dir(obj)` |
+| Step through | IDE debugger or CLI debugger |

package/skills/backend/debugging-wizard/references/quick-fixes.md

@@ -0,0 +1,177 @@
+# Quick Fixes
+
+## TypeError: Cannot read property 'x' of undefined
+
+```typescript
+// Error
+user.profile.name
+// user or profile is undefined
+
+// Fix: Optional chaining
+user?.profile?.name
+
+// Fix: Default value
+user?.profile?.name ?? 'Unknown'
+
+// Fix: Guard clause
+if (!user?.profile) {
+  return null;
+}
+return user.profile.name;
+```
+
+## Unhandled Promise Rejection
+
+```typescript
+// Error
+fetchData().then(process);
+// What if fetchData rejects?
+
+// Fix: Add catch
+fetchData()
+  .then(process)
+  .catch(error => {
+    console.error('Fetch failed:', error);
+  });
+
+// Fix: try/catch with await
+try {
+  const data = await fetchData();
+  await process(data);
+} catch (error) {
+  console.error('Operation failed:', error);
+}
+```
+
+## React: Too Many Re-renders
+
+```typescript
+// Error: Calling setState during render
+function Component() {
+  const [count, setCount] = useState(0);
+  setCount(count + 1); // Infinite loop!
+}
+
+// Fix: Use useEffect for side effects
+function Component() {
+  const [count, setCount] = useState(0);
+  useEffect(() => {
+    setCount(c => c + 1);
+  }, []); // Only on mount
+}
+
+// Error: Object/array in dependency array
+useEffect(() => {}, [{ a: 1 }]); // New object every render!
+
+// Fix: Memoize or use primitives
+const config = useMemo(() => ({ a: 1 }), []);
+useEffect(() => {}, [config]);
+```
+
+## CORS Error
+
+```typescript
+// Browser blocks cross-origin request
+
+// Fix 1: Server - Add CORS headers
+app.use(cors({
+  origin: 'http://localhost:3000',
+  credentials: true,
+}));
+
+// Fix 2: Proxy in development (Vite)
+// vite.config.ts
+export default {
+  server: {
+    proxy: {
+      '/api': 'http://localhost:8000',
+    },
+  },
+};
+```
+
+## Maximum Call Stack Size Exceeded
+
+```typescript
+// Error: Infinite recursion
+function factorial(n) {
+  return n * factorial(n - 1); // No base case!
+}
+
+// Fix: Add base case
+function factorial(n) {
+  if (n <= 1) return 1;
+  return n * factorial(n - 1);
+}
+
+// Error: Circular dependency in objects
+const a = {};
+const b = { ref: a };
+a.ref = b;
+JSON.stringify(a); // Fails!
+
+// Fix: Break circular reference
+JSON.stringify(a, (key, value) => {
+  if (key === 'ref') return '[Circular]';
+  return value;
+});
+```
+
+## Module Not Found
+
+```bash
+# Error: Cannot find module 'x'
+
+# Fix 1: Install the package
+npm install x
+
+# Fix 2: Check import path
+import x from './x';     # Relative - needs ./
+import x from 'x';       # Package - no ./
+
+# Fix 3: Check file extension
+import x from './x.js';  # ESM may need extension
+
+# Fix 4: Clear cache
+rm -rf node_modules package-lock.json
+npm install
+```
+
+## Async/Await Issues
+
+```typescript
+// Error: await in non-async function
+function getData() {
+  const data = await fetch('/api'); // SyntaxError!
+}
+
+// Fix: Mark function as async
+async function getData() {
+  const data = await fetch('/api');
+}
+
+// Error: forEach doesn't await
+items.forEach(async item => {
+  await process(item); // Doesn't wait!
+});
+
+// Fix: Use for...of
+for (const item of items) {
+  await process(item);
+}
+
+// Fix: Use Promise.all for parallel
+await Promise.all(items.map(item => process(item)));
+```
+
+## Quick Reference
+
+| Error Message | Likely Fix |
+|--------------|------------|
+| Cannot read property of undefined | Optional chaining `?.` |
+| Unhandled promise rejection | Add `.catch()` or try/catch |
+| Too many re-renders | Remove setState from render |
+| CORS error | Add CORS headers on server |
+| Maximum call stack | Add recursion base case |
+| Module not found | Check path, install package |
+| await in non-async | Add `async` keyword |

package/skills/backend/debugging-wizard/references/strategies.md

@@ -0,0 +1,142 @@
+# Debugging Strategies
+
+## Binary Search
+
+Divide and conquer to find the bug location.
+
+```markdown
+1. Comment out/disable half the code
+2. Test if bug still occurs
+3. If yes: bug is in remaining half
+4. If no: bug is in disabled half
+5. Repeat until isolated
+```
+
+```typescript
+// Example: Bug in data processing pipeline
+async function process(data) {
+  const step1 = await transform(data);
+  // Bug somewhere below?
+
+  const step2 = await validate(step1);
+  console.log('After step2:', step2); // Check here
+
+  const step3 = await enrich(step2);
+  const step4 = await save(step3);
+  return step4;
+}
+```
+
+## Minimal Reproduction
+
+Strip away everything until only the bug remains.
+
+```markdown
+1. Create new minimal project
+2. Add only code needed to reproduce
+3. Remove dependencies one by one
+4. Simplify inputs to smallest failing case
+5. Document exact reproduction steps
+```
+
+```typescript
+// Instead of debugging full app
+// Create minimal test case:
+const input = { id: null }; // Minimal failing input
+const result = processUser(input);
+console.log(result); // Isolate the exact failure
+```
+
+## Git Bisect
+
+Find the commit that introduced the bug.
+
+```bash
+# Start bisect
+git bisect start
+
+# Mark current commit as bad
+git bisect bad
+
+# Mark known good commit
+git bisect good v1.0.0
+
+# Git checks out middle commit
+# Test and mark:
+git bisect good  # or
+git bisect bad
+
+# Repeat until found
+# Git will say: "abc123 is the first bad commit"
+
+# End bisect
+git bisect reset
+```
+
+```bash
+# Automated bisect with test script
+git bisect start HEAD v1.0.0
+git bisect run npm test
+```
+
+## Time Travel Debugging
+
+Work backwards from the failure.
+
+```markdown
+1. Start at the error/failure point
+2. What value caused it? Where did that come from?
+3. Trace backwards through the code
+4. Find where the value diverged from expected
+```
+
+```typescript
+// Error: Cannot read 'name' of undefined at line 45
+
+// Line 45: const name = user.name;
+// Q: Why is user undefined?
+
+// Line 40: const user = users.find(u => u.id === id);
+// Q: Why didn't find() return a user?
+
+// Check: Is the id correct? Are users populated?
+console.log({ id, users, user });
+```
+
+## Rubber Duck Debugging
+
+Explain the problem step by step.
+
+```markdown
+1. State what the code should do
+2. Explain what it actually does
+3. Walk through the code line by line
+4. Describe what each line does
+5. The discrepancy often becomes obvious
+```
+
+## Delta Debugging
+
+When something recently broke.
+
+```bash
+# Check what changed
+git diff HEAD~5..HEAD
+
+# Check specific file history
+git log -p --follow -- src/problematic-file.ts
+
+# Find when file last worked
+git log --oneline -- src/problematic-file.ts
+```
+
+## Quick Reference
+
+| Strategy | Best For |
+|----------|----------|
+| Binary Search | Unknown bug location |
+| Minimal Repro | Complex bugs, reporting |
+| Git Bisect | Regression bugs |
+| Time Travel | Known error location |
+| Rubber Duck | Logic errors |
+| Delta Debug | Recent breakage |