18  Spell of Safe Refactoring

19 Spell of Safe Refactoring

Working seal: spell://safe-refactoring/517A86095D

Use when: Use when code quality must improve while public behavior stays fixed.

19.1 Copyable Template

Raw template: prompts/spells/safe-refactoring.txt

ROLE:
Act as a senior Python engineer performing behavior-preserving refactoring.

OBJECTIVE:
Refactor the supplied module to reduce duplication and improve readability without changing public behavior.

CONTEXT:
Python 3.12. The module runs inside a web API process and is called on every request. Existing tests are incomplete.

The function signatures are part of a stable public API.

CONSTRAINTS:
Do not add third-party dependencies. Do not change public function names, parameter order, or return schema.

Preserve current logging side effects unless they are obviously duplicated. Keep the patch bounded to the supplied file unless a test file is requested.

PROCEDURE:
First identify the invariants that must remain true. Then list duplication or code-smell candidates.

Propose the minimal refactor that removes the duplication. Explain tradeoffs briefly before showing code.

OUTPUT CONTRACT:
Return:

1\. a short summary,

2\. the invariants,

3\. a unified diff,

4\. the revised code,

5\. a targeted test plan.

VERIFICATION:
Include edge cases for empty input, malformed input, Unicode content, and large input size.

State why the refactor preserves behavior.

FAILURE BEHAVIOR:
If behavior cannot be inferred from the provided code, say exactly what is ambiguous and proceed with the safest minimal change.

19.2 Related Runes

• 1172 invariant - A law that must remain true while the rest of the system is allowed to move. If you cannot say the invariant, you probably do not yet understand the change.
• 1088 diff {Forge} - A visible account of what changed between one state and another. Good diffs make review local; bad diffs turn truth into fog.
• 1152 contract test - A promise checked at the seam between systems. Use it when mocks are too flattering and end-to-end tests are too blunt.
• 1445 deterministic - Given the same inputs, the same result should return. This is the antidote to drift, heisenbugs, and unreviewable behavior.
• 1430 backward-compatible - New versions do not casually break old clients or data.

19.3 Related Pages

• Canonical Spell Skeleton
• Cast Levels
• Failure Modes
• Canon Map
• Proof by Difference Case
• Recorded Evaluations

19.4 Source Form

19.5 Spell of Safe Refactoring

ROLE:

Act as a senior Python engineer performing behavior-preserving refactoring.

OBJECTIVE:

Refactor the supplied module to reduce duplication and improve readability without changing public behavior.

CONTEXT:

Python 3.12. The module runs inside a web API process and is called on every request. Existing tests are incomplete.

The function signatures are part of a stable public API.

CONSTRAINTS:

Do not add third-party dependencies. Do not change public function names, parameter order, or return schema.

Preserve current logging side effects unless they are obviously duplicated. Keep the patch bounded to the supplied file unless a test file is requested.

PROCEDURE:

First identify the invariants that must remain true. Then list duplication or code-smell candidates.

Propose the minimal refactor that removes the duplication. Explain tradeoffs briefly before showing code.

OUTPUT CONTRACT:

Return:

1. a short summary,

2. the invariants,

3. a unified diff,

4. the revised code,

5. a targeted test plan.

VERIFICATION:

Include edge cases for empty input, malformed input, Unicode content, and large input size.

State why the refactor preserves behavior.

FAILURE BEHAVIOR:

If behavior cannot be inferred from the provided code, say exactly what is ambiguous and proceed with the safest minimal change.