@simplysm/sd-claude 13.0.78 → 13.0.81

package/claude/skills/sd-debug/defense-in-depth.md

@@ -1,128 +0,0 @@
-# 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.

package/claude/skills/sd-debug/find-polluter.sh

@@ -1,64 +0,0 @@
-#!/bin/bash
-# Bisection script for finding which test creates unwanted files/directories
-# 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_or_dir_to_check> <test_pattern>"
-    echo "Example: $0 '.git' 'src/**/*.test.ts'"
-    exit 1
-fi
-
-CHECK_PATH="$1"
-TEST_PATTERN="$2"
-
-# Detect package manager: pnpm -> yarn -> npm (default)
-if [ -f "pnpm-lock.yaml" ]; then PM="pnpm"
-elif [ -f "yarn.lock" ]; then PM="yarn"
-else PM="npm"
-fi
-
-# Find all test files matching pattern
-readarray -t TEST_FILES < <(find . -path "$TEST_PATTERN" -type f)
-
-if [ ${#TEST_FILES[@]} -eq 0 ]; then
-    echo "No test files found matching pattern: $TEST_PATTERN"
-    exit 1
-fi
-
-echo "Found ${#TEST_FILES[@]} test files"
-echo "Checking for pollution: $CHECK_PATH"
-echo ""
-
-for test_file in "${TEST_FILES[@]}"; do
-    # Skip if pollution already exists
-    if [ -e "$CHECK_PATH" ]; then
-        echo "⚠️  Pollution already exists, skipping to avoid false positive"
-        echo "   Please remove $CHECK_PATH and re-run"
-        exit 1
-    fi
-
-    echo "Testing: $test_file"
-
-    # Run the test
-    $PM test "$test_file" > /dev/null 2>&1 || true
-
-    # Check if pollution appeared
-    if [ -e "$CHECK_PATH" ]; then
-        echo ""
-        echo "🔴 FOUND POLLUTER: $test_file"
-        echo ""
-        echo "This test created: $CHECK_PATH"
-        ls -la "$CHECK_PATH" 2>/dev/null || echo "(path exists but can't stat)"
-        echo ""
-        echo "Investigate with:"
-        echo "  $PM test '$test_file' -- --reporter=verbose"
-        echo "  git diff"
-        exit 0
-    fi
-done
-
-echo ""
-echo "✅ No polluter found - all ${#TEST_FILES[@]} tests are clean"

package/claude/skills/sd-debug/root-cause-tracing.md

@@ -1,168 +0,0 @@
-# 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
-
-```mermaid
-flowchart TD
-    A{"Bug appears deep in stack?"} -->|yes| B{"Can trace backwards?"}
-    B -->|yes| C[Trace to original trigger]
-    B -->|"no - dead end"| D[Fix at symptom point]
-    C --> E["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** (detect PM: `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, otherwise → npm):
-
-```bash
-$PM 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` in this directory:
-
-```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
-
-```mermaid
-flowchart TD
-    A(["Found immediate cause"]) --> B{"Can trace one level up?"}
-    B -->|yes| C["Trace backwards"]
-    B -->|no| D["NEVER fix just the symptom"]:::danger
-    C --> E{"Is this the source?"}
-    E -->|"no - keeps going"| C
-    E -->|yes| F["Fix at source"]
-    F --> G["Add validation at each layer"]
-    G --> H(("Bug impossible"))
-
-    classDef danger fill:#f00,color:#fff
-```
-
-**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

package/claude/skills/sd-discuss/SKILL.md

@@ -1,91 +0,0 @@
----
-name: sd-discuss
-description: "Technical discussion with industry research (explicit invocation only)"
----
-
-# Standards-Based Technical Discussion
-
-## Overview
-
-Facilitate balanced, evidence-based technical discussions by researching industry standards and project conventions BEFORE forming opinions.
-
-## The Process
-
-### 1. Understand the Question
-
-Ask ONE question to understand the user's motivation:
-
-- What problem triggered this question?
-- What constraints matter most?
-
-### 2. Research Before Opinions
-
-**MANDATORY before forming any opinion:**
-
-**Project research** (Read/Grep tools):
-
-- Read the actual source code related to the question
-- Check CLAUDE.md for project conventions
-- Find similar patterns in the codebase
-
-**Industry research** (WebSearch tool):
-
-- Search for current community consensus and trends
-- Check relevant specifications (TC39, W3C, RFCs)
-- Find recent benchmarks, migration case studies, or survey data
-- Check how popular libraries/frameworks approach this
-
-### 3. Present Balanced Arguments
-
-Present each option as if you were **advocating FOR it**. Equal depth, equal effort.
-
-For each option:
-
-- **Industry support**: Libraries, standards, and projects that use this approach (with sources)
-- **Technical advantages**: Concrete benefits with evidence
-- **When this wins**: Specific scenarios where this is clearly better
-
-### 4. Project Context Analysis
-
-- How does the current codebase align with each option?
-- What would migration cost look like?
-- What existing patterns favor one approach?
-
-### 5. Decision Criteria
-
-Provide a decision matrix — NOT a single recommendation:
-
-| Criteria            | Option A | Option B |
-| ------------------- | -------- | -------- |
-| Industry alignment  | ...      | ...      |
-| Project consistency | ...      | ...      |
-| Migration cost      | ...      | ...      |
-| Long-term trend     | ...      | ...      |
-
-Then ask: "Which criteria matter most to you?"
-
-## Key Rules
-
-1. **Research FIRST, opinion LAST** — No opinions before WebSearch + project code reading
-2. **Equal advocacy** — Each option gets the same depth of analysis
-3. **Evidence over intuition** — Cite sources, show data
-4. **No "obvious" answers** — If it were obvious, there'd be no discussion
-5. **Interactive** — Ask questions, don't monologue
-6. **Project-aware** — Ground the discussion in the actual codebase
-
-## Red Flags - STOP and Research More
-
-- Presenting one side with more depth than the other
-- Claiming "industry standard" without citing sources
-- Recommending without checking the project's current patterns
-- Giving a conclusion without asking user's priorities
-
-## Common Mistakes
-
-| Mistake                                  | Fix                                         |
-| ---------------------------------------- | ------------------------------------------- |
-| Jump to recommendation                   | Research first, present balanced options    |
-| "Industry standard is X" without sources | WebSearch for actual data and citations     |
-| Ignoring project context                 | Read codebase patterns before discussing    |
-| Monologue instead of discussion          | Ask about user's priorities and constraints |
-| Treating "modern" as "better"            | Evaluate on actual trade-offs, not trends   |

package/claude/skills/sd-explore/SKILL.md

@@ -1,118 +0,0 @@
----
-name: sd-explore
-description: "Use when analyzing a large codebase (30+ files) that must be read comprehensively. Splits files into groups and dispatches parallel sub-agents to avoid context compaction and information loss."
----
-
-# sd-explore
-
-## Overview
-
-Split a large codebase into manageable groups and dispatch parallel sub-agents, each reading its assigned files and writing results to disk. The calling skill then reads result files instead of raw source — no context compaction, no information loss.
-
-**Core principle:** Never read 30+ files in a single agent context. Split, parallelize, write to files.
-
-**Important:** This is a workflow the **orchestrator (main agent)** follows directly. Do NOT delegate the entire sd-explore workflow to a sub-agent — only the orchestrator has `Agent` tool access to dispatch parallel sub-agents. The orchestrator globs files, splits groups, and dispatches `Agent(Explore)` calls itself.
-
-## When to Use
-
-- Codebase analysis covering 30+ source files
-- Called by other skills (sd-review, sd-brainstorm, sd-debug, sd-plan) that need comprehensive file reading
-- Any task where reading all files sequentially would risk context compaction
-
-**When NOT to use:**
-- < 30 files — a single agent can handle it directly
-- Targeted search for a specific function/class — use Grep/Glob instead
-
-## Input
-
-The calling skill provides:
-
-1. **Target path** — directory to explore (e.g., `packages/solid/src`)
-2. **Name** — caller identifier for output filenames (e.g., `review`, `debug`, `brainstorm`)
-3. **File patterns** — glob patterns to match (default: `**/*.ts`, `**/*.tsx`; exclude `node_modules`, `dist`)
-4. **Analysis instructions** — free-form text describing what each sub-agent should do
-
-The analysis instructions are passed verbatim to each sub-agent. They can request anything: tags, summaries, pattern searches, specific questions, etc.
-
-## Workflow
-
-### Step 1: Discover Files
-
-Glob all matching files under the target path.
-
-- **< 30 files**: Run a single `Agent(subagent_type=Explore)` with the analysis instructions. No splitting needed. Write result to `.tmp/explore/{dt}_{name}.md` (where `{dt}` is current datetime as `yyyyMMddHHmmss`).
-- **>= 30 files**: Proceed to Step 2.
-
-### Step 2: Split Into Groups
-
-Split files into groups of **~30 files each**.
-
-**Splitting strategy:**
-
-1. List all subdirectories under target
-2. Group files by subdirectory, keeping each group around 30 files
-3. If the target is mostly flat (few subdirectories), group by file proximity (alphabetical chunks)
-4. Adjacent small directories can be merged into one group
-5. A single large directory (40+ files) should be split into multiple groups
-
-**Goal:** Balanced groups where related files stay together.
-
-### Step 3: Dispatch Parallel Agents
-
-Launch one `Agent(subagent_type=Explore)` per group, **all in a single message** for true parallelism.
-
-Each agent receives:
-
-```
-You are exploring a section of a codebase. Read ALL assigned files and write your analysis to the output file.
-
-**Assigned files:**
-[list of file paths for this group]
-
-**Analysis instructions:**
-[caller's free-form instructions, passed verbatim]
-
-**Output file:** .tmp/explore/{dt}_{name}-{group_index}.md
-
-Read every assigned file. Write your complete analysis to the output file. Do NOT skip files.
-```
-
-### Step 4: Return Result Paths
-
-After all agents complete, return the list of output file paths to the calling skill.
-
-The calling skill reads these files to get the analysis results — the main context stays clean.
-
-## Output Format
-
-Each sub-agent writes to its assigned output file. The format is determined by the caller's analysis instructions. If no specific format is requested, use:
-
-```markdown
-# Explore: [directory names]
-
-## File Summaries
-- `path/to/file.ts` — Brief description
-
-## Analysis
-[Results per the caller's instructions]
-```
-
-## Why Sub-Agents Matter
-
-The value is **context isolation**, not just speed:
-
-- **Without sub-agents**: Reading 100+ files in the main context causes compaction. Earlier file analyses get dropped, degrading quality of later analysis steps (review, planning, etc.)
-- **With sub-agents**: Each sub-agent reads ~30 files in its own context, writes results to disk, and exits. The main context only reads the summary files — staying clean for subsequent work.
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Delegating the entire workflow to a sub-agent | The orchestrator follows sd-explore directly — only it can dispatch parallel `Agent` calls |
-| Reading all files in one agent | Split into groups of ~30, dispatch parallel agents |
-| Not writing results to files | Each agent MUST write to its output file — this is what prevents context bloat |
-| Groups too large (50+) | Keep groups around 30 files for reliable coverage |
-| Groups too small (5-10) | Wastes agent overhead — merge small directories |
-| Not passing analysis instructions verbatim | The caller's instructions go to each agent as-is |
-| Running agents sequentially | Launch all agents in a single message for parallelism |
-| Skipping Step 1 threshold check | < 30 files don't need splitting — avoid unnecessary overhead |