OpenParable
Skip to content
← Back to skills

Deep Refactoring

Development
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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. 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.