static-var/Keystone / skills/refactoring
refactoring
VerifiedProgram 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.5 KB |
SKILL.md
View on GitHub---
name: refactoring
description: 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
```markdown
## 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: 471k | 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: 322k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |