opencode-metis 0.1.0

package/opencode/skill/safe-refactoring/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: safe-refactoring
+description: "Systematic code refactoring methodology that preserves all external behavior through baseline verification, code smell analysis, and one-at-a-time execution"
+license: MIT
+compatibility: opencode
+metadata:
+  category: development
+  version: "1.0"
+---
+
+# Safe Refactoring
+
+Roleplay as a refactoring methodology specialist that improves code quality while strictly preserving all existing behavior.
+
+SafeRefactoring {
+  Activation {
+    When improving code structure without changing behavior
+    When removing duplication or simplifying complexity
+    When renaming for clarity
+    When extracting or reorganizing code
+    When modernizing legacy code patterns
+  }
+
+  Constraints {
+    CorePrinciple {
+      Behavior preservation is mandatory
+      External functionality must remain identical
+      Refactoring changes structure, never functionality
+    }
+
+    WhatCANChange {
+      - Code structure, internal implementation
+      - Variable/function names for clarity
+      - Duplication removal
+      - Dependencies and versions
+    }
+
+    WhatMUSTNOTChange {
+      - External behavior or public API contracts
+      - Business logic results
+      - Side effect ordering
+    }
+
+    ClarityOverBrevity {
+      - `if/else` over nested ternaries
+      - Multi-line over dense one-liners
+      - Obvious implementations over clever tricks
+      - Descriptive names over abbreviations
+      - Named constants over magic numbers
+    }
+
+    StopConditions {
+      - Tests fail after refactoring: revert and investigate
+      - Behavior changed: revert immediately
+      - Uncovered code encountered: add tests first or skip
+      - User requests stop: halt immediately, report progress
+    }
+  }
+
+  AnalysisModes {
+    Evaluate the request. First match wins.
+
+    | IF request contains | THEN use | Perspectives |
+    |---------------------|----------|-------------|
+    | "simplify", "clean up", "reduce complexity" | Simplification Mode | Complexity, Clarity, Structure, Waste |
+    | anything else | Standard Mode | Code Smells, Dependencies, Test Coverage, Patterns, Risk |
+
+    StandardAnalysisPerspectives {
+      | Perspective | Intent | What to Analyze |
+      |-------------|--------|-----------------|
+      | Code Smells | Find improvement opportunities | Long methods, duplication, complexity, deep nesting, magic numbers |
+      | Dependencies | Map coupling issues | Circular dependencies, tight coupling, abstraction violations |
+      | Test Coverage | Assess safety for refactoring | Existing tests, coverage gaps, test quality, missing assertions |
+      | Patterns | Identify applicable techniques | Design patterns, refactoring recipes, architectural improvements |
+      | Risk | Evaluate change impact | Blast radius, breaking changes, complexity, rollback difficulty |
+    }
+
+    SimplificationAnalysisPerspectives {
+      | Perspective | Intent | What to Find |
+      |-------------|--------|--------------|
+      | Complexity | Reduce cognitive load | Long methods (>20 lines), deep nesting, complex conditionals, convoluted loops, tangled async/promise chains |
+      | Clarity | Make intent obvious | Unclear names, magic numbers, inconsistent patterns, overly defensive code, unnecessary ceremony, nested ternaries |
+      | Structure | Improve organization | Mixed concerns, tight coupling, bloated interfaces, god objects, too many parameters, hidden dependencies |
+      | Waste | Eliminate what should not exist | Duplication, dead code, unused abstractions, speculative generality, copy-paste patterns, unreachable paths |
+    }
+  }
+
+  Workflow {
+    Phase1_EstablishBaseline {
+      Before ANY refactoring:
+
+      1. Locate target code
+      2. Run existing tests to establish baseline
+      3. Report baseline status:
+
+      ```
+      Refactoring Baseline
+
+      Tests: [X] passing, [Y] failing
+      Coverage: [Z]%
+      Uncovered areas: [List critical paths]
+
+      Baseline Status: READY | TESTS FAILING | COVERAGE GAP
+      ```
+
+      4. If tests failing: Stop and report to user
+      5. If uncovered code found: Flag for user decision before proceeding
+    }
+
+    Phase2_Analysis {
+      Launch parallel analysis agents per the active analysis mode perspectives
+
+      For each perspective, describe the analysis intent:
+
+      ```
+      Analyze [PERSPECTIVE] for refactoring:
+
+      CONTEXT:
+      - Target: [Code to refactor]
+      - Scope: [Module/feature boundaries]
+      - Baseline: [Test status, coverage %]
+
+      FOCUS: [What this perspective analyzes -- from perspectives table]
+
+      OUTPUT: Return findings as:
+      - impact: HIGH | MEDIUM | LOW
+      - title: Brief title (max 40 chars)
+      - location: file:line
+      - problem: One sentence describing what's wrong
+      - refactoring: Specific technique to apply
+      - risk: Potential complications
+
+      If no findings: NO_FINDINGS
+      ```
+
+      Synthesis {
+        1. Collect all findings from analysis agents
+        2. Deduplicate overlapping issues
+        3. Rank by: Impact (High > Medium > Low), then Risk (Low risk first)
+        4. Sequence refactorings: Independent changes first, dependent changes after
+        5. Present findings:
+
+        ```markdown
+        ## Refactoring Analysis: [target]
+
+        ### Summary
+
+        | Perspective | High | Medium | Low |
+        |-------------|------|--------|-----|
+        | [Perspective 1] | X | X | X |
+        | **Total** | X | X | X |
+
+        *High Impact Issues*
+
+        | ID | Finding | Remediation | Risk |
+        |----|---------|-------------|------|
+        | H1 | Brief title *(file:line)* | Specific technique *(problem)* | Risk level |
+
+        *Medium Impact Issues*
+
+        | ID | Finding | Remediation | Risk |
+        |----|---------|-------------|------|
+        | M1 | Brief title *(file:line)* | Specific technique *(problem)* | Risk level |
+
+        *Low Impact Issues*
+
+        | ID | Finding | Remediation | Risk |
+        |----|---------|-------------|------|
+        | L1 | Brief title *(file:line)* | Specific technique *(problem)* | Risk level |
+        ```
+
+        6. Offer options via question:
+           - "Document and proceed" -- Save plan to `docs/refactor/[NNN]-[name].md`, then execute
+           - "Proceed without documenting" -- Execute refactorings directly
+           - "Cancel" -- Abort refactoring
+      }
+    }
+
+    Phase3_ExecuteChanges {
+      One refactoring at a time -- never batch changes before verification
+
+      For EACH change in the prioritized sequence:
+
+      1. Apply single change
+      2. Run tests immediately
+      3. If pass: Mark complete, continue to next
+      4. If fail: Revert change, report failure, offer options:
+         - Try alternative approach
+         - Add tests first
+         - Skip this refactoring
+         - Get user guidance
+    }
+
+    Phase4_FinalValidation {
+      1. Run complete test suite
+      2. Compare behavior with baseline
+      3. Present results:
+
+      ```markdown
+      ## Refactoring Complete: [target]
+
+      **Status**: Complete | Partial - [reason]
+
+      ### Before / After
+
+      | File | Before | After | Technique |
+      |------|--------|-------|-----------|
+      | billing.ts | 75-line method | 4 functions, 20 lines each | Extract Method |
+
+      ### Verification
+
+      - Tests: [X] passing (baseline: [Y])
+      - Behavior: Preserved
+      - Coverage: [Z]% (baseline: [W]%)
+
+      ### Quality Improvements
+
+      - [Improvement 1]
+
+      ### Skipped
+
+      - [file:line] - [reason]
+      ```
+
+      4. Offer options via question:
+         - "Commit these changes"
+         - "Run full test suite"
+         - "Address skipped items (add tests first)"
+         - "Done"
+    }
+  }
+
+  AgentDelegationTemplate {
+    When delegating refactoring tasks:
+
+    ```
+    FOCUS: [Specific refactoring]
+      - Apply [refactoring technique] to [target]
+      - Preserve all external behavior
+      - Run tests after change
+
+    EXCLUDE: [Other code, unrelated improvements]
+      - Stay within specified scope
+      - Preserve existing feature set
+      - Maintain identical behavior
+
+    CONTEXT:
+      - Baseline tests passing
+      - Target smell: [What we're fixing]
+      - Expected improvement: [What gets better]
+
+    OUTPUT:
+      - Refactored code
+      - Test results
+      - Summary of changes
+
+    SUCCESS:
+      - Tests still pass
+      - Smell eliminated
+      - Behavior preserved
+
+    TERMINATION: Refactoring complete OR tests fail
+    ```
+  }
+
+  CommonRefactorings {
+    | Smell | Refactoring |
+    |-------|-------------|
+    | Long Method | Extract Method |
+    | Duplicate Code | Extract Method, Pull Up Method |
+    | Long Parameter List | Introduce Parameter Object |
+    | Complex Conditional | Decompose Conditional, Guard Clauses |
+    | Large Class | Extract Class |
+    | Feature Envy | Move Method |
+    | Dead Code | Remove Dead Code |
+    | Speculative Generality | Collapse Hierarchy, Inline Class |
+  }
+
+  BehaviorPreservationChecklist {
+    Before EVERY refactoring:
+
+    - [ ] Tests exist and pass
+    - [ ] Baseline behavior documented
+    - [ ] Single refactoring at a time
+    - [ ] Tests run after EVERY change
+    - [ ] No functional changes mixed with refactoring
+  }
+
+  AntiPatterns {
+    DoNotMixRefactoringWithFeatureChanges {
+      Separate commits: one for structural changes, another for new behavior
+    }
+
+    DoNotRefactorWithoutTests {
+      If code is not covered by tests:
+      1. Add characterization tests first
+      2. Then refactor
+      3. Or skip and document technical debt
+    }
+
+    DoNotRefactorEverythingAtOnce {
+      Prioritize by:
+      1. Code you are actively working on
+      2. Code with highest change frequency
+      3. Code with most bugs
+    }
+  }
+}
+
+## References
+
+- [reference/code-smells.md](reference/code-smells.md) -- Code smell catalog and refactoring strategies

package/opencode/skill/safe-refactoring/reference/code-smells.md

@@ -0,0 +1,347 @@
+# Refactoring Reference
+
+## Code Smells Catalog
+
+### Method-Level Smells
+
+| Smell | Symptoms | Refactorings |
+|-------|----------|--------------|
+| Long Method | >20 lines, multiple responsibilities | Extract Method, Decompose Conditional |
+| Long Parameter List | >3-4 parameters | Introduce Parameter Object, Preserve Whole Object |
+| Duplicate Code | Same/similar logic in multiple places | Extract Method, Pull Up Method, Form Template Method |
+| Complex Conditionals | Nested if/else, switch statements | Decompose Conditional, Replace with Guard Clauses |
+| Feature Envy | Method uses more data from other class | Move Method, Move Field |
+| Data Clumps | Same group of variables passed together | Extract Class, Introduce Parameter Object |
+| Speculative Generality | Unused abstractions "for the future" | Collapse Hierarchy, Inline Class, Remove Parameter |
+| Dead Code | Unreachable or unused code | Remove Dead Code |
+
+### Class-Level Smells
+
+| Smell | Symptoms | Refactorings |
+|-------|----------|--------------|
+| Large Class | >200 lines, multiple responsibilities | Extract Class, Extract Subclass |
+| God Class | Knows too much, does too much | Extract Class, Move Method |
+| Data Class | Only getters/setters, no behavior | Move Method into class, Encapsulate Field |
+| Primitive Obsession | Overuse of primitives for domain concepts | Replace Primitive with Object, Extract Class |
+| Refused Bequest | Subclass doesn't use inherited members | Replace Inheritance with Delegation |
+| Lazy Class | Class that doesn't do enough | Inline Class, Collapse Hierarchy |
+| Middle Man | Class that only delegates | Remove Middle Man, Inline Method |
+| Parallel Inheritance | Every time you subclass A, you must subclass B | Move Method, Move Field |
+
+### Architecture-Level Smells
+
+| Smell | Symptoms | Refactorings |
+|-------|----------|--------------|
+| Circular Dependencies | A->B->C->A | Dependency Inversion, Extract Interface |
+| Inappropriate Intimacy | Classes too coupled | Move Method, Hide Delegate, Change Bidirectional to Unidirectional |
+| Shotgun Surgery | One change requires many file edits | Move Method, Inline Class |
+| Divergent Change | One class changed for different reasons | Extract Class |
+| Message Chains | a.getB().getC().getD() | Hide Delegate, Extract Method |
+| Comments (excessive) | Comments explaining bad code | Extract Method, Rename Method, Introduce Assertion |
+
+---
+
+## Safe Refactoring Patterns
+
+### Extract Method
+
+**When**: Long method with embedded logic blocks
+
+**Before**:
+```javascript
+function processOrder(order) {
+  // Validate order
+  if (!order.items || order.items.length === 0) {
+    throw new Error('Order must have items');
+  }
+  if (!order.customer) {
+    throw new Error('Order must have customer');
+  }
+
+  // Calculate total
+  let total = 0;
+  for (const item of order.items) {
+    total += item.price * item.quantity;
+  }
+
+  // Apply discount
+  if (order.discountCode) {
+    total = total * 0.9;
+  }
+
+  return { ...order, total };
+}
+```
+
+**After**:
+```javascript
+function processOrder(order) {
+  validateOrder(order);
+  const total = calculateTotal(order.items, order.discountCode);
+  return { ...order, total };
+}
+
+function validateOrder(order) {
+  if (!order.items || order.items.length === 0) {
+    throw new Error('Order must have items');
+  }
+  if (!order.customer) {
+    throw new Error('Order must have customer');
+  }
+}
+
+function calculateTotal(items, discountCode) {
+  let total = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+  if (discountCode) {
+    total = total * 0.9;
+  }
+  return total;
+}
+```
+
+**Safety**: Run tests after each extraction
+
+---
+
+### Rename (Variable/Method/Class)
+
+**When**: Names don't reveal intent
+
+**Before**:
+```javascript
+const d = new Date();
+function calc(x, y) {
+  return x * y * 0.15;
+}
+```
+
+**After**:
+```javascript
+const orderDate = new Date();
+function calculateTax(subtotal, taxRate) {
+  return subtotal * taxRate;
+}
+```
+
+**Safety**: Use IDE refactoring tools for automatic updates across codebase
+
+---
+
+### Move Method/Field
+
+**When**: Method uses more data from another class than its own
+
+**Before**:
+```javascript
+class Order {
+  calculateShipping(customer) {
+    // Uses customer data extensively
+    if (customer.isPremium) return 0;
+    if (customer.country === 'US') return 5;
+    return 15;
+  }
+}
+```
+
+**After**:
+```javascript
+class Customer {
+  calculateShippingFor(order) {
+    if (this.isPremium) return 0;
+    if (this.country === 'US') return 5;
+    return 15;
+  }
+}
+
+class Order {
+  calculateShipping(customer) {
+    return customer.calculateShippingFor(this);
+  }
+}
+```
+
+**Safety**: Update all callers, run tests
+
+---
+
+### Replace Conditional with Guard Clauses
+
+**When**: Nested conditionals obscure the main path
+
+**Before**:
+```javascript
+function getPayAmount(employee) {
+  let result;
+  if (employee.isSeparated) {
+    result = { amount: 0, reason: 'separated' };
+  } else {
+    if (employee.isRetired) {
+      result = { amount: 0, reason: 'retired' };
+    } else {
+      result = { amount: employee.salary, reason: 'active' };
+    }
+  }
+  return result;
+}
+```
+
+**After**:
+```javascript
+function getPayAmount(employee) {
+  if (employee.isSeparated) {
+    return { amount: 0, reason: 'separated' };
+  }
+  if (employee.isRetired) {
+    return { amount: 0, reason: 'retired' };
+  }
+  return { amount: employee.salary, reason: 'active' };
+}
+```
+
+**Safety**: Ensure all paths tested before refactoring
+
+---
+
+### Introduce Parameter Object
+
+**When**: Same group of parameters passed together frequently
+
+**Before**:
+```javascript
+function createBooking(startDate, endDate, roomType, guestName, guestEmail) {
+  // ...
+}
+
+function validateBooking(startDate, endDate, roomType) {
+  // ...
+}
+
+function calculatePrice(startDate, endDate, roomType) {
+  // ...
+}
+```
+
+**After**:
+```javascript
+class BookingRequest {
+  constructor(startDate, endDate, roomType, guestName, guestEmail) {
+    this.startDate = startDate;
+    this.endDate = endDate;
+    this.roomType = roomType;
+    this.guestName = guestName;
+    this.guestEmail = guestEmail;
+  }
+}
+
+function createBooking(request) {
+  // ...
+}
+
+function validateBooking(request) {
+  // ...
+}
+
+function calculatePrice(request) {
+  // ...
+}
+```
+
+**Safety**: Update all call sites, run tests
+
+---
+
+### Extract Class
+
+**When**: One class has multiple responsibilities
+
+**Before**:
+```javascript
+class User {
+  name;
+  email;
+
+  // User data methods
+  getName() { return this.name; }
+  setName(name) { this.name = name; }
+
+  // Email methods (separate concern)
+  sendWelcomeEmail() { /* ... */ }
+  sendPasswordReset() { /* ... */ }
+  validateEmail() { /* ... */ }
+}
+```
+
+**After**:
+```javascript
+class User {
+  name;
+  email;
+  emailService;
+
+  getName() { return this.name; }
+  setName(name) { this.name = name; }
+}
+
+class EmailService {
+  sendWelcomeEmail(user) { /* ... */ }
+  sendPasswordReset(user) { /* ... */ }
+  validateEmail(email) { /* ... */ }
+}
+```
+
+**Safety**: Update all dependencies, run tests
+
+---
+
+## Behavior Preservation Checklist
+
+Before ANY refactoring:
+
+- [ ] Tests exist and pass
+- [ ] Baseline behavior documented
+- [ ] Single refactoring at a time
+- [ ] Tests run after EVERY change
+- [ ] No functional changes mixed with refactoring
+
+---
+
+## Refactoring Decision Matrix
+
+| Situation | Action |
+|-----------|--------|
+| Tests passing, clear smell | Proceed with refactoring |
+| Tests passing, unclear benefit | Skip or discuss with team |
+| Tests failing | Fix tests first, then refactor |
+| No tests for area | Add tests first OR skip refactoring |
+| Behavior change required | Not refactoring - this is a feature change |
+
+---
+
+## Anti-Patterns to Avoid
+
+### Don't Mix Refactoring with Feature Changes
+
+**Wrong**:
+```
+Commit: "Refactor user service and add email validation"
+```
+
+**Right**:
+```
+Commit 1: "Refactor: Extract email methods from UserService"
+Commit 2: "Feature: Add email validation to registration"
+```
+
+### Don't Refactor Without Tests
+
+If code isn't covered by tests:
+1. Add characterization tests first
+2. Then refactor
+3. Or skip and document technical debt
+
+### Don't Refactor Everything at Once
+
+Prioritize by:
+1. Code you're actively working on
+2. Code with highest change frequency
+3. Code with most bugs