safeword 0.8.4 → 0.8.5

package/templates/cursor/rules/safeword-quality-reviewer.mdc

@@ -0,0 +1,158 @@
+---
+description: Deep code quality review with web research. Use when user explicitly requests verification against latest docs ('double check against latest', 'verify versions', 'check security'), needs deeper analysis beyond automatic hook, or is working on projects without SAFEWORD.md/CLAUDE.md. Fetches current documentation, checks latest versions, and provides deep analysis (performance, security, alternatives).
+alwaysApply: false
+---
+
+# Quality Reviewer
+
+Deep quality review with web research to verify code against the latest ecosystem state.
+
+**Primary differentiator**: Web research to verify against current versions, documentation, and best practices.
+
+**Triggers**:
+
+- **Explicit web research request**: "double check against latest docs", "verify we're using latest version", "check for security issues"
+- **Deep dive needed**: User wants analysis beyond automatic hook (performance, architecture alternatives, trade-offs)
+- **No SAFEWORD.md/CLAUDE.md**: Projects without context files (automatic hook won't run, manual review needed)
+- **Pre-change review**: User wants review before making changes (automatic hook only triggers after changes)
+- **Model-invoked**: Claude determines web research would be valuable
+
+**Relationship to automatic quality hook**:
+
+- **Automatic hook**: Fast quality check using existing knowledge + project context (guaranteed, runs on every change)
+- **This skill**: Deep review with web research when verification against current ecosystem is needed (on-demand, 2-3 min)
+
+## Review Protocol
+
+### 1. Identify What Changed
+
+Understand context:
+
+- What files were just modified?
+- What problem is being solved?
+- What was the implementation approach?
+
+### 2. Read Project Standards
+
+```bash
+ls CLAUDE.md SAFEWORD.md ARCHITECTURE.md .claude/
+```
+
+Read relevant standards:
+
+- `CLAUDE.md` or `SAFEWORD.md` - Project-specific guidelines
+- `ARCHITECTURE.md` - Architectural principles
+- `@./.safeword/guides/code-philosophy.md` - Core coding principles
+
+### 3. Evaluate Correctness
+
+**Will it work?**
+
+- Does the logic make sense?
+- Are there obvious bugs?
+
+**Edge cases:**
+
+- Empty inputs, null/undefined, boundary conditions (0, -1, max)?
+- Concurrent access, network failures?
+
+**Error handling:**
+
+- Are errors caught appropriately?
+- Helpful error messages?
+- Cleanup handled (resources, connections)?
+
+**Logic errors:**
+
+- Off-by-one errors, race conditions, wrong assumptions?
+
+### 4. Evaluate Anti-Bloat
+
+- Are all dependencies necessary? Could we use stdlib/built-ins?
+- Are abstractions solving real problems or imaginary ones?
+- YAGNI: Is this feature actually needed now?
+
+### 5. Evaluate Elegance
+
+- Is the code easy to understand?
+- Are names clear and descriptive?
+- Is the intent obvious?
+- Will this be easy to change later?
+
+### 6. Check Standards Compliance
+
+**Project standards** (from CLAUDE.md/SAFEWORD.md/ARCHITECTURE.md):
+
+- Does it follow established patterns?
+- Does it violate any documented principles?
+
+**Library best practices:**
+
+- Are we using libraries correctly?
+- Are we following official documentation?
+
+### 7. Verify Latest Versions
+
+**CRITICAL**: This is your main differentiator from automatic hook. ALWAYS check versions.
+
+Search for:
+- "[library name] latest stable version 2025"
+- "[library name] security vulnerabilities"
+
+**Flag if outdated:**
+
+- Major versions behind → WARN (e.g., React 17 when 19 is stable)
+- Minor versions behind → NOTE (e.g., React 19.0.0 when 19.1.0 is stable)
+- Security vulnerabilities → CRITICAL (must upgrade)
+- Using latest → Confirm
+
+### 8. Verify Latest Documentation
+
+**CRITICAL**: This is your main differentiator from automatic hook. ALWAYS verify against current docs.
+
+Fetch documentation from official sources:
+- https://react.dev (for React)
+- https://vitejs.dev (for Vite)
+
+**Look for:**
+
+- Are we using deprecated APIs?
+- Are there newer, better patterns?
+- Did the library's recommendations change since training data?
+
+## Output Format
+
+**Simple question** ("is it correct?"):
+
+```text
+**Correctness:** ✓ Logic is sound, edge cases handled, no obvious errors.
+```
+
+**Full review** ("double check and critique"):
+
+```markdown
+## Quality Review
+
+**Correctness:** [✓/⚠️/❌] [Brief assessment]
+**Anti-Bloat:** [✓/⚠️/❌] [Brief assessment]
+**Elegance:** [✓/⚠️/❌] [Brief assessment]
+**Standards:** [✓/⚠️/❌] [Brief assessment]
+**Versions:** [✓/⚠️/❌] [Latest version check with WebSearch]
+**Documentation:** [✓/⚠️/❌] [Current docs check with WebFetch]
+
+**Verdict:** [APPROVE / REQUEST CHANGES / NEEDS DISCUSSION]
+
+**Critical issues:** [List or "None"]
+**Suggested improvements:** [List or "None"]
+```
+
+## Critical Reminders
+
+1. **Primary value: Web research** - Verify against current ecosystem (versions, docs, security)
+2. **Complement automatic hook** - Hook does fast check with existing knowledge, you do deep dive with web research
+3. **Explicit triggers matter** - "double check against latest docs", "verify versions", "check security" = invoke web research
+4. **Always check latest docs** - Verify patterns are current, not outdated
+5. **Always verify versions** - Flag outdated dependencies
+6. **Be thorough but concise** - Cover all areas but keep explanations brief
+7. **Provide actionable feedback** - Specific line numbers, concrete suggestions
+8. **Clear verdict** - Always end with APPROVE/REQUEST CHANGES/NEEDS DISCUSSION

package/templates/cursor/rules/safeword-refactoring.mdc

@@ -0,0 +1,175 @@
+---
+description: Systematic refactoring with small-step discipline. Use when user says 'refactor', 'clean up', 'restructure', 'extract', 'rename', 'simplify', or mentions code smells. Enforces one change → test → commit cycle. For structural improvements, NOT style/formatting (use /lint). NOT for adding features or fixing bugs.
+alwaysApply: false
+---
+
+# Refactoring
+
+Improve code structure without changing behavior. One small step at a time.
+
+**Iron Law:** ONE REFACTORING → TEST → COMMIT. Never batch changes.
+
+## When to Use
+
+Answer IN ORDER. Stop at first match:
+
+1. User says "refactor", "clean up", "restructure"? → Use this skill
+2. User asks to "extract", "rename", "simplify"? → Use this skill
+3. Code smell identified? → Use this skill
+4. User wants to add feature or fix bug? → Skip (use tdd-enforcer)
+5. User wants formatting/style fixes? → Skip (use /lint)
+
+**Code smells** (common triggers):
+
+- Duplicated code (same logic in multiple places)
+- Long function (>30 lines, doing too much)
+- Magic numbers/strings (unexplained literals)
+- Deep nesting (>3 levels of indentation)
+- Dead code (unused functions, unreachable branches)
+- Poor naming (unclear what something does)
+
+---
+
+## Phase 1: ASSESS
+
+**Is this actually refactoring?**
+
+| User Intent         | Action                                          |
+| ------------------- | ----------------------------------------------- |
+| "Make this cleaner" | ✓ Refactoring                                   |
+| "Add validation"    | ✗ New behavior → tdd-enforcer                   |
+| "Fix this bug"      | ✗ Bug fix → tdd-enforcer or systematic-debugger |
+| "Format this code"  | ✗ Style → /lint                                 |
+
+**If not refactoring:** Explain and suggest correct approach.
+
+---
+
+## Phase 2: PROTECT
+
+**Does the code have tests?**
+
+| Coverage         | Action                                        |
+| ---------------- | --------------------------------------------- |
+| Well-tested      | Skip to Phase 3                               |
+| Partial coverage | Add characterization tests for untested parts |
+| No tests         | Add characterization tests first              |
+
+### Characterization Tests
+
+Capture current behavior before refactoring:
+
+```typescript
+// Characterization test - captures ACTUAL behavior
+it('processOrder returns current behavior', () => {
+  const result = processOrder({ items: [], user: null });
+  // Whatever it returns NOW is the expected value
+  expect(result).toEqual({ status: 'empty', total: 0 });
+});
+```
+
+**Purpose:** Safety net, not specification. Test what the code DOES, not what it SHOULD do.
+
+---
+
+## Phase 3: REFACTOR
+
+**Iron Law:** ONE refactoring at a time. Run tests after EVERY change.
+
+### Refactoring Catalog
+
+**Tier 1 - Always Safe** (no behavior change possible):
+
+| Smell                | Refactoring          | Example                                |
+| -------------------- | -------------------- | -------------------------------------- |
+| Unclear name         | **Rename**           | `d` → `discountAmount`                 |
+| Long function        | **Extract Function** | Pull 10 lines into `calculateTax()`    |
+| Unnecessary variable | **Inline Variable**  | Remove `temp = x; return temp;`        |
+| Misplaced code       | **Move Function**    | Move `validate()` to `Validator` class |
+
+**Tier 2 - Safe with Tests** (low risk if tests exist):
+
+| Smell               | Refactoring               | Example                                           |
+| ------------------- | ------------------------- | ------------------------------------------------- |
+| Repeated expression | **Extract Variable**      | `order.items.length > 0` → `const hasItems = ...` |
+| Complex conditional | **Decompose Conditional** | Extract `if` branches to named functions          |
+| Nested conditionals | **Guard Clauses**         | Early returns instead of deep nesting             |
+| Magic literal       | **Replace Magic Literal** | `0.2` → `VIP_DISCOUNT_RATE`                       |
+| Unused code         | **Remove Dead Code**      | Delete unreachable branches                       |
+
+**Tier 3 - Requires Care** (higher risk, break into smaller steps):
+
+| Smell                      | Refactoring                    | Caution                                     |
+| -------------------------- | ------------------------------ | ------------------------------------------- |
+| God class                  | **Extract Class**              | Do incrementally, move one method at a time |
+| Type-checking conditionals | **Replace with Polymorphism**  | Requires class hierarchy                    |
+| Too many parameters        | **Introduce Parameter Object** | Changes function signature                  |
+
+**Tie-breaker:** If multiple refactorings apply, choose smallest scope first (Rename < Extract Variable < Extract Function < Extract Class).
+
+---
+
+## Phase 4: VERIFY
+
+After each refactoring:
+
+1. **Run tests** - Must pass
+2. **If tests pass:** Commit with `refactor: [what changed]`
+3. **If tests fail:** Revert immediately
+
+### Revert Protocol
+
+```bash
+git checkout -- <changed-files>
+```
+
+**After revert:**
+
+- Was the refactoring too large? → Try smaller step
+- Did it accidentally change behavior? → Reconsider approach
+- DO NOT attempt to "fix" a failed refactoring
+
+### After 2 Failed Attempts
+
+**STOP.** Ask user:
+
+> "I've attempted this refactoring twice and tests keep failing. This suggests either:
+>
+> 1. The refactoring is too large (need smaller steps)
+> 2. The code has hidden dependencies
+> 3. Tests are brittle
+>
+> How would you like to proceed?"
+
+---
+
+## Phase 5: ITERATE
+
+```text
+More refactoring needed?
+├─ Yes → Return to Phase 3 (one more refactoring)
+└─ No → Done
+    └─ Report: "Refactoring complete. Changes: [summary]"
+```
+
+---
+
+## Anti-Patterns
+
+| Don't                           | Do                                    |
+| ------------------------------- | ------------------------------------- |
+| Batch multiple refactorings     | One refactoring → test → commit       |
+| "Fix" a failed refactoring      | Revert, then try smaller step         |
+| Refactor without tests          | Add characterization tests first      |
+| Change behavior during refactor | That's a feature/fix, not refactoring |
+| Skip the commit                 | Commit after every green test         |
+
+---
+
+## Key Takeaways
+
+1. **One change at a time** - Never batch refactorings
+2. **Tests before refactoring** - No safety net = no refactoring
+3. **Revert on failure** - Don't fix, revert and retry smaller
+4. **Commit after each success** - `refactor: [description]`
+5. **Smallest scope first** - Rename < Extract < Move < Restructure

package/templates/skills/safeword-brainstorming/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: brainstorming
+description: Use before implementation when refining rough ideas into specs. Guides collaborative design through Socratic questioning, alternative exploration, and incremental validation. Triggers: 'brainstorm', 'design', 'explore options', 'figure out', 'think through', 'what approach'.
+allowed-tools: '*'
+---
+
+# Brainstorming Ideas Into Specs
+
+Turn rough ideas into validated specs through Socratic dialogue.
+
+**Iron Law:** ONE QUESTION AT A TIME. EXPLORE ALTERNATIVES BEFORE DECIDING.
+
+## When to Use
+
+Answer IN ORDER. Stop at first match:
+
+1. Rough idea needs refinement? → Use this skill
+2. Multiple approaches possible? → Use this skill
+3. Unclear requirements? → Use this skill
+4. Clear task, obvious approach? → Skip (use enforcing-tdd directly)
+5. Pure research/investigation? → Skip
+
+---
+
+## Phase 1: CONTEXT
+
+**Purpose:** Understand what exists before asking questions.
+
+**Protocol:**
+
+1. Check project state (files, recent commits, existing specs)
+2. Review relevant docs in `.safeword/planning/`
+3. Identify constraints and patterns already established
+
+**Exit Criteria:**
+
+- [ ] Reviewed relevant codebase areas
+- [ ] Checked existing specs/designs
+- [ ] Ready to ask informed questions
+
+---
+
+## Phase 2: QUESTION
+
+**Iron Law:** ONE QUESTION PER MESSAGE
+
+**Protocol:**
+
+1. Ask one focused question
+2. Prefer multiple choice (2-4 options) when possible
+3. Open-ended is fine for exploratory topics
+4. Focus on: purpose, constraints, success criteria, scope
+
+**Question Types (in order of preference):**
+
+| Type            | When                    | Example                                              |
+| --------------- | ----------------------- | ---------------------------------------------------- |
+| Multiple choice | Clear options exist     | "Should this be (A) real-time or (B) polling-based?" |
+| Yes/No          | Binary decision         | "Do we need offline support?"                        |
+| Bounded open    | Need specifics          | "What's the max number of items to display?"         |
+| Open-ended      | Exploring problem space | "What problem are you trying to solve?"              |
+
+**Exit Criteria:**
+
+- [ ] Understand the core problem/goal
+- [ ] Know key constraints
+- [ ] Have success criteria
+- [ ] Scope boundaries are clear
+
+---
+
+## Phase 3: ALTERNATIVES
+
+**Iron Law:** ALWAYS PRESENT 2-3 OPTIONS BEFORE DECIDING
+
+**Protocol:**
+
+1. Present 2-3 approaches with trade-offs
+2. Lead with your recommendation and why
+3. Be explicit about what each gives up
+4. Let user choose (or suggest hybrid)
+
+**Format:**
+
+```text
+I'd recommend Option A because [reason].
+
+**Option A: [Name]**
+- Approach: [how it works]
+- Pros: [benefits]
+- Cons: [drawbacks]
+
+**Option B: [Name]**
+- Approach: [how it works]
+- Pros: [benefits]
+- Cons: [drawbacks]
+
+**Option C: [Name]** (if applicable)
+- Approach: [how it works]
+- Pros: [benefits]
+- Cons: [drawbacks]
+
+Which direction feels right?
+```
+
+**Exit Criteria:**
+
+- [ ] Presented 2-3 viable approaches
+- [ ] Gave clear recommendation with reasoning
+- [ ] User selected approach (or hybrid)
+
+---
+
+## Phase 4: DESIGN
+
+**Iron Law:** PRESENT IN 200-300 WORD SECTIONS. VALIDATE EACH.
+
+**Protocol:**
+
+1. Present design incrementally (not all at once)
+2. After each section: "Does this look right so far?"
+3. Cover: architecture, components, data flow, error handling
+4. Apply YAGNI ruthlessly - remove anything "just in case"
+5. Go back and clarify when something doesn't fit
+
+**Sections (present one at a time):**
+
+1. **Overview** - What we're building, high-level approach
+2. **Components** - Key pieces and responsibilities
+3. **Data Flow** - How data moves through system
+4. **Edge Cases** - Error handling, boundaries
+5. **Out of Scope** - What we're explicitly NOT doing
+
+**Exit Criteria:**
+
+- [ ] Each section validated by user
+- [ ] Design is complete and coherent
+- [ ] YAGNI applied (no speculative features)
+- [ ] Ready to create spec
+
+---
+
+## Phase 5: SPEC
+
+**Purpose:** Convert validated design into structured spec.
+
+**Protocol:**
+
+1. Determine level (L0/L1/L2) using triage questions
+2. Create spec using appropriate template
+3. Commit the spec
+
+**Triage:**
+
+| Question                                 | If Yes →                     |
+| ---------------------------------------- | ---------------------------- |
+| User-facing feature with business value? | **L2** → Feature Spec        |
+| Bug, improvement, internal, or refactor? | **L1** → Task Spec           |
+| Typo, config, or trivial change?         | **L0** → Task Spec (minimal) |
+
+**Output Locations:**
+
+- L2: `.safeword/planning/specs/feature-[slug].md`
+- L1/L0: `.safeword/planning/specs/task-[slug].md`
+- L2 Test Defs: `.safeword/planning/test-definitions/feature-[slug].md`
+
+**Exit Criteria:**
+
+- [ ] Spec created in correct location
+- [ ] L2: Test definitions created
+- [ ] Spec committed to git
+
+---
+
+## Phase 6: HANDOFF
+
+**Protocol:**
+
+1. Summarize what was created
+2. Ask: "Ready to start implementation with TDD?"
+3. If yes → Invoke enforcing-tdd skill
+
+**Exit Criteria:**
+
+- [ ] User confirmed spec is complete
+- [ ] Handed off to enforcing-tdd (if continuing)
+
+---
+
+## Key Principles
+
+| Principle                     | Why                                     |
+| ----------------------------- | --------------------------------------- |
+| One question at a time        | Prevents overwhelm, gets better answers |
+| Multiple choice preferred     | Faster to answer, reduces ambiguity     |
+| Alternatives before decisions | Avoids premature commitment             |
+| Incremental validation        | Catches misunderstandings early         |
+| YAGNI ruthlessly              | Scope creep kills projects              |
+
+---
+
+## Anti-Patterns
+
+| Don't                          | Do                               |
+| ------------------------------ | -------------------------------- |
+| Dump full design at once       | Present in 200-300 word sections |
+| Ask 5 questions in one message | Ask ONE question                 |
+| Skip alternatives              | Always present 2-3 options       |
+| Accept vague requirements      | Probe until concrete             |
+| Add "nice to have" features    | Put them in "Out of Scope"       |

package/templates/skills/{safeword-systematic-debugger → safeword-debugging}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: systematic-debugger
+name: debugging
 description: Four-phase debugging framework that ensures root cause identification before fixes. Use when encountering bugs, test failures, unexpected behavior, or when previous fix attempts failed. Enforces investigate-first discipline ('debug this', 'fix this error', 'test is failing', 'not working').
 allowed-tools: '*'
 ---
@@ -26,33 +26,6 @@ Answer IN ORDER. Stop at first match:
 - "Quick fix" seems obvious (red flag)
 - Already tried 1+ fixes that didn't work
 
----
-
-## Work Log
-
-**Think hard. Keep notes.**
-
-Before starting Phase 1, create or open a work log:
-
-**Location:** `.safeword/logs/{artifact-type}-{slug}.md`
-
-| Working on...         | Log file name            |
-| --------------------- | ------------------------ |
-| Ticket `001-fix-auth` | `ticket-001-fix-auth.md` |
-| Spec `task-add-cache` | `spec-task-add-cache.md` |
-
-**One artifact = one log.** If log exists, append a new session.
-
-**Especially important for debugging:**
-
-1. **Re-read the log** before each hypothesis
-2. **Log what you tried** and why it didn't work
-3. **Note dead ends** - debugging often revisits same paths
-
-**Template:** @./.safeword/templates/work-log-template.md
-
----
-
 ## The Four Phases
 
 Complete each phase before proceeding.
@@ -220,32 +193,6 @@ If you catch yourself thinking:
 
 **ALL mean: STOP. Return to Phase 1.**
 
-## Finding Test Pollution
-
-When tests pass individually but fail together (test isolation problem, tests affect each other, tests leave files behind), use bisection:
-
-```bash
-./.safeword/scripts/bisect-test-pollution.sh '.git' '*.test.ts' src
-```
-
-See: @./.safeword/scripts/bisect-test-pollution.sh
-
-## Debug Logging
-
-When adding diagnostic logging:
-
-```javascript
-// ❌ BAD
-console.log('here');
-console.log(data);
-
-// ✅ GOOD
-console.log('validateUser', { expected: 'admin', actual: user.role });
-console.log('processOrder', JSON.stringify({ input, output }, null, 2));
-```
-
-Log **expected vs actual**. Remove after fixing.
-
 ## Quick Reference
 
 | Phase             | Key Question                          | Success Criteria                   |
@@ -254,20 +201,3 @@ Log **expected vs actual**. Remove after fixing.
 | 2. Pattern        | "What's different from working code?" | Identified key differences         |
 | 3. Hypothesis     | "Is my theory correct?"               | Confirmed or formed new theory     |
 | 4. Implementation | "Does the fix work?"                  | Test passes, issue resolved        |
-
-## Finding Zombie Process Spawners
-
-When tests leave processes behind (playwright browsers not cleaned up, port stays in use, zombie node processes, chromium accumulating), use bisection to find the culprit:
-
-```bash
-./.safeword/scripts/bisect-zombie-processes.sh 'chromium' '*.test.ts' tests
-./.safeword/scripts/bisect-zombie-processes.sh 'playwright' '*.spec.ts' e2e
-```
-
-See: @./.safeword/scripts/bisect-zombie-processes.sh
-
-## Related Resources
-
-- Process cleanup guide: @./.safeword/guides/zombie-process-cleanup.md
-- Debug logging style: @./.safeword/guides/code-philosophy.md
-- TDD for fix verification: @./.safeword/guides/testing-guide.md

package/templates/skills/{safeword-tdd-enforcer → safeword-enforcing-tdd}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: tdd-enforcer
-description: Use when implementing features, fixing bugs, or adding new behavior. Ensures scope is defined before coding, then enforces RED → GREEN → REFACTOR test discipline. NOT for pure refactoring (use refactoring skill for structural improvements without behavior change). Triggers: 'implement', 'add', 'build', 'create', 'fix', 'change', 'feature', 'bug'.
+name: enforcing-tdd
+description: Use when implementing features, fixing bugs, or making code changes. Ensures scope is defined before coding, then enforces RED → GREEN → REFACTOR test discipline. Triggers: 'implement', 'add', 'build', 'create', 'fix', 'change', 'feature', 'bug'.
 allowed-tools: '*'
 ---
 
@@ -17,7 +17,7 @@ Answer IN ORDER. Stop at first match:
 1. Implementing new feature? → Use this skill
 2. Fixing bug? → Use this skill
 3. Adding enhancement? → Use this skill
-4. Refactoring only (no new behavior)? → Skip (use refactoring skill)
+4. Refactoring? → Use this skill
 5. Research/investigation only? → Skip this skill
 
 ---
@@ -160,15 +160,15 @@ Claim: "All tests pass"             "Tests pass" (no output shown)
 
 **Red Flags → STOP:**
 
-| Flag                        | Action                                 |
-| --------------------------- | -------------------------------------- |
-| "should", "probably" claims | Run command, show output first         |
-| "Done!" before verification | Run command, show output first         |
-| "Just in case" code         | Delete it                              |
-| Multiple functions          | Delete extras                          |
-| Refactoring                 | Stop - that's Phase 3                  |
-| Test still fails            | Debug (→ systematic-debugger if stuck) |
-| Hardcoded value             | Implement real logic (see below)       |
+| Flag                        | Action                             |
+| --------------------------- | ---------------------------------- |
+| "should", "probably" claims | Run command, show output first     |
+| "Done!" before verification | Run command, show output first     |
+| "Just in case" code         | Delete it                          |
+| Multiple functions          | Delete extras                      |
+| Refactoring                 | Stop - that's Phase 3              |
+| Test still fails            | Debug (→ debugging skill if stuck) |
+| Hardcoded value             | Implement real logic (see below)   |
 
 ### Anti-Pattern: Mock Implementations
 
@@ -253,11 +253,11 @@ Phase 0: L0 → create minimal spec → Phase 1: no new test (existing tests cov
 
 ## Integration
 
-| Scenario                | Handoff               |
-| ----------------------- | --------------------- |
-| Test fails unexpectedly | → systematic-debugger |
-| Review needed           | → quality-reviewer    |
-| Scope expanding         | → Update spec first   |
+| Scenario                | Handoff             |
+| ----------------------- | ------------------- |
+| Test fails unexpectedly | → debugging skill   |
+| Review needed           | → quality-reviewer  |
+| Scope expanding         | → Update spec first |
 
 ---