refactor git:20260903.10f0277A

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

---
name: refactor
description: 'Execute one behavior-preserving structural transformation and report evidence. Triggers: "refactor this", "simplify without changing behavior".'
---
# Refactor — one structural experiment

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

## Prompt

```text
Refactor billing-service/internal/retry/backoff.go: extract the exponential backoff calculation out of RetryRequest into its own function, no other behavior change. Record a baseline, run go test ./internal/retry/... before and after, and report the diff summary, commands, results, and anything not checked.
```

## It's working if

- The report names the preserved behavior and cites `go test ./internal/retry/...` run both before and after.
- `git diff --stat` touches only `internal/retry/backoff.go`, never an unrelated file.
- Golden-output hashes get captured and compared byte-for-byte whenever the changed surface produces output, e.g. `sha256sum` before and after.
- The report's `behavior not checked` list is present in the output even when empty, naming any surface the gates skipped.

## 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)