agent-skill-kit 3.9.135

package/.agent/skills/debug-pro/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: debug-pro
+description: >-
+  Systematic debugging: 4-phase methodology, root-cause tracing, and defense-in-depth verification.
+  Use when fixing bugs, tracing errors, investigating crashes, or diagnosing unexpected behavior.
+  NOT for new feature design or code review (use code-review).
+category: debugging
+triggers: ["debug", "bug", "error", "crash", "exception", "root cause", "investigation", "not working"]
+coordinates_with: ["test-architect", "code-review"]
+success_metrics: ["100% bugs have root cause identified", "< 15m MTTR"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# Debug Pro — Systematic Debugging
+
+> 4 phases. 5 Whys. No random changes. Never claim "fixed" without verification.
+
+---
+
+## 5 Must-Ask Questions (Socratic Gate)
+
+| # | Question | Options |
+|---|----------|---------|
+| 1 | Exact Error Message? | Stack trace / Console output / HTTP status |
+| 2 | Reproduction Steps? | Step-by-step to trigger the bug |
+| 3 | Expected vs Actual? | What should happen vs what happens |
+| 4 | Environment? | Browser / OS / Node version / Staging vs Prod |
+| 5 | Recent Changes? | New deploy / Dependency update / Config change |
+
+---
+
+## Prerequisites
+
+**Required:** None — Debug Pro is a methodology-based skill with no external dependencies.
+
+---
+
+## When to Use
+
+| Situation | Action |
+|-----------|--------|
+| Bug reported | Follow 4-phase methodology from Phase 1 |
+| Error/exception occurs | Root cause tracing with 5 Whys |
+| Crash investigation | Defense-in-depth analysis |
+| Fix validation needed | Verification checklist (Phase 4) |
+| Architecture review | Read `rules/engineering-spec.md` |
+
+---
+
+## System Boundaries
+
+| Owned by This Skill | NOT Owned |
+|---------------------|-----------|
+| 4-phase methodology (Reproduce→Isolate→Understand→Fix&Verify) | Debugger tool execution |
+| 5 Whys root cause analysis | Automated bug detection (→ code-review) |
+| Isolation techniques (git bisect/blame/log) | Test writing (→ test-architect) |
+| Verification checklist (4 items) | Code quality review (→ code-craft) |
+| Red flag detection (5 patterns) | Performance profiling (→ perf-optimizer) |
+| 3 advanced frameworks | Git command execution |
+
+**Pure decision skill:** Produces debugging strategies and checklists. Zero side effects.
+
+---
+
+## 4-Phase Methodology
+
+### Phase 1: Reproduce 🔄
+
+- [ ] Can reproduce consistently
+- [ ] Have minimal reproduction case
+- [ ] Understand expected behavior
+- [ ] Documented environment details
+
+### Phase 2: Isolate 🔍
+
+| Technique | Command | When |
+|-----------|---------|------|
+| Binary search | `git bisect` | Narrow to commit |
+| Recent changes | `git log --oneline -20` | Check recent commits |
+| Blame | `git blame path/to/file` | Find who changed what |
+
+### Phase 3: Understand 🧠 (5 Whys)
+
+```
+1. Why: [First observation]
+2. Why: [Deeper reason]
+3. Why: [Still deeper]
+4. Why: [Getting closer]
+5. Why: [ROOT CAUSE]
+```
+
+**Root cause MUST:** explain ALL symptoms. "It just happens" is NOT valid.
+
+### Phase 4: Fix & Verify ✅
+
+- [ ] Bug no longer reproduces
+- [ ] Related functionality works
+- [ ] No new issues introduced
+- [ ] Regression test added
+
+---
+
+## Phase Transitions (Strict Order)
+
+```
+REPRODUCE → ISOLATE     [reproduction checklist complete]
+ISOLATE → UNDERSTAND    [source narrowed to component]
+UNDERSTAND → FIX_VERIFY [root cause explains all symptoms]
+FIX_VERIFY → RESOLVED   [verification passed + regression test]  // terminal
+FIX_VERIFY → REPRODUCE  [verification failed]
+UNDERSTAND → ISOLATE    [hypothesis disproven]
+ANY_PHASE → REPRODUCE   [red flag detected]
+```
+
+**No phase may be skipped.**
+
+---
+
+## 🚩 Red Flags (Return to Phase 1)
+
+| Pattern | Why It's Wrong |
+|---------|---------------|
+| "Quick fix for now, investigate later" | Skipping root cause analysis |
+| "Just try changing X and see" | Random change without evidence |
+| "It's probably X, let me fix that" | Assumption without verification |
+| "Should work now" / "Seems fixed" | No verification |
+| "Tests pass, we're done" | Tests ≠ complete verification |
+
+---
+
+## Error Taxonomy
+
+| Code | Recoverable | Trigger |
+|------|-------------|---------|
+| `ERR_INVALID_REQUEST_TYPE` | No | Request type not supported |
+| `ERR_MISSING_DESCRIPTION` | Yes | Bug description not provided |
+| `ERR_MISSING_EXPECTED` | Yes | Expected behavior not provided |
+| `ERR_PHASE_SKIP` | No | Attempted to skip a phase |
+| `ERR_INVALID_PHASE` | No | Phase name not recognized |
+| `RED_FLAG` | Yes | Red flag detected; return to Phase 1 |
+
+**Zero internal retries.** Deterministic; same context = same methodology output.
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Random changes hoping to fix | Follow 4-phase methodology |
+| Assume root cause without evidence | Verify with 5 Whys |
+| Claim fixed without testing | Run verification checklist |
+| Stop at symptoms | Dig to root cause |
+| Skip regression test | Add test for every fix |
+
+---
+
+## Audit Logging (OpenTelemetry)
+
+| Event | Metadata Payload | Severity |
+|-------|------------------|----------|
+| `investigation_started` | `{"bug_category": "runtime", "phase": "reproduce"}` | `INFO` |
+| `root_cause_identified` | `{"root_cause": "null check missing", "confidence": "HIGH"}` | `INFO` |
+| `fix_verified` | `{"regression_test_added": true, "similar_patterns": 0}` | `INFO` |
+
+All debug-pro outputs MUST emit `investigation_started`, `root_cause_identified`, or `fix_verified` events when applicable.
+
+---
+
+## 📑 Content Map
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| [defense-in-depth/](defense-in-depth/) | Defense-in-depth analysis framework | Crash investigation |
+| [root-cause-tracing/](root-cause-tracing/) | Root cause tracing framework | Complex bugs |
+| [verification-before-completion/](verification-before-completion/) | Verification framework | Fix validation |
+| [engineering-spec.md](rules/engineering-spec.md) | Full engineering spec | Architecture review |
+
+---
+
+## 🔗 Related
+
+| Item | Type | Purpose |
+|------|------|---------|
+| `test-architect` | Skill | Regression test writing |
+| `code-review` | Skill | Code quality validation |
+| `/diagnose` | Workflow | Debug workflow |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/debug-pro/defense-in-depth/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: Defense-in-Depth Validation
+description: Validate at every layer data passes through to make bugs impossible
+category: debugging-subskill
+triggers: ["defense in depth", "validation layers", "prevent bug", "structural fix"]
+coordinates_with: ["debug-pro", "security-scanner", "test-architect"]
+success_metrics: ["0 recurrent bugs", "4 layers of validation applied"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# Defense-in-Depth Validation
+
+## Overview
+
+When you fix a bug caused by invalid data, adding validation at one place feels sufficient. But that single check can be bypassed by different code paths, refactoring, or mocks.
+
+**Core principle:** Validate at EVERY layer data passes through. Make the bug structurally impossible.
+
+## Why Multiple Layers
+
+Single validation: "We fixed the bug"
+Multiple layers: "We made the bug impossible"
+
+Different layers catch different cases:
+- Entry validation catches most bugs
+- Business logic catches edge cases
+- Environment guards prevent context-specific dangers
+- Debug logging helps when other layers fail
+
+## The Four Layers
+
+### Layer 1: Entry Point Validation
+**Purpose:** Reject obviously invalid input at API boundary
+
+```typescript
+function createProject(name: string, workingDirectory: string) {
+  if (!workingDirectory || workingDirectory.trim() === '') {
+    throw new Error('workingDirectory cannot be empty');
+  }
+  if (!existsSync(workingDirectory)) {
+    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
+  }
+  if (!statSync(workingDirectory).isDirectory()) {
+    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
+  }
+  // ... proceed
+}
+```
+
+### Layer 2: Business Logic Validation
+**Purpose:** Ensure data makes sense for this operation
+
+```typescript
+function initializeWorkspace(projectDir: string, sessionId: string) {
+  if (!projectDir) {
+    throw new Error('projectDir required for workspace initialization');
+  }
+  // ... proceed
+}
+```
+
+### Layer 3: Environment Guards
+**Purpose:** Prevent dangerous operations in specific contexts
+
+```typescript
+async function gitInit(directory: string) {
+  // In tests, refuse git init outside temp directories
+  if (process.env.NODE_ENV === 'test') {
+    const normalized = normalize(resolve(directory));
+    const tmpDir = normalize(resolve(tmpdir()));
+
+    if (!normalized.startsWith(tmpDir)) {
+      throw new Error(
+        `Refusing git init outside temp dir during tests: ${directory}`
+      );
+    }
+  }
+  // ... proceed
+}
+```
+
+### Layer 4: Debug Instrumentation
+**Purpose:** Capture context for forensics
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  logger.debug('About to git init', {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+  // ... proceed
+}
+```
+
+## Applying the Pattern
+
+When you find a bug:
+
+1. **Trace the data flow** - Where does bad value originate? Where used?
+2. **Map all checkpoints** - List every point data passes through
+3. **Add validation at each layer** - Entry, business, environment, debug
+4. **Test each layer** - Try to bypass layer 1, verify layer 2 catches it
+
+## Example from Session
+
+Bug: Empty `projectDir` caused `git init` in source code
+
+**Data flow:**
+1. Test setup → empty string
+2. `Project.create(name, '')`
+3. `WorkspaceManager.createWorkspace('')`
+4. `git init` runs in `process.cwd()`
+
+**Four layers added:**
+- Layer 1: `Project.create()` validates not empty/exists/writable
+- Layer 2: `WorkspaceManager` validates projectDir not empty
+- Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
+- Layer 4: Stack trace logging before git init
+
+**Result:** All 1847 tests passed, bug impossible to reproduce
+
+## Key Insight
+
+All four layers were necessary. During testing, each layer caught bugs the others missed:
+- Different code paths bypassed entry validation
+- Mocks bypassed business logic checks
+- Edge cases on different platforms needed environment guards
+- Debug logging identified structural misuse
+
+**Don't stop at one validation point.** Add checks at every layer.
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [../root-cause-tracing/SKILL.md](../root-cause-tracing/SKILL.md) | Trace to original trigger before adding layers |
+| [../verification-before-completion/SKILL.md](../verification-before-completion/SKILL.md) | Verify fix after adding defense layers |
+| [../SKILL.md](../SKILL.md) | 4-phase methodology overview |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/debug-pro/root-cause-tracing/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: Root Cause Tracing
+description: Systematically trace bugs backward through call stack to find original trigger
+category: debugging-subskill
+triggers: ["stack trace", "trace backward", "find polluter", "root cause tracing"]
+coordinates_with: ["debug-pro", "test-architect"]
+success_metrics: ["100% bugs fixed at root cause", "0 side-effects from tests"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# Root Cause Tracing
+
+## Overview
+
+Bugs often manifest deep in the call stack (git init in wrong directory, file created in wrong location, database opened with wrong path). Your instinct is to fix where the error appears, but that's treating a symptom.
+
+**Core principle:** Trace backward through the call chain until you find the original trigger, then fix at the source.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Bug appears deep in stack?" [shape=diamond];
+    "Can trace backwards?" [shape=diamond];
+    "Fix at symptom point" [shape=box];
+    "Trace to original trigger" [shape=box];
+    "BETTER: Also add defense-in-depth" [shape=box];
+
+    "Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"];
+    "Can trace backwards?" -> "Trace to original trigger" [label="yes"];
+    "Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"];
+    "Trace to original trigger" -> "BETTER: Also add defense-in-depth";
+}
+```
+
+**Use when:**
+- Error happens deep in execution (not at entry point)
+- Stack trace shows long call chain
+- Unclear where invalid data originated
+- Need to find which test/code triggers the problem
+
+## The Tracing Process
+
+### 1. Observe the Symptom
+```
+Error: git init failed in /Users/jesse/project/packages/core
+```
+
+### 2. Find Immediate Cause
+**What code directly causes this?**
+```typescript
+await execFileAsync('git', ['init'], { cwd: projectDir });
+```
+
+### 3. Ask: What Called This?
+```typescript
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  → called by Session.initializeWorkspace()
+  → called by Session.create()
+  → called by test at Project.create()
+```
+
+### 4. Keep Tracing Up
+**What value was passed?**
+- `projectDir = ''` (empty string!)
+- Empty string as `cwd` resolves to `process.cwd()`
+- That's the source code directory!
+
+### 5. Find Original Trigger
+**Where did empty string come from?**
+```typescript
+const context = setupCoreTest(); // Returns { tempDir: '' }
+Project.create('name', context.tempDir); // Accessed before beforeEach!
+```
+
+## Adding Stack Traces
+
+When you can't trace manually, add instrumentation:
+
+```typescript
+// Before the problematic operation
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  console.error('DEBUG git init:', {
+    directory,
+    cwd: process.cwd(),
+    nodeEnv: process.env.NODE_ENV,
+    stack,
+  });
+
+  await execFileAsync('git', ['init'], { cwd: directory });
+}
+```
+
+**Critical:** Use `console.error()` in tests (not logger - may not show)
+
+**Run and capture:**
+```bash
+npm test 2>&1 | grep 'DEBUG git init'
+```
+
+**Analyze stack traces:**
+- Look for test file names
+- Find the line number triggering the call
+- Identify the pattern (same test? same parameter?)
+
+## Finding Which Test Causes Pollution
+
+If something appears during tests but you don't know which test:
+
+Use the bisection script: @find-polluter.sh
+
+```bash
+./find-polluter.sh '.git' 'src/**/*.test.ts'
+```
+
+Runs tests one-by-one, stops at first polluter. See script for usage.
+
+## Real Example: Empty projectDir
+
+**Symptom:** `.git` created in `packages/core/` (source code)
+
+**Trace chain:**
+1. `git init` runs in `process.cwd()` ← empty cwd parameter
+2. WorktreeManager called with empty projectDir
+3. Session.create() passed empty string
+4. Test accessed `context.tempDir` before beforeEach
+5. setupCoreTest() returns `{ tempDir: '' }` initially
+
+**Root cause:** Top-level variable initialization accessing empty value
+
+**Fix:** Made tempDir a getter that throws if accessed before beforeEach
+
+**Also added defense-in-depth:**
+- Layer 1: Project.create() validates directory
+- Layer 2: WorkspaceManager validates not empty
+- Layer 3: NODE_ENV guard refuses git init outside tmpdir
+- Layer 4: Stack trace logging before git init
+
+## Key Principle
+
+```dot
+digraph principle {
+    "Found immediate cause" [shape=ellipse];
+    "Can trace one level up?" [shape=diamond];
+    "Trace backwards" [shape=box];
+    "Is this the source?" [shape=diamond];
+    "Fix at source" [shape=box];
+    "Add validation at each layer" [shape=box];
+    "Bug impossible" [shape=doublecircle];
+    "NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+    "Found immediate cause" -> "Can trace one level up?";
+    "Can trace one level up?" -> "Trace backwards" [label="yes"];
+    "Can trace one level up?" -> "NEVER fix just the symptom" [label="no"];
+    "Trace backwards" -> "Is this the source?";
+    "Is this the source?" -> "Trace backwards" [label="no - keeps going"];
+    "Is this the source?" -> "Fix at source" [label="yes"];
+    "Fix at source" -> "Add validation at each layer";
+    "Add validation at each layer" -> "Bug impossible";
+}
+```
+
+**NEVER fix just where the error appears.** Trace back to find the original trigger.
+
+## Stack Trace Tips
+
+**In tests:** Use `console.error()` not logger - logger may be suppressed
+**Before operation:** Log before the dangerous operation, not after it fails
+**Include context:** Directory, cwd, environment variables, timestamps
+**Capture stack:** `new Error().stack` shows complete call chain
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- Found root cause through 5-level trace
+- Fixed at source (getter validation)
+- Added 4 layers of defense
+- 1847 tests passed, zero pollution
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [find-polluter.sh](find-polluter.sh) | Bisection script to find polluting test |
+| [../defense-in-depth/SKILL.md](../defense-in-depth/SKILL.md) | Add validation layers after finding root cause |
+| [../verification-before-completion/SKILL.md](../verification-before-completion/SKILL.md) | Verify fix completeness |
+| [../SKILL.md](../SKILL.md) | 4-phase methodology overview |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/debug-pro/root-cause-tracing/find-polluter.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# Bisection script to find which test creates unwanted files/state
+# Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern>
+# Example: ./find-polluter.sh '.git' 'src/**/*.test.ts'
+
+set -e
+
+if [ $# -ne 2 ]; then
+  echo "Usage: $0 <file_to_check> <test_pattern>"
+  echo "Example: $0 '.git' 'src/**/*.test.ts'"
+  exit 1
+fi
+
+POLLUTION_CHECK="$1"
+TEST_PATTERN="$2"
+
+echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
+echo "Test pattern: $TEST_PATTERN"
+echo ""
+
+# Get list of test files
+TEST_FILES=$(find . -path "$TEST_PATTERN" | sort)
+TOTAL=$(echo "$TEST_FILES" | wc -l | tr -d ' ')
+
+echo "Found $TOTAL test files"
+echo ""
+
+COUNT=0
+for TEST_FILE in $TEST_FILES; do
+  COUNT=$((COUNT + 1))
+
+  # Skip if pollution already exists
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo "⚠️  Pollution already exists before test $COUNT/$TOTAL"
+    echo "   Skipping: $TEST_FILE"
+    continue
+  fi
+
+  echo "[$COUNT/$TOTAL] Testing: $TEST_FILE"
+
+  # Run the test
+  npm test "$TEST_FILE" > /dev/null 2>&1 || true
+
+  # Check if pollution appeared
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo ""
+    echo "🎯 FOUND POLLUTER!"
+    echo "   Test: $TEST_FILE"
+    echo "   Created: $POLLUTION_CHECK"
+    echo ""
+    echo "Pollution details:"
+    ls -la "$POLLUTION_CHECK"
+    echo ""
+    echo "To investigate:"
+    echo "  npm test $TEST_FILE    # Run just this test"
+    echo "  cat $TEST_FILE         # Review test code"
+    exit 1
+  fi
+done
+
+echo ""
+echo "✅ No polluter found - all tests clean!"
+exit 0

package/.agent/skills/debug-pro/rules/_sections.md

@@ -0,0 +1,15 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Engineering Specification (engineering)
+
+**Impact:** MEDIUM  
+**Description:** Full engineering specification covering contracts, security, and scalability.
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/debug-pro/rules/_template.md

@@ -0,0 +1,32 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
+
+---
+
+⚡ PikaKit v3.9.134