refactor git:20260825.2207c5bA

Immutable. This exact content is served forever at /api/v1/blob/30c934734b38eb95.

---
name: refactor
description: 'Execute one behavior-preserving structural transformation and report evidence. Triggers: "refactor this", "simplify without changing behavior".'
practices:
- refactoring
- legacy-code-seams
- design-patterns
hexagonal_role: supporting
consumes:
- repo-context
produces:
- code-changes
context_rel: []
skill_api_version: 1
context:
  window: fork
  intent:
    mode: task
  sections:
    exclude:
    - HISTORY
metadata:
  capabilities: [refactor]
  effects: [modify_source_files]
  canonical_status: canonical
  disposition: keep_specialist
  tier: execution
  dependencies: []
output_contract: code changes with regression evidence
---
# Refactor — one structural experiment

Refactor changes structure while preserving observable behavior. It performs one
caller-selected transformation and reports the result.

## Procedure

1. Name the preserved behavior and the focused acceptance surface.
2. Record an honest baseline, including any reproducible ambient failures.
3. Apply one bounded transformation: extract, rename, inline, simplify,
   encapsulate, move, or delete dead code.
4. Run the focused check and the smallest package-level regression check justified
   by the changed surface.
5. Return the diff summary, commands, results, and behavior not checked.

Do not combine a newly discovered behavior fix with the structural change. A red
result is evidence for the caller; this skill does not revert, narrow, retry,
commit, validate, or route subsequent work automatically.

## Seam experiments before commitment

When the transformation needs a seam — an extraction boundary, interface, or
module split — and more than one candidate seam exists, probe before you cut.
Run the probe in disposable isolation (a scratch branch, worktree, or copied
tree the caller's policy allows): rough in the seam, see what it forces —
signature churn, import cycles, test rewrites — then discard the probe and
keep only the knowledge. Stop condition: at most two probes; if the second
candidate seam also fights back, report both findings to the caller instead of
trying a third. Cutting the first imaginable seam directly into the working
tree is the **premature seam** failure mode: the wrong boundary calcifies
because reverting it now costs more than living with it.

## Neutrality gates

"Behavior-preserving" is a claim to execute, not assert. Gate the
transformation on behavior-identical proof:

- The focused check and the package-level regression check pass both before
  and after, with the same set of pre-existing failures — no new red, and no
  quietly vanished red either (a test that stops running is a behavior change).
- For output-producing surfaces (generators, serializers, formatters, reports),
  hash the outputs: capture golden-output hashes over identical inputs before
  the change and compare byte-for-byte after. A hash mismatch is a behavior
  diff to surface and explain, never to shrug at; the caller decides whether to
  keep, narrow, or reverse the change.
- Observable error messages, exit codes, and public signatures on the changed
  surface are part of behavior unless the caller excluded them.

A neutrality gate that was skipped or narrowed after the fact is the
**post-hoc neutrality** failure mode — the diff decides what got tested. Name
any surface the gates did not cover in the report's behavior-not-checked list.

## References

- [Behavior-preserving simplification](references/behavior-preserving-simplification.md)
- [Behavior scenarios](references/refactor.feature)