Safe refactoring
Change structure without losing behavior, protocol validity, or concurrent user edits.
Before mutation
- Establish the exact behavior to preserve and the intentional behavior change, if any.
- Locate callers, implementations, serialized forms, tests, configuration, and external protocol names.
- Check the working tree and treat unrelated modifications as user-owned.
- Define mechanical acceptance checks: compile, focused tests, type checks, contract tests, and diff inspection.
- Split the work into dependency-ordered increments when a single atomic patch would be hard to verify.
Mutation rules
- Use expected content hashes for existing files; a mismatch means reload and reconcile instead of overwriting.
- Prefer narrow edits and stable compatibility adapters while consumers migrate.
- Keep persisted schema and event changes versioned; tolerate additive fields where forward compatibility is intended.
- Preserve tool-call/result adjacency, event IDs, resource ownership, cancellation, and error semantics during agent-runtime refactors.
- Do not mix broad formatting or unrelated cleanup into the functional diff.
- If a generated artifact should change, update its source and regenerate it with the documented command.
Verification loop
- Inspect the resulting diff for accidental deletion, path drift, stale names, and expanded authority.
- Run the smallest fast check that catches syntax/type errors, then the focused behavior tests.
- Run broader integration checks when the changed boundary has multiple consumers.
- Treat warnings or skipped tests relevant to the change as evidence to explain, not automatic success.
- If verification fails, retain the diagnostic evidence, correct the implementation, and repeat.
Completion report
Report the behavioral outcome, compatibility decisions, important changed paths, and checks actually executed. Call out anything not verified. Do not describe a refactor as behavior-preserving without evidence.
1---2name: safe-refactoring3description: Execute behavior-preserving or intentionally scoped refactors safely. Use this for multi-file renames, component/service extraction, state-management changes, API migrations, concurrency refactors, or any request where unrelated user work and subtle contracts must be preserved.4---5
6# Safe refactoring
7
8Change structure without losing behavior, protocol validity, or concurrent user edits.
9
10## Before mutation
11
121. Establish the exact behavior to preserve and the intentional behavior change, if any.
132. Locate callers, implementations, serialized forms, tests, configuration, and external protocol names.
143. Check the working tree and treat unrelated modifications as user-owned.
154. Define mechanical acceptance checks: compile, focused tests, type checks, contract tests, and diff inspection.
165. Split the work into dependency-ordered increments when a single atomic patch would be hard to verify.
17
18## Mutation rules
19
20- Use expected content hashes for existing files; a mismatch means reload and reconcile instead of overwriting.
21- Prefer narrow edits and stable compatibility adapters while consumers migrate.
22- Keep persisted schema and event changes versioned; tolerate additive fields where forward compatibility is intended.
23- Preserve tool-call/result adjacency, event IDs, resource ownership, cancellation, and error semantics during agent-runtime refactors.
24- Do not mix broad formatting or unrelated cleanup into the functional diff.
25- If a generated artifact should change, update its source and regenerate it with the documented command.
26
27## Verification loop
28
291. Inspect the resulting diff for accidental deletion, path drift, stale names, and expanded authority.
302. Run the smallest fast check that catches syntax/type errors, then the focused behavior tests.
313. Run broader integration checks when the changed boundary has multiple consumers.
324. Treat warnings or skipped tests relevant to the change as evidence to explain, not automatic success.
335. If verification fails, retain the diagnostic evidence, correct the implementation, and repeat.
34
35## Completion report
36
37Report the behavioral outcome, compatibility decisions, important changed paths, and checks actually executed. Call out anything not verified. Do not describe a refactor as behavior-preserving without evidence.
gabrielmoreira