Deep Refactoring
Developmentdeep-refactoringDeep 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.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/nevalang/neva/blob/HEAD/.codex/skills/deep-refactoring/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/deep-refactoring, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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.