{"id":16456,"plugin_id":"plugins_6a512fae91f881918208460aae465ff9","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:13:26.231Z","digest":"3577f1d72547343067fb05dfcacdc63dbd32726fa52dd113b8ee53b7f1a708ae","against":null,"payload":{"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.","included_files":[],"name":"refactoring","skill_md_contents":"---\nname: refactoring\ndescription: 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.\n---\n\n# Refactoring\n\n## Core principle\n\nRefactoring changes structure while preserving behavior. Improve design in small, reversible steps, with characterization or regression proof when behavior could drift.\n\n## Load when\n\nLoad 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.\n\nIf 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.\n\nAt 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.\n\n## Outcome contract\n\nA complete refactor reports:\n\n- the behavior invariant that must not change;\n- smells or pressures addressed;\n- isolation checked before mutation via `../../references/gates/isolation.md`;\n- characterization/regression proof used before risky edits;\n- files changed and why each changed;\n- verification commands/results or explicit proof gaps;\n- checkpoint handoff to `change-review` when review is needed.\n\n## Process\n\n1. Classify size and risk.\n   - Small/local: one area, clear invariant, existing proof likely enough.\n   - Large/cross-cutting: multiple boundaries, weak coverage, shared contracts, or context-window risk.\n   - Completion criterion: refactor path is either safe for direct mutation or documented first.\n2. For large refactors, write a refactor doc under `docs/keystone/refactors/YYYY-MM-DD-<slug>.md` before editing.\n   - Include goal, invariants, smells, affected areas, slices, proof, rollback, and review focus.\n   - Completion criterion: doc is specific enough for `task-creation` or `implementation`.\n3. Pass isolation before mutation.\n   - Load/check `../../references/gates/isolation.md`.\n   - Respect unrelated dirty files and protected scope.\n   - Completion criterion: mutation scope is safe.\n4. Establish behavior proof.\n   - Prefer existing behavior tests; add characterization coverage when the invariant lacks a tripwire.\n   - Completion criterion: there is a tripwire for accidental behavior change or a documented proof gap.\n5. Apply small refactorings.\n   - Prefer rename, extract, inline, move, split, consolidate, simplify conditionals, remove dead code, and clarify ownership.\n   - Keep public contracts stable unless explicitly approved.\n   - Completion criterion: each step is understandable and reversible.\n6. Use engineering standards.\n   - Load `../../references/engineering-standards.md` for architecture or ownership decisions.\n   - Remove abstractions that lack current pressure.\n   - Completion criterion: the result has clearer ownership, state, naming, or boundaries.\n7. Verify.\n   - Load and pass `../../references/gates/proof.md` for the preserved invariant.\n   - Completion criterion: behavior invariant is supported by observed evidence.\n8. Checkpoint and hand off.\n   - Use `../../references/gates/checkpoint.md`.\n   - Hand off to `change-review` for non-trivial refactors or leave an explicit review pointer.\n\n## Smell prompts\n\nInvestigate 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.\n\n## Hard rules\n\n- Preserve behavior unless the user explicitly approves a behavior change.\n- Do not disguise feature work as refactoring.\n- Do not perform broad refactors without a refactor doc.\n- Do not trust “looks equivalent” without proof or an explicit proof gap.\n- Do not introduce patterns for imagined futures.\n\n## Output format\n\n```markdown\n## Refactor report\nInvariant: ...\nSize/risk: small / large\nSmells addressed: ...\nFiles changed: ...\nVerification: ...\nRisks/gaps: ...\n\n### Checkpoint\nCurrent skill: refactoring\nCompleted gates: ...\nNext required skill: change-review / implementation / none\nNext check: ...\nAction: continue now / ask user / pending pointer / stop\n```\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}