Small Refactor

Safely restructures a small code unit (under 100 lines) to improve readability, reduce cyclomatic complexity, or eliminate code duplication. External behavior is 100% preserved.

1. Purpose

Improve internal code structure without changing what it does. A "Refactor" preserves existing inputs, outputs, side-effects, and passes existing tests before and after.

2. When to Use

Use this skill when:

• Simplifying deeply nested if/else statements.
• Extracting a reusable helper function within a module.
• Renaming confusing internal variables for clarity.

3. When Not to Use

• Do not use to fix bugs or change logic; use minimal-bug-fix.
• Do not use across entire architectures or multi-module refactors; use step-decomposer.

4. Required Inputs

• target_file: Path to the file containing the function.
• function_name: The specific function or method to refactor.
• refactor_goal: The exact structural improvement (e.g. "Extract validation helper", "Flatten nested loops").

5. Missing-Input Behavior

1. If existing tests do not cover the target function: stop and use regression-test-writer to add test coverage before refactoring.
2. If function_name is not found in file: stop and verify function name.
3. Never change external function signatures or return types.

6. Procedure

Follow these numbered actions:

1. Action 1: Run Existing Tests (Baseline)
   • Run project test runner. Ensure 100% pass before starting.
2. Action 2: Plan Structural Simplification
   • Apply standard refactoring patterns: early returns, guard clauses, extracting small pure functions.
3. Action 3: Apply Refactored Code
   • Edit the target file cleanly.
4. Action 4: Run Existing Tests (Validation)
   • Run the same test suite. Confirm 100% pass.
5. Action 5: If Tests Fail, Revert Immediately
   • Revert changes via git and explain the behavioral discrepancy.
6. Action 6: Emit Refactor Summary
   • Format per Section 8.

7. Decision Rules

• If test suite fails after refactor: immediate rollback. Do not "fix the test" unless the user explicitly requested a test change.
• Never add new external dependencies during a small refactor.

8. Output Format

Emit the refactor summary using this template:

### Small Refactor: [Function Name] in [Target File]

- **Target Unit**: `[Function Name]`
- **Refactor Goal**: [e.g. Flatten nested conditionals with early returns]
- **Baseline Test Status**: [PASS]
- **Post-Refactor Test Status**: [PASS]

#### Before & After Comparison
```diff
[Diff showing simplification]

Verification Proof

• Test command: [e.g. npm test] -> [Output confirming all tests passed]

## 9. Verification Checklist
- [ ] Existing tests passed before editing.
- [ ] Existing tests passed after editing without modification.
- [ ] Function signature and return values remained identical.
- [ ] No new dependencies were added.

## 10. Common Failures and Recovery
| Failure Symptom | Cause | Recovery Action |
| :--- | :--- | :--- |
| Broken edge behavior | Over-simplifying condition | Revert and preserve exact original boolean expression. |
| Test failure after refactor | Unintended side effect changed | Rollback immediately; do not alter existing test assertions. |

## 11. Stop or Escalation Conditions
Stop and ask the user when:
- No automated tests exist for the target function and user prohibits adding test files.

## 12. Examples

### Example 1: Successful Execution
**Input:**
```text
Target: src/discount.js
Function: getDiscount
Goal: Use guard clauses to replace 3-level nested if statements.

Output:

### Small Refactor: getDiscount in src/discount.js

- **Target Unit**: `getDiscount`
- **Refactor Goal**: Flatten 3-level nested if statements with guard clauses
- **Baseline Test Status**: PASS
- **Post-Refactor Test Status**: PASS

#### Before & After Comparison
```diff
 function getDiscount(user) {
-  if (user) {
-    if (user.isActive) {
-      if (user.isVip) {
-        return 0.20;
-      }
-      return 0.10;
-    }
-  }
-  return 0.0;
+  if (!user || !user.isActive) {
+    return 0.0;
+  }
+  return user.isVip ? 0.20 : 0.10;
 }

Verification Proof

• Test command: npm test tests/discount.test.js -> 6 passed, 0 failed

### Example 2: Ambiguous or Missing Input
**Input:**
```text
Refactor the app.

Output:

### Small Refactor: Halted - Scope Too Broad

- **Status**: Halted

"Refactor the app" is too large for a small refactor. Please specify:
1. Target file path.
2. Target function or class name (under 100 lines).
3. Specific structural goal.

Example 3: Expected Final Output

Output:

### Small Refactor: formatAddress in utils/address.ts

- **Target Unit**: `formatAddress`
- **Refactor Goal**: Extract postal code formatter to private helper
- **Baseline Test Status**: PASS
- **Post-Refactor Test Status**: PASS

#### Before & After Comparison
```diff
+function formatPostalCode(zip: string): string {
+    return zip.trim().toUpperCase();
+}
+
 export function formatAddress(addr: Address): string {
-    const cleanZip = addr.zip.trim().toUpperCase();
+    const cleanZip = formatPostalCode(addr.zip);
     return `${addr.street}, ${addr.city} ${cleanZip}`;
 }

Verification Proof

• Test command: npm test -> 14 passed, 0 failed