Skip to content

static-var/Keystone / skills/refactoring

refactoring

Unverified

Program source-code refactoring for an explicit structural code improvement to structure, ownership, types, or duplication that preserves identified executable behavior. Select only when the request requires a structural code change with project-specific invariant proof, or enters through a canonical handoff from another Keystone skill.

Refactoring

Core principle

Refactoring changes structure while preserving behavior. Improve design in small, reversible steps, with characterization or regression proof when behavior could drift.

Load when

Load for an existing software project when the user asks to improve code structure while preserving an identified behavior contract: extract or inline code, reduce duplication, clarify names or type boundaries, remove code smells, or reorganize ownership.

If the user wants behavior change, use implementation. If a failure cause is unknown, use root-cause-analysis. If the refactor is broad or risky, create a refactor doc before mutation.

At entry, use the full Keystone path when the work changes integrated project code and needs project-specific invariant proof. Handle isolated text cleanup, mechanical formatting, and standalone snippets directly. Explicit invocation selects the full Refactoring behavior.

Outcome contract

A complete refactor reports:

  • the behavior invariant that must not change;
  • smells or pressures addressed;
  • isolation checked before mutation via ../_shared/gates/isolation.md;
  • characterization/regression proof used before risky edits;
  • files changed and why each changed;
  • verification commands/results or explicit proof gaps;
  • checkpoint handoff to change-review when review is needed.

Process

  1. Classify size and risk.
    • Small/local: one area, clear invariant, existing proof likely enough.
    • Large/cross-cutting: multiple boundaries, weak coverage, shared contracts, or context-window risk.
    • Completion criterion: refactor path is either safe for direct mutation or documented first.
  2. For large refactors, write a refactor doc under docs/keystone/refactors/YYYY-MM-DD-<slug>.md before editing.
    • Include goal, invariants, smells, affected areas, slices, proof, rollback, and review focus.
    • Completion criterion: doc is specific enough for task-creation or implementation.
  3. Pass isolation before mutation.
    • Load/check ../_shared/gates/isolation.md.
    • Respect unrelated dirty files and protected scope.
    • Completion criterion: mutation scope is safe.
  4. Establish behavior proof.
    • Prefer existing behavior tests; add characterization coverage when the invariant lacks a tripwire.
    • Completion criterion: there is a tripwire for accidental behavior change or a documented proof gap.
  5. Apply small refactorings.
    • Prefer rename, extract, inline, move, split, consolidate, simplify conditionals, remove dead code, and clarify ownership.
    • Keep public contracts stable unless explicitly approved.
    • Completion criterion: each step is understandable and reversible.
  6. Use engineering standards.
    • Load ../_shared/engineering-standards.md for architecture or ownership decisions.
    • Remove abstractions that lack current pressure.
    • Completion criterion: the result has clearer ownership, state, naming, or boundaries.
  7. Verify.
    • Load and pass ../_shared/gates/proof.md for the preserved invariant.
    • Completion criterion: behavior invariant is supported by observed evidence.
  8. Checkpoint and hand off.
    • Use ../_shared/gates/checkpoint.md.
    • Hand off to change-review for non-trivial refactors or leave an explicit review pointer.

Smell prompts

Investigate duplication, long functions, god objects, feature envy, primitive obsession, data clumps, shotgun surgery, divergent change, hidden control flow, speculative generality, vague managers/helpers, mixed abstraction levels, duplicated state, and unclear ownership.

Hard rules

  • Preserve behavior unless the user explicitly approves a behavior change.
  • Do not disguise feature work as refactoring.
  • Do not perform broad refactors without a refactor doc.
  • Do not trust “looks equivalent” without proof or an explicit proof gap.
  • Do not introduce patterns for imagined futures.

Output format

## Refactor report
Invariant: ...
Size/risk: small / large
Smells addressed: ...
Files changed: ...
Verification: ...
Risks/gaps: ...

### Checkpoint
Current skill: refactoring
Completed gates: ...
Next required skill: change-review / implementation / none
Next check: ...
Action: continue now / ask user / pending pointer / stop
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 319kUpdated Claude CodeCodexVerifiedInstall