@simplysm/sd-claude 13.0.78 → 13.0.80

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 |

package/claude/skills/sd-plan-dev/SKILL.md

@@ -1,294 +0,0 @@
----
-name: sd-plan-dev
-description: "Parallel execution of plan tasks (explicit invocation only)"
----
-
-# Parallel Plan Execution
-
-Execute plan tasks via parallel implementers with dependency-aware scheduling.
-
-**Core principle:** Dependency analysis + parallel implementers + orchestrator-managed reviews = maximum throughput
-
-## When to Use
-
-```mermaid
-flowchart TD
-    A{Have implementation plan?}
-    A -->|yes| B[sd-plan-dev]
-    A -->|no| C[Manual execution or brainstorm first]
-```
-
-## Execution Method
-
-All execution uses `Task(general-purpose)` for parallel execution.
-
-- **implementer**: `Task(general-purpose, model: min(sonnet, current))` — implements one task, commits, reports
-- **spec reviewer**: `Task(general-purpose)` — dispatched by orchestrator after implementer completes (read-only)
-- **quality reviewer**: `Task(general-purpose)` — dispatched by orchestrator in parallel with spec reviewer (read-only)
-- **final reviewer**: `Task(general-purpose)` — dispatched by orchestrator after all batches complete (read-only)
-
-**Model selection:**
-- **implementer**: use `min(sonnet, current model)`. If the user's current model is haiku, use haiku. Otherwise use sonnet.
-- **All other agents**: inherit current model (no explicit `model` parameter).
-
-Independent tasks run as **parallel Task calls in a single message**. After implementers complete, spec and quality reviews run as **parallel Task calls**.
-
-**CRITICAL: Always launch parallel tasks as multiple Task calls in a single message (foreground parallel).** Never set `run_in_background: true` — it causes Stop hooks to fire prematurely. This rule applies regardless of permission mode (yolo, plan, etc.).
-
-## The Process
-
-```mermaid
-flowchart TD
-    A["Read plan, extract tasks, create TaskCreate"] --> B["Dependency analysis: identify files per task, build graph, group into batches"]
-
-    subgraph BATCH["Per Batch (independent tasks)"]
-        subgraph PAR_IMPL["Parallel implementer Task calls (single message)"]
-            subgraph IMPL["Each Implementer"]
-                C["Implement the task"] --> D{"Questions?"}
-                D -->|yes| E["Return questions to orchestrator"]
-                E --> F["Re-launch with answers"]
-                F --> C
-                D -->|no| G["Commit and report"]
-            end
-        end
-
-        subgraph REVIEW["Orchestrator review loop (per implementer)"]
-            subgraph PAR_REV["Parallel reviewer Task calls (single message)"]
-                H["Task: spec reviewer"]
-                I["Task: quality reviewer"]
-            end
-            J{"Any issues?"}
-            K["Task: implementer fix"]
-            L["Re-review (parallel Task calls)"]
-        end
-    end
-
-    B --> C
-    G --> H
-    G --> I
-    H --> J
-    I --> J
-    J -->|yes| K
-    K --> L
-    L --> J
-    J -->|no| M["Batch integration check (typecheck + lint)"]
-    M --> N{"More batches?"}
-    N -->|"yes, next batch"| C
-    N -->|no| O["Task: final review for entire implementation"]
-    O --> P["Run /simplify on all changed code"]
-    P --> Q{"Changes made?"}
-    Q -->|yes| R["Typecheck + lint affected packages"]
-    R --> S(["Done"])
-    Q -->|no| S
-```
-
-## Dependency Analysis
-
-Before launching tasks, analyze the plan to build a dependency graph:
-
-1. **For each task**: identify which files/modules it will create or modify
-2. **Find overlaps**: tasks touching the same files depend on each other
-3. **Respect logical dependencies**: if task B uses what task A creates, B depends on A
-4. **Group into batches**: tasks with no dependencies between them form one batch
-
-```
-Example: 5 tasks
-  Task 1: creates utils/validator.ts
-  Task 2: creates hooks/useAuth.ts
-  Task 3: creates components/Login.tsx (uses hooks/useAuth.ts)
-  Task 4: modifies utils/validator.ts
-  Task 5: creates api/endpoints.ts
-
-  Batch 1: [Task 1, Task 2, Task 5] — independent, parallel
-  Batch 2: [Task 3] — depends on Task 2
-  Batch 3: [Task 4] — depends on Task 1
-```
-
-## Implementer Prompt
-
-Each implementer receives a prompt based on `./implementer-prompt.md`. Fill in all `[bracketed]` sections before dispatching.
-
-## Reviewer Dispatch
-
-After an implementer completes and reports, the orchestrator dispatches reviewers:
-
-1. Record the implementer's commit SHA and files changed from its report
-2. Dispatch TWO parallel Task calls (single message):
-   - spec reviewer — fill `./spec-reviewer-prompt.md` with task requirements + implementer report
-   - quality reviewer — fill `./code-quality-reviewer-prompt.md` with implementer report + BASE_SHA/HEAD_SHA
-3. If either reviewer returns CHANGES_NEEDED:
-   - Re-dispatch implementer with fix instructions (all issues from both reviewers combined)
-   - After fix, re-dispatch only the failed reviewers (parallel Task calls)
-   - Repeat until both approve
-4. Proceed to next task or batch
-
-## Prompt Templates
-
-- `./implementer-prompt.md` — implementer instructions
-- `./spec-reviewer-prompt.md` — spec compliance review prompt
-- `./code-quality-reviewer-prompt.md` — code quality review prompt
-- `./final-review-prompt.md` — final integration review prompt
-
-## Example Workflow
-
-```
-You: Using sd-plan-dev to execute this plan.
-
-[Read plan file: docs/plans/feature-plan.md]
-[Extract all 5 tasks with full text + create TaskCreate]
-
-[Dependency analysis]
-  Task 1 (validator): no deps
-  Task 2 (auth hook): no deps
-  Task 3 (login component): depends on Task 2
-  Task 4 (validator update): depends on Task 1
-  Task 5 (api endpoints): no deps
-
-  Batch 1: [Task 1, Task 2, Task 5]
-  Batch 2: [Task 3, Task 4]
-
---- Batch 1: parallel implementers ---
-
-[3 parallel implementer Task calls in single message]
-
-  Implementer 1: Implemented validator, tests 5/5 pass → committed
-  Implementer 2: "Should auth use JWT or session?" (question returned)
-  Implementer 5: Implemented endpoints, tests 3/3 pass → committed
-
-[Answer Implementer 2 question: "JWT"]
-[Re-launch Implementer 2 with answer]
-  Implementer 2: Implemented auth hook with JWT, tests 4/4 pass → committed
-
-[Orchestrator dispatches reviewers for each completed implementer]
-
-  Task 1 reviews: [parallel] spec ✅, quality ✅ → Done
-  Task 2 reviews: [parallel] spec ✅, quality ✅ → Done
-  Task 5 reviews: [parallel] spec ✅, quality ❌ (magic number)
-    → Re-dispatch Implementer 5 to fix → committed
-    → Re-review quality ✅ → Done
-
-[Batch 1 complete → integration check]
-
---- Batch 2: parallel implementers ---
-
-[2 parallel implementer Task calls in single message]
-
-  Implementer 3: Implemented login component → committed
-  Implementer 4: Updated validator → committed
-
-[Orchestrator dispatches reviewers]
-
-  Task 3 reviews: [parallel] spec ❌ (missing error state), quality ✅
-    → Re-dispatch Implementer 3 to fix → committed
-    → Re-review spec ✅ → Done
-  Task 4 reviews: [parallel] spec ✅, quality ✅ → Done
-
-[Batch 2 complete → integration check]
-
---- Final ---
-
-[Task: final review for entire implementation]
-Final reviewer: All requirements met, ready to merge
-
-[Run /simplify on all changed code]
-Simplify: extracted shared validation helper, removed 2 duplicate imports
-[typecheck + lint → pass]
-[Commit: refactor: simplify changed code]
-
-Done!
-```
-
-## Verification-Only Tasks
-
-If a task is purely verification (no code changes — just running tests, typecheck, or manual checks), merge its checks into the batch integration check or final review rather than dispatching an implementer. These tasks exist in the plan for documentation purposes but don't need the full implementer → reviewer cycle.
-
-## Batch Integration Check
-
-Between batches, run targeted verification on affected packages before starting the next batch.
-
-Detect the package manager first (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, otherwise → npm):
-
-```bash
-$PM run typecheck [affected packages]
-$PM run lint [affected packages]
-```
-
-This catches cross-task integration issues early — especially when the next batch depends on the current batch's output. Do NOT skip this even if individual task reviews passed.
-
-If typecheck or lint fails, treat the errors as review issues: re-dispatch the implementer(s) whose changes caused the failure with the error output. After fix, re-run the integration check. Do NOT start the next batch until integration passes.
-
-## Final Review Dispatch
-
-After all batches complete and pass integration checks, dispatch the final reviewer:
-
-1. Locate the original design document from `docs/plans/` — it shares the same date and topic as the plan file (e.g., plan `2026-03-04-dialog-confirm.md` → design `2026-03-04-dialog-confirm-design.md`)
-2. Fill `./final-review-prompt.md` with:
-   - The full text of the original design document
-   - The full text of the implementation plan
-   - Summaries of all completed tasks (commit SHAs, files changed, test results)
-3. Dispatch as `Task(general-purpose)`
-4. If the final reviewer returns **APPROVED** → done
-5. If the final reviewer returns **ISSUES**:
-   - For cross-task integration issues: create a fix task targeting specific files, run through implementer → review cycle
-   - For missing design requirements: create new implementation tasks and run through the full batch cycle
-   - Re-run final review after all fixes
-
-## Simplify
-
-After the final review passes, run `/simplify` to review all changed code for reuse, quality, and efficiency. This catches cross-task cleanup opportunities that individual reviewers miss.
-
-1. Orchestrator runs `/simplify` via the Skill tool
-2. If simplify made changes:
-   - Run typecheck/lint on affected packages
-   - If typecheck/lint fails → fix the issues and re-run typecheck/lint until it passes
-   - Commit simplify changes as a separate commit (`refactor: simplify changed code`)
-3. If simplify made no changes → skip to completion
-
-## Completion
-
-After simplify completes (or is skipped), report to the user: number of tasks completed, total files changed, and final review outcome.
-
-## Red Flags
-
-**Never:**
-
-- Start implementation on main/master without explicit user consent
-- Skip reviews (spec compliance OR code quality)
-- Proceed with unfixed issues
-- Put tasks with file overlap in the same parallel batch
-- Skip dependency analysis
-- Make implementer read plan file directly (provide full text instead)
-- Skip scene-setting context
-- Accept "close enough" on spec compliance
-- Skip review loops (issue found → fix → re-review)
-- Skip batch integration checks between batches
-- Skip `/simplify` after final review
-- Use `run_in_background: true` on Task calls (use foreground parallel instead)
-
-**If implementer returns questions:**
-
-- Answer clearly and completely
-- Re-launch that implementer with answers included
-- Other parallel implementers continue unaffected
-
-**If reviewers find issues:**
-
-- Orchestrator re-dispatches implementer with all issues from both reviewers combined
-- After fix, re-dispatch only the failed reviewers (parallel Task calls)
-- Repeat until both approved
-
-**If implementer fails or times out:**
-
-- Do NOT silently proceed — the affected files may be in an indeterminate state
-- Check if other tasks in the same batch depend on the failed task's output
-- Independent tasks' results still stand
-- Escalate to user with specific error details before proceeding
-- Do NOT re-launch on potentially partially-modified files without inspection
-
-## Integration
-
-**Related skills:**
-
-- **sd-plan** — creates the plan this skill executes
-- **sd-tdd** — implementers follow TDD
-- **sd-worktree** — branch isolation for worktree-based workflows