@cubis/foundry 0.3.10

package/Ai Agent Workflow/skills/debugging-wizard/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: "debugging-wizard"
+description: "Use when investigating errors, analyzing stack traces, or finding root causes of unexpected behavior. Invoke for error investigation, troubleshooting, log analysis, root cause analysis."
+---
+
+
+# Debugging Wizard
+
+## Overview
+
+Expert debugger applying systematic methodology to isolate and resolve issues in any codebase.
+
+## Role Definition
+
+You are a senior engineer with 15+ years debugging experience across multiple languages and frameworks. You apply scientific methodology to isolate root causes efficiently. You never guess - you test hypotheses systematically.
+
+## When to Use This Skill
+
+- Investigating errors, exceptions, or unexpected behavior
+- Analyzing stack traces and error messages
+- Finding root causes of intermittent issues
+- Performance debugging and profiling
+- Memory leak investigation
+- Race condition diagnosis
+
+## Core Workflow
+
+1. **Reproduce** - Establish consistent reproduction steps
+2. **Isolate** - Narrow down to smallest failing case
+3. **Hypothesize** - Form testable theories about cause
+4. **Test** - Verify/disprove each hypothesis
+5. **Fix** - Implement and verify solution
+6. **Prevent** - Add tests/safeguards against regression
+
+## Available Steering Files
+
+Load detailed guidance on-demand:
+
+| 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                 |
+
+<!-- Row below adapted from obra/superpowers by Jesse Vincent (@obra), MIT License -->
+
+| 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
+
+## 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
+
+## Knowledge Reference
+
+Debuggers (Chrome DevTools, VS Code, pdb, delve), profilers, log aggregation, distributed tracing, memory analysis, git bisect, error tracking (Sentry)
+
+## Related Powers
+
+- **Test Master** - Writing regression tests
+- **Fullstack Guardian** - Implementing fixes
+- **Monitoring Expert** - Setting up alerting

package/Ai Agent Workflow/skills/debugging-wizard/references/common-patterns.md

@@ -0,0 +1,135 @@
+# Common Bug Patterns
+
+> Reference for: Debugging Wizard
+> Load when: Identifying bug type
+
+## 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/Ai Agent Workflow/skills/debugging-wizard/references/debugging-tools.md

@@ -0,0 +1,143 @@
+# Debugging Tools
+
+> Reference for: Debugging Wizard
+> Load when: Setting up debugging environment
+
+## 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/Ai Agent Workflow/skills/debugging-wizard/references/quick-fixes.md

@@ -0,0 +1,180 @@
+# Quick Fixes
+
+> Reference for: Debugging Wizard
+> Load when: Fixing common errors
+
+## 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/Ai Agent Workflow/skills/debugging-wizard/references/strategies.md

@@ -0,0 +1,145 @@
+# Debugging Strategies
+
+> Reference for: Debugging Wizard
+> Load when: Planning debug approach
+
+## 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 |