Should I refactor during a bug fix?

Not recommended. Fix the bug first, then propose a separate refactor with explicit approval.

What if there are no tests for the code being refactored?

Write tests first to establish a safety net, then refactor.

How do I know the refactor didn’t change behavior?

Rely on tests to verify behavior, and run npm test and npm run build to ensure parity.

pwp-refactor

Scanned

npx machina-cli add skill shandar/pwp-plugin/pwp-refactor --openclaw

Files (1)

SKILL.md

3.7 KB

Refactoring Skill

This skill defines how to refactor code safely. The cardinal rule: refactoring changes structure, never behavior. If behavior changes, it's not a refactor — it's a feature or a fix.

Refactoring Mindset

Refactoring is not cleaning. It's restructuring code to make it easier to understand, extend, or maintain. It requires the same rigor as writing new features.
Never refactor and change behavior in the same commit. Mixing structural changes with behavioral changes makes review impossible and debugging a nightmare.
Tests are your safety net. If tests don't exist for the code you're refactoring, write them first.
Approval required. Do not refactor code you weren't asked to touch. Flag ugly code, but don't fix it without explicit approval.

When to Refactor

Signal	Example	Action
Duplication	Same logic in 3+ places	Extract to shared function/component
Complexity	Function > 50 lines, deeply nested conditionals	Decompose into smaller functions
Naming	Misleading or abbreviated names	Rename for clarity
God files	File > 500 lines mixing concerns	Split by responsibility
Dead code	Unused imports, unreachable branches	Remove
Type weakness	`any` types, missing interfaces	Add proper types

When NOT to Refactor

During a bug fix (fix the bug, then propose a refactor separately)
Without tests for the affected code
Without explicit approval from the user/team
When you're "just making it better" without a concrete improvement goal
In the same commit as a feature change

Refactoring Protocol

Step 1: Justify

State what you want to refactor and why
Quantify the improvement: "Reduces duplication from 3 copies to 1"

Step 2: Ensure Safety Net

Verify tests exist for the code being refactored
If tests are missing: write them first, commit them separately, then refactor

Step 3: Plan the Changes

List every file that will change
Identify the refactoring pattern
Declare the scope boundary: "I will only touch files X, Y, Z"

Step 4: Execute

One refactoring pattern per commit
Run tests after each step
If tests break, revert and investigate

Step 5: Verify

# Before and after must match
npm test → all pass
npm run build → exits 0

Common Refactoring Patterns

Extract Function: Long function → smaller functions with clear names
Extract Component: Large component → focused components composed together
Rename: Misleading names → descriptive, consistent names
Move / Reorganize: Code in wrong file → logical location
Inline: Unnecessary abstraction → logic inlined where used
Simplify Conditionals: Nested if/else → guard clauses, early returns

Anti-Patterns

Anti-Pattern	Why It's Wrong
Refactoring while fixing a bug	Can't tell if the bug fix works or the refactor broke something
Refactoring without tests	No safety net — behavior changes go undetected
"While I'm here" refactoring	Scope creep — stay within declared boundaries
Premature abstraction	Extracting a pattern seen only once adds complexity
Renaming everything at once	High blast radius — rename incrementally

Source

git clone https://github.com/shandar/pwp-plugin/blob/main/skills/pwp-refactor/SKILL.mdView on GitHub

Overview

pwp-refactor provides a safe protocol to restructure code without altering behavior. It emphasizes tests as safety nets, incremental commits, and explicit scope. Use it when files grow too big, have duplication, or confusing names.

How This Skill Works

Follow the protocol: 1) Justify what you refactor and why. 2) Ensure a safety net by verifying tests exist (or write them first). 3) Plan changes by listing affected files, the refactoring pattern, and scope. 4) Execute with one refactoring pattern per commit and run tests after each step. 5) Verify that before/after parity holds by running npm test and npm run build.

When to Use It

Duplication: same logic in 3+ places; extract to a shared function or component.
Complexity: long functions or deeply nested conditionals; decompose into smaller pieces.
Naming: misleading or abbreviated names; rename for clarity.
God files: files > 500 lines with mixed concerns; split by responsibility.
Dead code or type weaknesses: unused imports, missing interfaces, or weak types; remove or strengthen types.

Quick Start

Step 1: Identify a candidate with duplication, complexity, or naming issues and justify the refactor.
Step 2: Ensure tests exist (or add them) to safety-net the change.
Step 3: Plan changes (files involved, pattern), implement one refactoring per commit, and run tests/build after each step.

Best Practices

Always ensure tests exist for the code being refactored, or write them first.
Make one refactoring pattern per commit to keep changes isolated.
Declare the exact scope and touched files before changing anything.
Run tests after each step and revert if any test breaks.
Document the rationale and scope of the change for reviewers.

Example Use Cases

Extract a shared utility from three duplicates into one function.
Rename a misleading function name to reflect its behavior.
Move a component to its own module to reduce god files.
Inline a trivial wrapper to remove needless abstraction.
Simplify nested conditionals using guard clauses and early returns.

Frequently Asked Questions

Add this skill to your agents