@simplysm/sd-claude 13.0.78 → 13.0.81

package/claude/skills/sd-tdd/testing-anti-patterns.md

@@ -1,317 +0,0 @@
-# Testing Anti-Patterns
-
-**Load this reference when:** writing or changing tests, adding mocks, or tempted to add test-only methods to production code.
-
-## Overview
-
-Tests must verify real behavior, not mock behavior. Mocks are a means to isolate, not the thing being tested.
-
-**Core principle:** Test what the code does, not what the mocks do.
-
-**Following strict TDD prevents these anti-patterns.**
-
-## The Iron Laws
-
-```
-1. NEVER test mock behavior
-2. NEVER add test-only methods to production classes
-3. NEVER mock without understanding dependencies
-```
-
-## Anti-Pattern 1: Testing Mock Behavior
-
-**The violation:**
-
-```typescript
-// ❌ BAD: Testing that the mock exists
-test('renders sidebar', () => {
-  render(<Page />);
-  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
-});
-```
-
-**Why this is wrong:**
-
-- You're verifying the mock works, not that the component works
-- Test passes when mock is present, fails when it's not
-- Tells you nothing about real behavior
-
-**your human partner's correction:** "Are we testing the behavior of a mock?"
-
-**The fix:**
-
-```typescript
-// ✅ GOOD: Test real component or don't mock it
-test('renders sidebar', () => {
-  render(<Page />);  // Don't mock sidebar
-  expect(screen.getByRole('navigation')).toBeInTheDocument();
-});
-
-// OR if sidebar must be mocked for isolation:
-// Don't assert on the mock - test Page's behavior with sidebar present
-```
-
-### Gate Function
-
-```
-BEFORE asserting on any mock element:
-  Ask: "Am I testing real component behavior or just mock existence?"
-
-  IF testing mock existence:
-    STOP - Delete the assertion or unmock the component
-
-  Test real behavior instead
-```
-
-## Anti-Pattern 2: Test-Only Methods in Production
-
-**The violation:**
-
-```typescript
-// ❌ BAD: destroy() only used in tests
-class Session {
-  async destroy() {
-    // Looks like production API!
-    await this._workspaceManager?.destroyWorkspace(this.id);
-    // ... cleanup
-  }
-}
-
-// In tests
-afterEach(() => session.destroy());
-```
-
-**Why this is wrong:**
-
-- Production class polluted with test-only code
-- Dangerous if accidentally called in production
-- Violates YAGNI and separation of concerns
-- Confuses object lifecycle with entity lifecycle
-
-**The fix:**
-
-```typescript
-// ✅ GOOD: Test utilities handle test cleanup
-// Session has no destroy() - it's stateless in production
-
-// In test-utils/
-export async function cleanupSession(session: Session) {
-  const workspace = session.getWorkspaceInfo();
-  if (workspace) {
-    await workspaceManager.destroyWorkspace(workspace.id);
-  }
-}
-
-// In tests
-afterEach(() => cleanupSession(session));
-```
-
-### Gate Function
-
-```
-BEFORE adding any method to production class:
-  Ask: "Is this only used by tests?"
-
-  IF yes:
-    STOP - Don't add it
-    Put it in test utilities instead
-
-  Ask: "Does this class own this resource's lifecycle?"
-
-  IF no:
-    STOP - Wrong class for this method
-```
-
-## Anti-Pattern 3: Mocking Without Understanding
-
-**The violation:**
-
-```typescript
-// ❌ BAD: Mock breaks test logic
-test("detects duplicate server", () => {
-  // Mock prevents config write that test depends on!
-  vi.mock("ToolCatalog", () => ({
-    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined),
-  }));
-
-  await addServer(config);
-  await addServer(config); // Should throw - but won't!
-});
-```
-
-**Why this is wrong:**
-
-- Mocked method had side effect test depended on (writing config)
-- Over-mocking to "be safe" breaks actual behavior
-- Test passes for wrong reason or fails mysteriously
-
-**The fix:**
-
-```typescript
-// ✅ GOOD: Mock at correct level
-test("detects duplicate server", () => {
-  // Mock the slow part, preserve behavior test needs
-  vi.mock("MCPServerManager"); // Just mock slow server startup
-
-  await addServer(config); // Config written
-  await addServer(config); // Duplicate detected ✓
-});
-```
-
-### Gate Function
-
-```
-BEFORE mocking any method:
-  STOP - Don't mock yet
-
-  1. Ask: "What side effects does the real method have?"
-  2. Ask: "Does this test depend on any of those side effects?"
-  3. Ask: "Do I fully understand what this test needs?"
-
-  IF depends on side effects:
-    Mock at lower level (the actual slow/external operation)
-    OR use test doubles that preserve necessary behavior
-    NOT the high-level method the test depends on
-
-  IF unsure what test depends on:
-    Run test with real implementation FIRST
-    Observe what actually needs to happen
-    THEN add minimal mocking at the right level
-
-  Red flags:
-    - "I'll mock this to be safe"
-    - "This might be slow, better mock it"
-    - Mocking without understanding the dependency chain
-```
-
-## Anti-Pattern 4: Incomplete Mocks
-
-**The violation:**
-
-```typescript
-// ❌ BAD: Partial mock - only fields you think you need
-const mockResponse = {
-  status: "success",
-  data: { userId: "123", name: "Alice" },
-  // Missing: metadata that downstream code uses
-};
-
-// Later: breaks when code accesses response.metadata.requestId
-```
-
-**Why this is wrong:**
-
-- **Partial mocks hide structural assumptions** - You only mocked fields you know about
-- **Downstream code may depend on fields you didn't include** - Silent failures
-- **Tests pass but integration fails** - Mock incomplete, real API complete
-- **False confidence** - Test proves nothing about real behavior
-
-**The Iron Rule:** Mock the COMPLETE data structure as it exists in reality, not just fields your immediate test uses.
-
-**The fix:**
-
-```typescript
-// ✅ GOOD: Mirror real API completeness
-const mockResponse = {
-  status: "success",
-  data: { userId: "123", name: "Alice" },
-  metadata: { requestId: "req-789", timestamp: 1234567890 },
-  // All fields real API returns
-};
-```
-
-### Gate Function
-
-```
-BEFORE creating mock responses:
-  Check: "What fields does the real API response contain?"
-
-  Actions:
-    1. Examine actual API response from docs/examples
-    2. Include ALL fields system might consume downstream
-    3. Verify mock matches real response schema completely
-
-  Critical:
-    If you're creating a mock, you must understand the ENTIRE structure
-    Partial mocks fail silently when code depends on omitted fields
-
-  If uncertain: Include all documented fields
-```
-
-## Anti-Pattern 5: Integration Tests as Afterthought
-
-**The violation:**
-
-```
-✅ Implementation complete
-❌ No tests written
-"Ready for testing"
-```
-
-**Why this is wrong:**
-
-- Testing is part of implementation, not optional follow-up
-- TDD would have caught this
-- Can't claim complete without tests
-
-**The fix:**
-
-```
-TDD cycle:
-1. Write failing test
-2. Implement to pass
-3. Refactor
-4. THEN claim complete
-```
-
-## When Mocks Become Too Complex
-
-**Warning signs:**
-
-- Mock setup longer than test logic
-- Mocking everything to make test pass
-- Mocks missing methods real components have
-- Test breaks when mock changes
-
-**your human partner's question:** "Do we need to be using a mock here?"
-
-**Consider:** Integration tests with real components often simpler than complex mocks
-
-## TDD Prevents These Anti-Patterns
-
-**Why TDD helps:**
-
-1. **Write test first** → Forces you to think about what you're actually testing
-2. **Watch it fail** → Confirms test tests real behavior, not mocks
-3. **Minimal implementation** → No test-only methods creep in
-4. **Real dependencies** → You see what the test actually needs before mocking
-
-**If you're testing mock behavior, you violated TDD** - you added mocks without watching test fail against real code first.
-
-## Quick Reference
-
-| Anti-Pattern                    | Fix                                           |
-| ------------------------------- | --------------------------------------------- |
-| Assert on mock elements         | Test real component or unmock it              |
-| Test-only methods in production | Move to test utilities                        |
-| Mock without understanding      | Understand dependencies first, mock minimally |
-| Incomplete mocks                | Mirror real API completely                    |
-| Tests as afterthought           | TDD - tests first                             |
-| Over-complex mocks              | Consider integration tests                    |
-
-## Red Flags
-
-- Assertion checks for `*-mock` test IDs
-- Methods only called in test files
-- Mock setup is >50% of test
-- Test fails when you remove mock
-- Can't explain why mock is needed
-- Mocking "just to be safe"
-
-## The Bottom Line
-
-**Mocks are tools to isolate, not things to test.**
-
-If TDD reveals you're testing mock behavior, you've gone wrong.
-
-Fix: Test real behavior or question why you're mocking at all.

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

@@ -1,67 +0,0 @@
----
-name: sd-use
-description: "Route requests to sd-* skills/agents (explicit invocation only)"
-model: haiku
----
-
-# sd-use - Auto Skill Router
-
-Analyze user request from ARGUMENTS, select the best matching skill, explain why, then execute it.
-
-## Execution Flow
-
-1. Read ARGUMENTS
-2. If user names a specific skill, route to that skill directly
-3. Otherwise, match against catalog below
-4. Report selection with reason
-5. Execute immediately
-
-## Catalog (execute via `Skill` tool)
-
-| Skill                | When to select                                                                                                                                  |
-|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
-| `sd-brainstorm`      | New feature, component, or behavior change — **creative work before implementation**                                                            |
-| `sd-debug`           | Bug, test failure, unexpected behavior — **systematic root cause investigation**                                                                |
-| `sd-tdd`             | Implementing a feature or fixing a bug — **before writing code**                                                                                |
-| `sd-plan`            | Multi-step task with spec/requirements — **planning before code**                                                                               |
-| `sd-plan-dev`        | Already have a plan — **executing implementation plan**                                                                                         |
-| `sd-review`          | Code review + refactoring analysis — defects, safety, API design, conventions, complexity, duplication, code structure                           |
-| `sd-check`           | Verify code — typecheck, lint, tests                                                                                                            |
-| `sd-commit`          | Create a git commit                                                                                                                             |
-| `sd-readme`          | Update a package README.md                                                                                                                      |
-| `sd-discuss`         | Evaluate code design decisions against industry standards and project conventions                                                                |
-| `sd-api-name-review` | Review public API naming consistency                                                                                                            |
-| `sd-worktree`        | Start new work in branch isolation                                                                                                              |
-| `sd-skill`           | Create or edit skills                                                                                                                           |
-| `sd-email-analyze`   | Analyze, read, or summarize email files (`.eml` or `.msg`) — parsing and attachment extraction                                                  |
-| `sd-document`        | Read or write document files (`.docx`, `.xlsx`, `.pptx`, `.pdf`) — content extraction, creation, data export                                    |
-
-## Selection Rules
-
-1. **Explicit skill name** — If user mentions a specific skill name, route to that skill directly
-2. Select **exactly one** skill — the most specific match wins
-3. **Review & Refactor**: "find bugs", "review", "refactor", "improve structure", "remove duplication" → `sd-review`
-4. **Sequential requests**: Route to the **first** skill only. After completion, user can invoke the next
-5. If nothing matches, use **default LLM behavior** and handle the request directly
-6. Pass ARGUMENTS through as the skill's input
-
-## Report Format
-
-Before executing, output:
-
-```
-**Selected**: `{skill-name}`
-**Reason**: {one-line explanation}
-**Tip**: Next time you can call `/{skill-name} {request}` directly.
-```
-
-Then execute immediately.
-
-If no match:
-
-```
-**Selected**: Default LLM
-**Reason**: {one-line explanation}
-```
-
-Then handle the request directly.

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

@@ -1,78 +0,0 @@
----
-name: sd-worktree
-description: "Git worktree branch isolation (explicit invocation only)"
-model: haiku
----
-
-# sd-worktree
-
-Branch-isolated workflow using git worktrees.
-
-## Flow
-
-```mermaid
-flowchart TD
-    START([sd-worktree invoked]) --> ADD
-
-    subgraph ADD [add]
-        A1["git worktree add .worktrees/NAME -b NAME"]
-        A1 -->|fail| HALT
-        A1 -->|ok| A2[detect package manager]
-        A2 --> A3["pm install (cwd: .worktrees/NAME)"]
-        A3 -->|fail| HALT
-        A3 -->|ok| A4["cd .worktrees/NAME"]
-    end
-
-    A4 --> WORK["work + commit inside worktree"]
-    WORK --> MERGE
-
-    subgraph MERGE [merge]
-        M0["cd PROJECT_ROOT"]
-        M0 --> M1["git merge NAME --no-ff (cwd: PROJECT_ROOT)"]
-        M1 -->|fail| HALT
-        M1 -->|ok| M2[merge complete]
-    end
-
-    M2 --> CLEAN
-
-    subgraph CLEAN [clean]
-        C1{"cwd inside worktree?"}
-        C1 -->|yes| HALT
-        C1 -->|no| C2["rm -rf .worktrees/NAME (bash)"]
-        C2 --> C3["git worktree prune"]
-        C3 --> C4["git branch -d NAME"]
-        C4 -->|fail| HALT
-        C4 -->|ok| C5[done]
-    end
-
-    HALT([HALT - AskUserQuestion])
-```
-
-## Rules
-
-### HALT
-
-When any step reaches **fail** or **HALT**:
-
-1. Show the error message to the user as-is
-2. Ask the user how to proceed via `AskUserQuestion`
-3. Do **nothing** until the user responds
-
-Manual git merge, git stash, git reset, git clean, or **any workaround is forbidden**. Yolo mode does NOT override HALT.
-
-### Worktree location
-
-All worktrees MUST be created under **`.worktrees/`** (project root).
-
-### Package manager detection
-
-| File | PM |
-|---|---|
-| `pnpm-lock.yaml` | pnpm |
-| `yarn.lock` | yarn |
-| `package-lock.json` | npm |
-| `bun.lockb` / `bun.lock` | bun |
-
-### clean: use rm -rf
-
-`git worktree remove` almost always fails on Windows due to file locks. Use `rm -rf` (bash) + `git worktree prune` instead.