refactor

Files (3)

• HTML-REPORT.md
• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Refactor

Explore existing code for structural changes that remove obligations from
callers. No feature or diff is needed.

## 1. Scope

Read the repository's instructions and the requested scope or concern: a
path, subsystem, goal such as making invalid checkout states
unrepresentable, or a ticket and its map from `research-codebase`. With a
ticket, inspect the code its change touches; a candidate's cost is what that
change would otherwise have to work around. With no target, map the
repository's major subsystems and choose promising areas to inspect.

## 2. Discover

Use a single agent by default. Apply these related questions in one pass;
they overlap and are not separate work queues. Split a large scope only
along genuinely independent subsystems.

- **Representation:** which units, identities, states, or operations rely
  on primitives, flags, naming, or caller discipline?
- **Derivability:** which stored or passed values could be derived from
  authoritative state instead of kept in sync?
- **Invariant ownership:** which rules do callers repeatedly enforce that
  one owning module or storage constraint could guarantee?
- **Lifecycle ownership:** which acquire/release or transaction protocols
  could a scoped operation own instead of each caller?
- **Least capability:** which callers receive authority they do not need?
- **Altitude:** which special cases compensate for limitations in the
  underlying mechanism? Where should the rule live?
- **Deep modules:** which repeated orchestration could sit behind an
  interface that hides knowledge callers currently need?

## 3. Substantiate

Read each promising implementation and its callers in full, with the tests
and contracts needed to judge the change. Trace the burden or possible
misuse to concrete code. A candidate needs a present cost or credible
failure mode; an observed bug is not required.

Describe the replacement and check which guarantees it actually enforces,
and which still need validation or tests. Distinguish tighter internal
representations from changes to accepted external behavior. Preserve
required boundary validation.

Merge candidates that address the same underlying mechanism.

## 4. Present and wait

Rank candidates by concrete benefit and migration risk. With a ticket, rank
first a candidate that removes the ticket's need at its cause, making the
ticket's change unnecessary. For each, give:

- Locations and evidence of the current burden or possible misuse.
- The proposed representation or owning module, and what callers stop doing.
- Expected size (small/medium/large), justified by the affected modules,
  callers, and migration work. State any uncertainty.
- Guarantees gained, affected contracts, migration risks, and verification
  needed.

State what you explored and what remains unread. Return no candidates when
none meet the evidence bar.

Render the candidates as an HTML report following
[HTML-REPORT.md](HTML-REPORT.md), and reply with its path and the ranked
candidate titles, one line each.

Wait for the user to select a candidate and approve any changes to accepted
behavior before editing.

## 5. Implement

Use the `develop` skill for the chosen change. Pass the selected candidate's
evidence, scope, accepted contracts, and risks as its requirements.
With a ticket, finish the refactor before the ticket's change, so each
lands as its own diff. When the refactor removes the ticket's need, verify
the need is met and drop the ticket's change.

From lithammer/ai, MIT.

More from lithammer/ai