| name | refactor |
| description | Analyze a codebase for quality issues across code smells, clean code, separation of concerns, modularity, and API-first design, then generate a prioritized refactoring report and gated execution roadmap (characterization safety net, commit discipline, delete packet, close-out delta). |
| context | fork |
| policy_doc_kind | skill |
| classification | canonical |
| canonical_owner | self |
| authority_level | procedural |
| in_verifier_scope | true |
| lexical_guard_profile | stale_names,destructive_rollback,branch_policy_live |
/refactor - Codebase Analysis And Refactoring
This skill owns the refactor workflow and its gates. Global policy owns runtime routing, git policy, review requirements, and delivery constraints; ~/.claude/standards/testing-standard.md owns test-breadth definitions; the planner agent owns DAG mechanics.
Usage
/refactor /path/to/project
/refactor /path/to/project --focus api,modularity
/refactor /path/to/project --report-only
/refactor /path/to/project --depth shallow
Flags
| Flag | Effect |
|---|
(none) | Full analysis and roadmap generation |
--focus X,Y | Limit the dimensions analyzed |
--report-only | Produce findings without build-spec generation |
--depth shallow | Skip deep architecture tooling |
Workflow
0. Forcing-reason gate
Refactor execution requires a recorded forcing reason — one of:
- blocked feature (name it)
- defect cluster (cite the incidents or issues)
- performance wall (cite the measurement)
- compliance or security finding (cite it)
"Looks legacy" or style preference fails the gate. --report-only analysis is exempt; build-spec generation and all execution require the forcing reason recorded in the report header.
1. Detect and index
- detect stack and layout
- read local docs that affect architecture
- use RLM for deep analysis when the repo and task justify it
2. Analyze five dimensions
For each finding, report:
- what is wrong
- where it is
- severity
- recommended remediation
Dimensions:
- code smells
- clean code
- separation of concerns
- modularity
- API-first design
3. Heuristic scans → baseline
Gather supporting metrics such as:
- file count
- LOC
- test coverage ratio when available
- largest files
- lint suppressions
- TODO count
any count
