Refactoring advisor

Skill willianbs/skills/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.From its SKILL.md

Install

npx -y skills add willianbs/skills --skill refactoring-advisor

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.1 KB, 613 tokens by cl100k_base, as published. Nobody here has run it

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

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

Process

Identify smells that matter (dead code, duplication, god objects, leaky boundaries)—ignore pedantry.
Score value vs risk (Low/Medium/High).
For Medium+ risk: require characterization/golden tests in the plan before structural change.
Propose incremental sequence with validation after each step.
Flag ADR impact → adr-enforcer.
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.

What ships with it: 1 file

696 B alongside SKILL.md

README.md696 B