# Deep Refactoring

> Deep Refactoring is an Agent Skill for development published in the nevalang/neva repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

A systematic approach to refactoring complex codebases.

- Skill name: `deep-refactoring`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/nevalang/neva/blob/HEAD/.codex/skills/deep-refactoring/SKILL.md
- Repository: nevalang/neva (1,074 GitHub stars when collected)

## SKILL.md

# Deep Refactoring Skill

Use this skill when a component has become too complex to understand or modify safely, or when architectural flaws (e.g. duplicated logic) are identified.

## 1. Phase 1: Knowledge Mapping

The goal is to move from "mystery code" to "well-defined intent".

- **Plain English Specification**: Write a document describing what the function/component is _supposed_ to do in strictly plain English. Do not look at the code yet; use the current problem statement and requirements.
- **Dependency Visualization**: Use Mermaid flowcharts to map out how functions call each other. Identify:
  - Indirect recursion loops.
  - Points of high coupling.
  - Redundant entry points.
- **Data Flow Analysis**: Trace how data (especially complex objects) transforms through the system.

## 2. Phase 2: Decoupling

The goal is to separate _what_ is being done from _how_ and _where_.

- **Extract Pure Logic**: Identify "dirty" functions that do multiple things. Extract the pure logic into standalone, side-effect-free functions, when makes sense.
- **Unify Entry Points**: Ensure there is a single source of truth for specific operations, unless clearly needed.

## 3. Phase 3: Tuning & Validation

The goal is to polish, optimize, and ensure correctness.

- **Complexity Reduction**: Target non-optimal code paths.
- **Readability Pass**: Use the "plain English" descriptions from Phase 1 to rename variables and update comments so they match the intent.
- **Verification**:
  - Run existing tests.
  - Add/Remove/Change tests when/if needed and/or contributes to code quality.

---

Source: https://www.openparable.com/skill/development/deep-refactoring (OpenParable). Cite the canonical URL above.
