strategy-no-untested-refactor
Skill4 starsChanged 4 months agoMITView on GitHub
Never refactor code that lacks tests without first adding characterization tests; run the tests before and after so the refactor keeps behavior identical. Use when the user asks for a behavior-preserving refactor and expects the tests to prove the behavior did not change; the user wants to restructure or clean up existing behavior and needs characterization tests to lock in current behavior first; the user asks to refactor a class, service, or function that currently has no automated tests covering its behavior. Keywords: strategy, untested, refactor, refactoring, characterization, tests, test-first, behavior-preserving, safety-net, regression.
In this repository119 other files it gives its agents.
- strategy-bitrix-d7-incrementalSkill
- strategy-explicit-over-magicSkill
- strategy-framework-conventionsSkill
- strategy-legacy-safe-editsSkill
- strategy-minimal-diffSkill
- strategy-preserve-public-apiSkill
- strategy-readonly-immutabilitySkill
- strategy-security-firstSkill
- strategy-test-drivenSkill
- openapiSkill
- paginationSkill
- rest-designSkill
- versioningSkill
- cqrsSkill
- dependency-inversionSkill
- hexagonalSkill
- repository-patternSkill
- service-layerSkill
- bitrixSkill
- findings-reportSkill
- laravelSkill
- performanceSkill
- phpSkill
- project-analysisSkill
- refactoringSkill
- roi-prioritizationSkill
- securitySkill
- stack-detectionSkill
- cache-layersSkill
- component-engineSkill
- d7-eventsSkill
- d7-loaderSkill
- d7-orm-queriesSkill
- iblock-elementsSkill
- kernel-main-moduleSkill
- localizationSkill
- controllersSkill
- ormSkill
- validationSkill
- controllersSkill
- query-builderSkill
- routingSkill
- autoload-psr4Skill
- dependency-managementSkill
- scriptsSkill
- connection-poolingSkill
- mysql-indexingSkill
- redisSkill
- transactionsSkill
- ci-github-actionsSkill
- deployment-strategiesSkill
- docker-phpSkill
- env-configSkill
- associationsSkill
- entities-mappingSkill
- orm-basicsSkill
- entity-apiSkill
- module-developmentSkill
- routing-controllersSkill
- formsSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 7 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 66
Do not treat the work as a behavior-preserving refactor when the user explicitly wants to change behavior or fix a bug.
- Distinctive: line 68
Do not add characterization tests first when the target code already has a reliable, passing test suite that covers the behavior being …
- Distinctive: line 87
Never refactor code that has no tests until you have added characterization tests that pin its current behavior.
- Distinctive: line 92
Prefer running the tests green before the refactor and confirming the same tests are still green after, using small verified steps.
- Distinctive: line 97
Avoid changing behavior, fixing bugs, or adding features in the same step as a refactor.
- Distinctive: line 107
Write tests that assert the current behavior of the target code and run them until they pass against the unchanged code.
- Distinctive: line 139
Not applicable — no I/O, auth, or untrusted input.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- generated: do not edit — source: knowledge/atoms/ai-rules/strategy-no-untested-refactor/ --><!-- schema: atomVersion=3 skillVersion=2 graphVersion=1 --><!-- compile: @php-skills/compiler v1.0.0 (deterministic build) -->Strategy — No Untested Refactor
When to use
- The user asks for a behavior-preserving refactor and expects the tests to prove the behavior did not change.
- The user wants to restructure or clean up existing behavior and needs characterization tests to lock in current behavior first.
- The user asks to refactor a class, service, or function that currently has no automated tests covering its behavior.
When NOT to use
- Do not treat the work as a behavior-preserving refactor when the user explicitly wants to change behavior or fix a bug; that is a feature or fix, not a refactor.
- Do not add characterization tests first when the target code already has a reliable, passing test suite that covers the behavior being refactored.
Core guidance
- Capture behavior as-is, including quirks — Write characterization tests against the behavior the code has now, including its quirks and bugs, not the behavior you wish it had.
- Run the tests before and after the refactor — Run the full relevant test suite green before starting, then run it again after the refactor and confirm the same tests still pass unchanged.
- Keep behavior changes out of the refactor — Do not fix bugs or change behavior in the same step as the refactor; land the behavior-preserving refactor first, then change behavior as a separate, tested step.
- Refactor in small, test-checked steps — Refactor in small steps and re-run the characterization tests after each step so a regression is caught immediately, not at the end.
- Add characterization tests before refactoring — If the code you are about to refactor has no covering tests, write characterization tests that pin its current behavior before you change anything.
Never
- Never refactor code that has no tests until you have added characterization tests that pin its current behavior.
Prefer
- Prefer running the tests green before the refactor and confirming the same tests are still green after, using small verified steps.
Avoid
- Avoid changing behavior, fixing bugs, or adding features in the same step as a refactor; keep the refactor strictly behavior-preserving.
Escalate to user when
- Escalate to the user when the code is too entangled to characterize with tests and ask whether to add a seam first or defer the refactor.
Quick recipe
- Write tests that assert the current behavior of the target code and run them until they pass against the unchanged code. (verify: The new characterization tests pass against the original, un-refactored code.)
- Make small behavior-preserving edits and re-run the same tests after each edit, stopping and reverting if any test changes. (verify: The identical characterization tests are still green after the refactor.)
Anti-patterns
| Anti-pattern | Why it fails | Do instead |
| Sneaking a behavior change into a refactor | It muddies the diff and makes it impossible to attribute a changed test to the<br>right edit. | Land the pure refactor first, then make the behavior change as its own tested<br>step. |
| One big-bang refactor with no checkpoints | If the final result differs from the original, there is no way to pinpoint which<br>of the many changes caused it. | Take small behavior-preserving steps and re-run the tests after each one. |
| Refactor first, add tests later | Post-hoc tests lock in the new behavior and can never prove the refactor<br>preserved the old behavior. | Write the characterization tests against the original code before touching it. |
See references/anti-patterns.md.
Common mistakes
- Refactoring blind with no way to detect drift — Restructuring untested code with no tests means a behavior change goes completely undetected until it reaches users. Fix: Add characterization tests first, then refactor against that safety net.
- Skipping the baseline test run — Refactoring without first running the suite green means you cannot tell whether a later failure came from the refactor or was already broken. Fix: Establish a green baseline first, then compare the post-refactor run against it.
- Characterization tests encode desired behavior — Writing the "should-be" behavior into characterization tests instead of the actual current behavior defeats their purpose. Fix: Assert exactly what the code does today, quirks included; fix the behavior later as a separate, intentional change.
Version notes
- Test-first refactoring is version-agnostic (PHP >=7.4) — Requiring characterization tests before a refactor is independent of PHP version; it applies from PHP 7.4 upward and to any test framework in use.
Security
- Not applicable — no I/O, auth, or untrusted input.
Testing
- Activation and decision behavior are verified in
eval/scenarios/ai-rules/strategy-no-untested-refactor.yaml.
Additional resources
- references/anti-patterns.md
- references/examples.md
- references/pitfalls.md
- references/recipes.md
- references/version-differences.md
Knowledge graph
Related: ai-rules/strategy-minimal-diff, ai-rules/strategy-test-driven
<!-- graph-fragment: graph/fragments/ai-rules/strategy-no-untested-refactor.yaml -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.