code-refactor

Files (1)

• SKILL.md

SKILL.md (first lines)

Conduct a deep technical review of this codebase with the goal of determining how it should
be refactored.

**Do not begin by changing code.** First understand the system as it exists: what problem it
solves, how it is organized, what constraints appear to have shaped it, and where its
current design helps or hinders future work. This is an architectural and implementation
review, not a linting exercise.

Do not assume that more abstraction, more layering, more interfaces, more files, or more
design patterns constitute improvement. Prefer the simplest design that accurately expresses
the domain and satisfies the real requirements.

Scope the review to `$ARGUMENTS` if provided, otherwise treat the whole repository as in
scope. Examples: `the storage layer`, `cmd/`, `the plugin system`.

Skip vendored dependencies, build output, generated code, and lockfiles (`node_modules/`,
`dist/`, `vendor/`, `*.min.js`, `go.sum`).

## Phase one — understand before recommending

Work the dimensions this codebase actually raises — the problem domain, the repository
survey, language and ecosystem conventions, correctness, architecture, readability,
efficiency, tests, dependencies. A dimension with nothing to report gets no section in the
output. **Do not invent requirements that the repository does not support.**

On ecosystem conventions specifically: judge the code by the conventions of its own language
and contemporary community, and name what is technically valid but culturally unusual enough
to raise maintenance cost. Name too the places where conventional wisdom should _not_ be
followed, because the domain or the repository has a legitimate reason to differ — that
judgment is the part no checklist makes for you.

**Start with what the repository already knows about itself.** `THEORY.md`, `.issues/`, an
existing `WALKTHROUGH.md`, ADRs and design notes are evidence, and prior passes by sibling
skills are the cheapest context available:

- If `THEORY.md` exists, read it first and treat it as a hypothesis, not a fact. Verify its
  central claims against the code. Where it is right, build on it instead of re-deriving the
  domain. Where it is wrong, that is a finding.
- If `.issues/` exists, read all of it. Known correctness bugs are input to the target
  design — a module you are proposing to delete makes its open bugs moot, and that is worth
  saying.

Only where neither exists do the domain and repository survey yourself, and do them as input
to the target design rather than as a deliverable. This skill does not write `THEORY.md`.

Trace several representative operations end to end. Pay particular attention to boundaries
between components — many important design problems occur at boundaries rather than inside
individual functions.

## Phase two — judge

Identify what the codebase does well before considering major changes. **Preserve good
decisions unless there is a concrete reason to replace them.**

Distinguish demonstrated defects from plausible risks.

### Refactoring philosophy

The desired outcome is not a theoretically perfect architecture. It is a smaller, clearer,
more correct, more idiomatic system whose structure reflects the actual problem.

Favor refactorings that reduce concepts, reduce indirection, clarify ownership, make
invariants explicit, make state transitions easier to understand, improve locality, expose
important behavior through clearer APIs, remove duplication of knowledge, separate genuinely
independent concerns, consolidate things that should never have been separated, make tests
easier to write at meaningful boundaries, and reduce the number of ways the same task can be
accomplished.

**Be suspicious of refactorings that merely move complexity around.**

## Phase three — write it up

Two artifacts, and the split is the thing most easily gotten wrong: **a finding is a defect
at a location; the design is what the system should become.**

Both live under `.issues/`: the findings as their own files, everything else as the overview
at `.issues/000-refactor.md`. Nothing goes to the repository root. A refactoring plan is
working state that expires the moment it is executed — it does not belong beside the
standing documents (`README.md`, `CLAUDE.md`, `THEORY.md`, `WALKTHROUGH.md`), which answer
questions that stay answered.

### Findings → `.issues/`

Follow [issues-protocol.md](../code-audit/references/issues-protocol.md), the canonical copy
shared across the `code-*` review skills, for the file layout, finding
format, dedup checks against `.issues/` and GitHub, and re-run rules. File each with
`**Source:** code-refactor`.

A finding is a specific problem at a specific location — a correctness risk, a cohesion or
coupling failure, an abstraction that leaks, a dependency that does not earn its cost.
Severity uses the protocol's four levels and their meanings; there is no second scale here.

The protocol's `## Description` and `## Suggested fix` already ask for what you observed,
where it appears, why it matters, and the change you propose. A refactor finding adds three
things to them:

1. Which kind of issue it is — correctness, design, maintainability, performance,
   ecosystem-convention, or operational, or some combination
2. The cost, risk, or trade-off of making the change
3. Your confidence in the recommendation

Use specific files, packages/modules, types, functions, and execution paths as evidence.
Avoid generic advice that could apply to any repository.

**Do not inflate severity.** A long list of minor style observations should not obscure a
small number of consequential design problems.

### The overview → `.issues/000-refactor.md`

Regenerated in place on each pass, per the protocol. Cover, in this order:

**The system as you understand it.** Concise, in terms of the problem it solves rather than
the technologies it uses. Then the current architecture, explained against that problem.

**What the codebase does well.** Before the changes. Specific, not courtesy.

**The target design.** Not a list of local fixes — what the codebase should look like after
refactoring: the proposed conceptual model, major packages/modules/components, ownership of
important state, principal interfaces and boundaries, dependency direction, major data

From philoserf/claude-code-config, MIT.

More from philoserf/claude-code-config