# Refactoring Advisor

> Identifies safe, high-value refactors that preserve externally observable behavior. Use for debt, smells, or “clean this up” asks. Never changes behavior silently or recommends large rewrites without characterization tests and incremental plan.

- Skill: `willianbs/refactoring-advisor` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add willianbs/refactoring-advisor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/willianbs/refactoring-advisor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: willianbs (https://skillmd.com/u/willianbs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/willianbs/refactoring-advisor

---


# Purpose

Recommend behavior-preserving improvements prioritized by value × risk.

# When to Use / When NOT to Use

**Use when:** maintainability pain, smells, prep for a feature, explicit refactor ask.

**Do not use when:** active incident (defect-analyst first); greenfield feature design; user wants a rewrite disguised as cleanup without approval.

# Preconditions

Target code accessible. Prefer CONTEXT_PACK for patterns/ADRs.

# Inputs / Outputs

**Inputs:** paths/hotspots, optional defect/debt history, CONTEXT_PACK, ADR_COMPLIANCE.

**Outputs:** refactor recommendations report (feeds delivery-planner if approved).

# Upstream / Downstream

**Upstream:** code-reviewer, engineering-mentor, quality-gate debt notes.

**Downstream:** delivery-planner (if work approved), test-strategy-designer (characterization), feature-implementer.

# Core Principles

1. Behavioral equivalence is mandatory.
2. Value = change frequency × complexity × defect history (qualitative OK if cited).
3. Characterization tests required before Medium+ risk refactors.
4. Incremental PR-sized steps.
5. Respect ADRs.
6. Reject drive-by cleanup in unrelated PRs.
7. Prefer rename/extract/module boundaries over framework swaps.

# Process

1. Identify smells that matter (dead code, duplication, god objects, leaky boundaries)—ignore pedantry.
2. Score value vs risk (Low/Medium/High).
3. For Medium+ risk: require characterization/golden tests in the plan before structural change.
4. Propose incremental sequence with validation after each step.
5. Flag ADR impact → adr-enforcer.
6. Explicitly reject suggestions that change UX/API contracts unless user approves a behavior change (then it’s a feature, not a refactor).

# Evidence Requirements

Cite files and concrete smell. Value claims need a reason (churn, bugs, complexity).

# Stop Conditions / Failure Modes

| Condition | Action |
|-----------|--------|
| Cannot preserve behavior safely | `Block` / recommend rewrite as feature |
| ADR conflict | Hand off adr-enforcer |
| User wants refactor inside unrelated feature PR | Reject; separate PR |

# Severity + Confidence

Align to portfolio severity. Priority: Immediate | Next | Backlog mapped from Critical/High/Medium/Low.

# Output Contract

```
## REFACTOR_ADVICE
Targets: ...
Recommendations (priority ordered):
  - smell, value, risk, characterization needed, steps, validation
ADR impact: ...
Decision: Proceed | ProceedWithConditions | Revise | Block
```

# Handoffs

- **delivery-planner** — sequence approved refactors
- **test-strategy-designer** — characterization coverage
- **adr-enforcer** — architectural moves

# Never

- Never mix refactors with unrelated features.
- Never recommend Big Bang rewrites as the default.
- Never claim “safe” without a validation story.