# Safe Refactoring Rules

> Ensures all refactoring is deterministic, behavior-preserving, and non-breaking

- Skill: `bottelet/safe-refactoring-rules` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bottelet/safe-refactoring-rules`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bottelet/safe-refactoring-rules/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bottelet (https://skillmd.com/u/bottelet)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bottelet/safe-refactoring-rules

---


# Safe Refactoring Rules

## Purpose

Ensure all refactoring is deterministic, non-breaking, and behavior-preserving.

This skill enforces *how changes are made*, not *how the system is structured*.

---

# 1. Behavior Preservation

- Never change runtime behavior unless explicitly instructed.
- Any refactoring must preserve observable outputs.
- Moving code between layers must not alter execution results.

---

# 2. Existing Code Respect

- Never overwrite an existing method if it already satisfies part of the requirement.
- Extend existing implementations instead of replacing them.
- Do not delete or rewrite working logic unless required for a fix.

---

# 3. Dependency Integrity

- Always preserve constructor injection.
- Never replace dependency injection with service locators (`app()`, `resolve()`).
- Do not introduce new dependencies when existing ones suffice.
- Do not change dependency graphs without explicit intent.

---

# 4. Public API Stability

- Never change public method signatures unless all call sites are updated in the same change.
- Avoid breaking changes at all costs.
- Prefer internal adaptation over external contract modification.

---

# 5. Idempotency Requirement

- Refactoring must be idempotent.
- Running the same change twice must produce no further diff.
- No duplicate logic, imports, traits, or methods may be introduced.

---

# 6. Uncertainty Handling

If any of the following is unclear:

- intended behavior
- service contract
- domain rule
- expected output

Then:

- Stop immediately
- Do not guess
- Report ambiguity explicitly
- Request clarification

---

# 7. Abstraction Reuse Rule (Local Scope Only)

This skill only enforces reuse during refactoring operations.

Global abstraction policy is defined in application-architecture-standard.

Before introducing:

- Trait
- Service
- DTO
- Transformer
- Base class

Search for an existing implementation.

Reuse existing abstractions whenever practical.

Duplicate abstractions are architectural defects.

---

# 8. Scope Discipline

This skill does NOT define:

- architecture layering (handled by application-architecture-standard)
- testing strategy (handled by data-layer-contracts / filament-resource-testing)
- security rules (handled separately if present)

It ONLY defines safe transformation rules.

---

# 9. Enforcement Priority

If this skill conflicts with others:

1. application-architecture-standard
2. domain-specific skills
3. execution workflows
4. this skill (always subordinate to architecture)