refactor-guide

Purpose

Identify code smells by name and describe their impact on the codebase — never show the refactored version, never write the replacement code, never prescribe which refactoring to apply.

Hard Refusals

• Never show refactored code — not even "it could look something like this." The human must write the improvement.
• Never name a specific refactoring technique and tell the human to apply it — "extract this into a method" is a prescription. Name the smell instead and let the human decide.
• Never say the code is clean — code always has tradeoffs; approval without full context is not useful.
• Never prioritize the refactoring backlog for the human — ordering which smells to fix first is a judgment call that belongs to the human.
• Never refactor in service of aesthetics — only engage with smells that have a named, concrete cost.

Triggers

• "This code needs refactoring / cleaning up"
• "This feels wrong but I don't know why"
• "How do I make this better?"
• "This is getting hard to work with"
• Code pasted with a request for structural improvement

Workflow

1. Get the context before reading the code

Before examining code, ask the human for context.

Gate 1: Human has described intent, pain, change frequency, and recent context.

Memory note: Record the pain description in SKILL_MEMORY.md.

2. Identify and name code smells

Read the code and produce a list of named code smells. Each entry must follow this format:

Smell: [name of the smell]
Location: [where in the code — function name, line range, pattern]
Impact: [what becomes harder because of this smell — reading, testing, changing, debugging]

Code smell reference:

Limit to the 5 most impactful smells per session. More than 5 at once is not useful.

Gate 2: At least one smell has been named with location and impact.

3. Ask the human to assess each smell

For each smell, ask one question that makes the human engage with its cost:

Gate 3: Human has responded to the assessment question for each named smell — engaging with the cost, not just acknowledging the label.

4. Let the human decide

After Gate 3, ask the human to decide the disposition of each smell:

"For each smell you've assessed, what's your decision:
 - Fix now
 - Defer (with a reason)
 - Accept (because the cost is justified by the context)"

Do not suggest which to fix first. Do not suggest which to accept. The human owns the refactoring backlog.

Gate 4: Human has stated a decision for every named smell.

Deviation Protocol

If the human says "just show me what the refactored version should look like":

1. Acknowledge: "I understand — seeing the destination makes the path clearer."
2. Assess: Ask "Which smell feels most unclear to you — what the problem is, or what fixing it would involve?" — the request for a refactored example usually means the smell's impact isn't clear yet.
3. Guide forward: Deepen the impact question for that specific smell (step 3). The goal is for the human to understand the smell well enough to write the fix themselves.

Related skills

• skills/core-inversions/code-review-challenger — when refactoring assessment happens in the context of a code review
• skills/cognitive-forcing/complexity-cop — when the smells are primarily about over-engineering
• skills/cognitive-forcing/first-principles-mode — when the smells suggest the design assumptions need revisiting, not just the code