safeword 0.8.3 → 0.8.5

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 |
 
 ---