refactor-for-reuse

Files (1)

• SKILL.md

SKILL.md (first lines)

# Refactor for Reuse

## Overview

Eliminate redundancy and promote reuse while preserving exact behavior. The goal is not fewer lines — it's code where every piece of logic exists once, dead code is gone, and shared patterns are extracted where they belong. Every change must pass: "Does this remove duplication or dead weight without changing what the code does?"

## When to Use

- After tests pass when the same logic appears in two or more places
- When code was written under time pressure and copy-pasted rather than extracted
- When consolidating related logic scattered across files or modules
- After merging changes that introduced duplication or inconsistency
- When dead code has accumulated — unreachable branches, unused variables, commented-out blocks
- When a wrapper, abstraction, or pattern adds no value over calling the underlying code directly

**When NOT to use:**

- The duplication is intentional — two similar things that will diverge (premature abstraction is worse than duplication)
- You don't fully understand why the code exists — apply Chesterton's Fence before extracting
- The "shared" logic would create a coupling between unrelated modules
- You're about to rewrite the module entirely — refactoring throwaway code wastes effort
- The issue is readability, naming, or structural complexity — use `refactor-for-clarity` instead

## The Four Principles

### 1. Preserve Behavior Exactly

Don't change what the code does — only how it's structured. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a refactor preserves behavior, don't make it.

```
ASK BEFORE EVERY CHANGE:
→ Does this produce the same output for every input?
→ Does this maintain the same error behavior?
→ Does this preserve the same side effects and ordering?
→ Do all existing tests still pass without modification?
```

### 2. Follow Project Conventions

Refactoring means making code more consistent with the codebase, not imposing external preferences. Before extracting or consolidating:

```
1. Read AGENTS.md or CLAUDE.md / project conventions
2. Study how neighboring code handles similar patterns
3. Match the project's style for:
   - Import ordering and module system
   - Function declaration style
   - Naming conventions
   - Error handling patterns
   - Type annotation depth
```

Refactoring that breaks project consistency is not improvement — it's churn.

### 3. Extract Intent, Not Coincidence

Refactoring has a failure mode: extracting things that look the same but aren't. Watch for these traps:

- **Extracting coincidental duplication** — two functions that happen to look alike now but will diverge; premature extraction creates coupling that costs more than the duplication did
- **Over-extracting small helpers** — a two-line helper used once adds indirection without reuse value
- **Merging unrelated logic** — two things that share structure but serve different purposes should stay separate
- **Optimizing for DRY as a rule** — DRY is a heuristic, not a law; the goal is reducing accidental coupling, not eliminating every repeated token

### 4. Scope to What Changed

Default to refactoring recently modified code. Avoid drive-by changes to unrelated code unless explicitly asked to broaden scope. Unscoped refactoring creates noise in diffs and risks unintended regressions.

## The Refactoring Process

### Step 1: Verify Test Coverage

Before touching anything, confirm the code you're about to refactor is covered by tests. Tests are the only proof that behavior is preserved after structural changes.

If coverage is missing: invoke **`test-driven-development`** to write characterization tests first — tests that pin the current behavior before any refactoring begins. Commit them before proceeding.

If the code's behavior is unclear before writing tests: invoke **`verify-before-claim`** — open the actual files and confirm what the code does before asserting it.

### Step 2: Understand Before Touching (Chesterton's Fence)

Before extracting or removing anything, understand why it exists.

```
BEFORE REFACTORING, ANSWER:
- What is this code's responsibility?
- What calls it? What does it call?
- Why might duplication exist here? (intentional divergence? historical copy-paste?)
- Check git blame: was this written under time pressure, or deliberately structured this way?
```

If you can't answer these, you're not ready to refactor. Read more context first.

### Step 3: Identify Redundancy

Scan for these patterns — each one is a concrete signal, not a vague smell:

| Pattern | Signal | Refactoring |
|---------|--------|-------------|
| Duplicated logic | Same 5+ lines in multiple places | Extract to a shared function |
| Dead code | Unreachable branches, unused variables, commented-out blocks | Remove (after confirming it's truly dead) |
| Unnecessary abstractions | Wrapper that adds no value | Inline the wrapper, call the underlying function directly |
| Over-engineered patterns | Factory-for-a-factory, strategy-with-one-strategy | Replace with the simple direct approach |
| Redundant type assertions | Casting to a type that's already inferred | Remove the assertion |

### Step 4: Apply Changes Incrementally

Make one refactoring at a time. Run tests after each change. **Submit refactoring changes separately from feature or bug fix changes.**

```
FOR EACH REFACTORING:
1. Make the change
2. Run the test suite
3. If tests pass → commit (or continue to next)
4. If tests fail → revert and reconsider — do NOT modify tests to force a pass
```

Avoid batching multiple changes into a single untested step. If something breaks, you need to know which change caused it.

**The Rule of 500:** If a refactoring would touch more than 500 lines, invest in automation (codemods, sed scripts, AST transforms) rather than making the changes by hand.

From eyalgo/kensaiapp, MIT.

More from eyalgo/kensaiapp