oh-my-customcodex 0.1.0

package/templates/.claude/skills/systematic-debugging/condition-based-waiting.md

@@ -0,0 +1,240 @@
+# Condition-Based Waiting
+
+<!-- Source: https://github.com/tmdgusya/engineering-disciplines (MIT License) -->
+
+## Overview
+
+Arbitrary delays (`sleep`, `setTimeout`, `await new Promise(r => setTimeout(r, 1000))`) are a debugging anti-pattern. They hide timing issues, make tests slow, and still fail intermittently.
+
+**Core principle:** Replace arbitrary delays with condition-based polling that waits for the actual state you need.
+
+## When to Use
+
+**Use when:**
+- Tests use `await sleep(1000)` or similar arbitrary waits
+- Code has `setTimeout` for "giving time" to async operations
+- Tests are flaky because timing depends on system speed
+- You need to wait for: file to exist, process to start, server to be ready, database record to appear
+
+## The Problem with Arbitrary Delays
+
+```typescript
+// ❌ Arbitrary delay - fragile and slow
+await fs.writeFile(path, content);
+await sleep(500); // "Give it time to write"
+const result = await fs.readFile(path);
+
+// Problems:
+// 1. 500ms may not be enough on slow systems
+// 2. 500ms is always wasted on fast systems
+// 3. The actual condition (file readable) is never verified
+```
+
+## The Solution: Condition-Based Waiting
+
+```typescript
+// ✓ Condition-based - fast and reliable
+await fs.writeFile(path, content);
+await waitUntil(() => fs.access(path).then(() => true).catch(() => false));
+const result = await fs.readFile(path);
+
+// Benefits:
+// 1. Proceeds as soon as condition is met (fast on fast systems)
+// 2. Has a timeout for safety (catches real failures)
+// 3. The actual condition is explicit and verified
+```
+
+## Core Implementation
+
+```typescript
+interface WaitOptions {
+  timeout?: number;      // Max wait time in ms (default: 5000)
+  interval?: number;     // Poll interval in ms (default: 100)
+  message?: string;      // Error message on timeout
+}
+
+async function waitUntil(
+  condition: () => boolean | Promise<boolean>,
+  options: WaitOptions = {}
+): Promise<void> {
+  const { timeout = 5000, interval = 100, message = 'Condition not met' } = options;
+  const deadline = Date.now() + timeout;
+
+  while (Date.now() < deadline) {
+    const result = await condition();
+    if (result) return;
+    await new Promise(resolve => setTimeout(resolve, interval));
+  }
+
+  throw new Error(`waitUntil timeout after ${timeout}ms: ${message}`);
+}
+```
+
+See `condition-based-waiting-example.ts` for the complete implementation with all utilities.
+
+## Common Patterns
+
+### Wait for File to Exist
+
+```typescript
+// ❌ Arbitrary delay
+await triggerFileCreation();
+await sleep(1000);
+const content = await fs.readFile(outputPath, 'utf-8');
+
+// ✓ Condition-based
+await triggerFileCreation();
+await waitUntil(
+  () => fs.access(outputPath).then(() => true).catch(() => false),
+  { timeout: 5000, message: `File not created: ${outputPath}` }
+);
+const content = await fs.readFile(outputPath, 'utf-8');
+```
+
+### Wait for Process to Start
+
+```typescript
+// ❌ Arbitrary delay
+startServer();
+await sleep(2000); // "Give server time to start"
+const response = await fetch('http://localhost:3000/health');
+
+// ✓ Condition-based
+startServer();
+await waitUntil(
+  async () => {
+    try {
+      const res = await fetch('http://localhost:3000/health');
+      return res.ok;
+    } catch {
+      return false;
+    }
+  },
+  { timeout: 10000, message: 'Server did not start within 10s' }
+);
+const response = await fetch('http://localhost:3000/health');
+```
+
+### Wait for Database Record
+
+```typescript
+// ❌ Arbitrary delay
+await triggerAsyncOperation();
+await sleep(500);
+const record = await db.find({ id: expectedId });
+
+// ✓ Condition-based
+await triggerAsyncOperation();
+await waitUntil(
+  async () => {
+    const record = await db.find({ id: expectedId });
+    return record !== null;
+  },
+  { timeout: 3000, message: `Record ${expectedId} not created` }
+);
+const record = await db.find({ id: expectedId });
+```
+
+### Wait for Log Output
+
+```typescript
+// ❌ Arbitrary delay
+process.spawn('my-command');
+await sleep(1000);
+expect(logOutput).toContain('Server started');
+
+// ✓ Condition-based
+const logOutput: string[] = [];
+const proc = process.spawn('my-command');
+proc.stdout.on('data', (chunk) => logOutput.push(chunk.toString()));
+
+await waitUntil(
+  () => logOutput.some(line => line.includes('Server started')),
+  { timeout: 10000, message: 'Server start message not seen in logs' }
+);
+```
+
+### Wait for Count to Reach Expected Value
+
+```typescript
+// ❌ Arbitrary delay
+await triggerBatchOperation();
+await sleep(2000);
+const items = await db.findAll();
+expect(items.length).toBe(10);
+
+// ✓ Condition-based
+await triggerBatchOperation();
+await waitUntil(
+  async () => {
+    const items = await db.findAll();
+    return items.length >= 10;
+  },
+  { timeout: 5000, message: 'Batch did not complete: expected 10 items' }
+);
+const items = await db.findAll();
+expect(items.length).toBe(10);
+```
+
+## Choosing Timeout and Interval Values
+
+| Scenario | Timeout | Interval | Rationale |
+|----------|---------|----------|-----------|
+| File write | 2s | 50ms | Fast local I/O |
+| Process start | 10s | 200ms | Process startup varies |
+| HTTP server ready | 15s | 300ms | Server may need to compile |
+| Database record | 3s | 100ms | DB writes are fast |
+| CI environment | 2-3x local | same | CI is often slower |
+
+**Rule of thumb:**
+- Interval: 10-20% of expected wait time, minimum 50ms
+- Timeout: 3-5x the typical wait time
+- Add a buffer for CI: multiply timeout by 2-3x
+
+## Testing the Waiters Themselves
+
+```typescript
+// Test that waitUntil resolves when condition becomes true
+it('resolves when condition becomes true', async () => {
+  let ready = false;
+  setTimeout(() => { ready = true; }, 100);
+
+  await expect(
+    waitUntil(() => ready, { timeout: 1000 })
+  ).resolves.toBeUndefined();
+});
+
+// Test that waitUntil rejects on timeout
+it('rejects with timeout error when condition never met', async () => {
+  await expect(
+    waitUntil(() => false, { timeout: 100, message: 'test condition' })
+  ).rejects.toThrow('waitUntil timeout after 100ms: test condition');
+});
+```
+
+## Migration Guide
+
+When refactoring existing `sleep` calls:
+
+1. **Identify what the sleep is "waiting for"** — read surrounding code
+2. **Find the observable state change** — what becomes true when the operation completes?
+3. **Replace with `waitUntil(condition)`** — poll for that state
+4. **Set appropriate timeout** — 3-5x the typical wait time
+5. **Add descriptive message** — what should have happened?
+
+```typescript
+// Before
+await startProcess();
+await sleep(2000);
+checkResult();
+
+// After - step 1: what is sleep waiting for? Process to be ready.
+// After - step 2: observable state? Process responds to health check.
+// After - step 3-5:
+await startProcess();
+await waitUntil(
+  () => isProcessReady(),
+  { timeout: 10000, message: 'Process did not become ready' }
+);
+checkResult();
+```

package/templates/.claude/skills/systematic-debugging/defense-in-depth.md

@@ -0,0 +1,252 @@
+# Defense-in-Depth Validation
+
+<!-- Source: https://github.com/tmdgusya/engineering-disciplines (MIT License) -->
+
+## Overview
+
+Instead of fixing bugs reactively, add validation at every layer so bugs become structurally impossible. Each layer catches what the previous layer missed.
+
+**Core principle:** Don't just fix the bug. Add a guard that makes the bug impossible at every layer that should have caught it.
+
+## When to Use
+
+**Use when:**
+- The same class of bug keeps appearing in different places
+- A bug got through multiple layers that should have caught it
+- You want to prevent regression of a hard-to-reproduce bug
+- Building new features where invalid state could cause harm
+
+## The Four Layers
+
+### Layer 1: Input Validation (Entry Points)
+
+Validate at the boundary where data enters your system.
+
+```typescript
+// ❌ No validation - bug can enter the system
+async function createSession(projectDir: string): Promise<Session> {
+  return new Session(projectDir);
+}
+
+// ✓ Validate at entry - bug is caught immediately
+async function createSession(projectDir: string): Promise<Session> {
+  if (!projectDir || projectDir.trim() === '') {
+    throw new Error(`createSession: projectDir must be a non-empty string, got: ${JSON.stringify(projectDir)}`);
+  }
+  return new Session(projectDir);
+}
+```
+
+**What to validate at entry points:**
+- Non-empty strings for required path/name fields
+- Valid ranges for numeric values
+- Required fields exist in objects
+- File/directory exists when required
+
+### Layer 2: Constructor Guards (Object Creation)
+
+Validate in constructors so objects can never be created in invalid state.
+
+```typescript
+// ❌ Object can be created with invalid state
+class Session {
+  constructor(private projectDir: string) {}
+}
+
+// ✓ Constructor prevents invalid state
+class Session {
+  constructor(private projectDir: string) {
+    if (!projectDir || projectDir.trim() === '') {
+      throw new Error(
+        `Session: projectDir must be non-empty, got: ${JSON.stringify(projectDir)}`
+      );
+    }
+  }
+}
+```
+
+**Constructor guard pattern:**
+```typescript
+class WorktreeManager {
+  constructor(private baseDir: string, private sessionId: string) {
+    if (!baseDir) throw new Error('WorktreeManager: baseDir is required');
+    if (!sessionId) throw new Error('WorktreeManager: sessionId is required');
+  }
+}
+```
+
+### Layer 3: Method Preconditions (Critical Operations)
+
+Add guards before operations that could cause harm if called with bad state.
+
+```typescript
+// ❌ No precondition - git init could run in wrong directory
+async function initializeWorktree(): Promise<void> {
+  await execFileAsync('git', ['init'], { cwd: this.projectDir });
+}
+
+// ✓ Precondition - verify state is valid before dangerous operation
+async function initializeWorktree(): Promise<void> {
+  if (!this.projectDir) {
+    throw new Error(
+      `initializeWorktree: projectDir is not set. ` +
+      `This likely means the object was created with an empty path.`
+    );
+  }
+  await execFileAsync('git', ['init'], { cwd: this.projectDir });
+}
+```
+
+**When to add method preconditions:**
+- Before file system operations (read, write, delete)
+- Before network calls with user-provided data
+- Before database writes
+- Before spawning processes with user-provided arguments
+
+### Layer 4: Test Assertions (Regression Prevention)
+
+Add assertions in tests that would catch the bug early and clearly.
+
+```typescript
+// ❌ Test doesn't verify the path is correct
+it('should initialize session', async () => {
+  const session = await createSession(tempDir);
+  expect(session).toBeDefined();
+});
+
+// ✓ Test verifies the critical invariant
+it('should initialize session with correct project directory', async () => {
+  const session = await createSession(tempDir);
+  expect(session).toBeDefined();
+  // Assert the invariant that was violated
+  expect(session.projectDir).toBe(tempDir);
+  expect(session.projectDir).not.toBe('');
+  expect(session.projectDir).not.toBe(process.cwd());
+});
+```
+
+**Test assertion patterns:**
+```typescript
+// Assert paths are absolute and within expected location
+expect(path.isAbsolute(result.dir)).toBe(true);
+expect(result.dir.startsWith(tempDir)).toBe(true);
+
+// Assert values match what was provided (not defaults or fallbacks)
+expect(result.name).toBe(providedName);
+expect(result.id).not.toBe('');
+```
+
+## Applying Defense-in-Depth
+
+When you find a bug, don't just fix it. Add guards at ALL four layers:
+
+### Step 1: Fix the immediate bug
+
+```typescript
+// Fix the actual bug first
+const context = setupCoreTest();
+await context.initialize(); // Add the missing initialization
+```
+
+### Step 2: Add input validation
+
+```typescript
+export function createProject(name: string, dir: string): Project {
+  if (!dir || dir.trim() === '') {
+    throw new Error(`createProject: dir must be non-empty`);
+  }
+  return new Project(name, dir);
+}
+```
+
+### Step 3: Add constructor guard
+
+```typescript
+class Project {
+  constructor(name: string, dir: string) {
+    if (!dir) throw new Error('Project: dir is required');
+    this.dir = dir;
+  }
+}
+```
+
+### Step 4: Add method precondition
+
+```typescript
+async clone(): Promise<Project> {
+  if (!this.dir) {
+    throw new Error('Project.clone: dir must be set before cloning');
+  }
+  // ... clone logic
+}
+```
+
+### Step 5: Add regression test
+
+```typescript
+it('should not use empty string as project dir', async () => {
+  const project = await createProject('test', tempDir);
+  expect(project.dir).toBe(tempDir);
+  expect(project.dir).not.toBe('');
+});
+```
+
+## Error Message Quality
+
+Good error messages reduce debugging time from hours to minutes.
+
+```typescript
+// ❌ Unhelpful error
+throw new Error('Invalid directory');
+
+// ✓ Helpful error - includes what, where, why, and the actual value
+throw new Error(
+  `WorktreeManager.createWorktree: projectDir must be an absolute path to an existing directory.\n` +
+  `Got: ${JSON.stringify(projectDir)}\n` +
+  `Hint: Check that the project was initialized before calling this method.`
+);
+```
+
+**Error message template:**
+```
+{ClassName}.{methodName}: {what went wrong}.
+Got: {actual value}
+Expected: {what was expected}
+Hint: {likely cause or fix}
+```
+
+## Common Validation Patterns
+
+```typescript
+// Non-empty string
+if (!value || typeof value !== 'string' || value.trim() === '') {
+  throw new Error(`${context}: ${fieldName} must be a non-empty string, got: ${JSON.stringify(value)}`);
+}
+
+// Positive number
+if (typeof value !== 'number' || value <= 0 || !isFinite(value)) {
+  throw new Error(`${context}: ${fieldName} must be a positive number, got: ${value}`);
+}
+
+// Valid enum value
+const validValues = ['draft', 'active', 'archived'] as const;
+if (!validValues.includes(value)) {
+  throw new Error(`${context}: ${fieldName} must be one of [${validValues.join(', ')}], got: ${JSON.stringify(value)}`);
+}
+
+// Required object field
+if (!obj || typeof obj !== 'object') {
+  throw new Error(`${context}: ${fieldName} must be an object, got: ${typeof obj}`);
+}
+```
+
+## Result
+
+After applying defense-in-depth to the session initialization bug:
+
+- Layer 1 caught: Invalid input at `createSession()` entry point
+- Layer 2 caught: Empty string in `Session` constructor
+- Layer 3 caught: Unset `projectDir` before `git init`
+- Layer 4 caught: Test assertion verified correct path was used
+
+The bug class is now structurally impossible — it would be caught at the earliest possible point with a clear error message pointing to the root cause.

package/templates/.claude/skills/systematic-debugging/find-polluter.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# find-polluter.sh — Binary search for test pollution source
+# Source: https://github.com/tmdgusya/engineering-disciplines (MIT License)
+#
+# Usage: ./find-polluter.sh <test-runner-cmd> <failing-test-pattern>
+# Example: ./find-polluter.sh "bun test" "should not have side effects"
+#
+# How it works:
+# 1. Runs all tests to confirm the failure exists
+# 2. Binary searches through the test list to find which test causes pollution
+# 3. Reports the polluter and its position in the test order
+#
+# Requirements: Test runner must support running specific test files
+# Works with: jest, vitest, bun test, mocha
+
+set -euo pipefail
+
+# Configuration
+TEST_CMD="${1:-bun test}"
+FAILING_TEST="${2:-}"
+TIMEOUT="${3:-60}"  # seconds per test run
+
+if [[ -z "$FAILING_TEST" ]]; then
+  echo "Usage: $0 <test-runner-cmd> <failing-test-pattern> [timeout-seconds]"
+  echo "Example: $0 'bun test' 'should not have side effects' 60"
+  exit 1
+fi
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+log_info() { echo -e "${GREEN}[INFO]${NC} $*"; }
+log_warn() { echo -e "${YELLOW}[WARN]${NC} $*"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $*"; }
+
+# Step 1: Collect all test files
+log_info "Collecting test files..."
+mapfile -t ALL_TEST_FILES < <(find . -name "*.test.ts" -o -name "*.test.js" -o -name "*.spec.ts" -o -name "*.spec.js" | grep -v node_modules | sort)
+
+if [[ ${#ALL_TEST_FILES[@]} -eq 0 ]]; then
+  log_error "No test files found"
+  exit 1
+fi
+
+log_info "Found ${#ALL_TEST_FILES[@]} test files"
+
+# Step 2: Confirm the failure exists when running all tests
+log_info "Confirming failure exists with full test suite..."
+if timeout "$TIMEOUT" bash -c "$TEST_CMD 2>&1" | grep -q "$FAILING_TEST"; then
+  if timeout "$TIMEOUT" bash -c "$TEST_CMD 2>&1" | grep -q "FAIL\|✗\|× "; then
+    log_info "Failure confirmed in full suite"
+  else
+    log_warn "Test pattern found but no failures detected - check pattern matches failing test"
+  fi
+else
+  log_error "Failing test pattern '$FAILING_TEST' not found in test output"
+  log_error "Check that the test exists and the pattern is correct"
+  exit 1
+fi
+
+# Step 3: Confirm the test passes in isolation
+FAILING_TEST_FILE=""
+for f in "${ALL_TEST_FILES[@]}"; do
+  if grep -l "$FAILING_TEST" "$f" &>/dev/null; then
+    FAILING_TEST_FILE="$f"
+    break
+  fi
+done
+
+if [[ -z "$FAILING_TEST_FILE" ]]; then
+  log_error "Could not find file containing test: $FAILING_TEST"
+  exit 1
+fi
+
+log_info "Failing test is in: $FAILING_TEST_FILE"
+log_info "Testing in isolation..."
+
+if timeout "$TIMEOUT" bash -c "$TEST_CMD $FAILING_TEST_FILE 2>&1" | grep -q "FAIL\|✗\|× "; then
+  log_warn "Test fails even in isolation - this is not a pollution issue"
+  log_warn "The test itself has a bug, not pollution from another test"
+  exit 0
+else
+  log_info "Test passes in isolation - pollution confirmed"
+fi
+
+# Step 4: Binary search for the polluter
+# Remove the failing test file from the list of candidates
+CANDIDATE_FILES=()
+for f in "${ALL_TEST_FILES[@]}"; do
+  if [[ "$f" != "$FAILING_TEST_FILE" ]]; then
+    CANDIDATE_FILES+=("$f")
+  fi
+done
+
+log_info "Binary searching through ${#CANDIDATE_FILES[@]} candidate files..."
+
+low=0
+high=$((${#CANDIDATE_FILES[@]} - 1))
+found_polluter=""
+
+while [[ $low -le $high ]]; do
+  mid=$(( (low + high) / 2 ))
+
+  # Test with files from 0 to mid, plus the failing test
+  SUBSET=("${CANDIDATE_FILES[@]:0:$((mid + 1))}" "$FAILING_TEST_FILE")
+
+  log_info "Testing subset of $((mid + 1)) files (indices 0-$mid) + failing test..."
+
+  # Build file list for the test command
+  FILE_LIST="${SUBSET[*]}"
+
+  if timeout "$TIMEOUT" bash -c "$TEST_CMD $FILE_LIST 2>&1" | grep -q "FAIL\|✗\|× "; then
+    log_info "Failure reproduced with subset 0-$mid"
+    high=$((mid - 1))
+    found_polluter="${CANDIDATE_FILES[$mid]}"
+  else
+    log_info "No failure with subset 0-$mid, polluter is in higher range"
+    low=$((mid + 1))
+  fi
+done
+
+# Step 5: Report results
+echo ""
+echo "=========================================="
+if [[ -n "$found_polluter" ]]; then
+  log_info "POLLUTER FOUND: $found_polluter"
+  echo ""
+  echo "This test file causes '$FAILING_TEST' to fail when run before it."
+  echo ""
+  echo "To verify:"
+  echo "  $TEST_CMD $found_polluter $FAILING_TEST_FILE"
+  echo ""
+  echo "Next steps:"
+  echo "  1. Open $found_polluter"
+  echo "  2. Look for: global state mutations, missing afterEach/afterAll cleanup"
+  echo "  3. Check for: database records not deleted, files not cleaned up"
+  echo "  4. Check for: environment variables set but not restored"
+  echo "  5. Add proper cleanup in afterEach/afterAll"
+else
+  log_warn "Polluter not found via binary search"
+  log_warn "This may happen if multiple tests together cause the pollution"
+  log_warn "Try running subsets manually to narrow down"
+fi
+echo "=========================================="