static-var/Keystone / skills/refactoring
refactoring
UnverifiedProgram 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-reviewwhen review is needed.
Process
- 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.
- For large refactors, write a refactor doc under
docs/keystone/refactors/YYYY-MM-DD-<slug>.mdbefore editing.- Include goal, invariants, smells, affected areas, slices, proof, rollback, and review focus.
- Completion criterion: doc is specific enough for
task-creationorimplementation.
- Pass isolation before mutation.
- Load/check
../_shared/gates/isolation.md. - Respect unrelated dirty files and protected scope.
- Completion criterion: mutation scope is safe.
- Load/check
- 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.
- 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.
- Use engineering standards.
- Load
../_shared/engineering-standards.mdfor architecture or ownership decisions. - Remove abstractions that lack current pressure.
- Completion criterion: the result has clearer ownership, state, naming, or boundaries.
- Load
- Verify.
- Load and pass
../_shared/gates/proof.mdfor the preserved invariant. - Completion criterion: behavior invariant is supported by observed evidence.
- Load and pass
- Checkpoint and hand off.
- Use
../_shared/gates/checkpoint.md. - Hand off to
change-reviewfor non-trivial refactors or leave an explicit review pointer.
- Use
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 467k | Updated | Claude CodeCodex | Verified | Install |
| 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: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |