dev-refactor-plan

name	dev-refactor-plan
description	Use when the user asks for a behavior-preserving refactor plan before implementation. Do not trigger when the user already requested a clear, scoped refactor to be implemented directly.
metadata	{"version":"0.5","updated":"2026-07-26"}

Refactor plan workflow

Use this workflow when the task is to refactor code while preserving behavior.

Steps

1. State the refactor goal.

   • What should improve?
   • What behavior must remain unchanged?

2. Map current structure.

   • Relevant files and modules
   • Entry points and call paths
   • Tests and validation commands
   • Dependency cycles and change fan-out
   • Shared mutable state and deployment coupling
   • Git co-change history when it can reveal candidate seams; treat it as supporting evidence, not an automatic reason to merge modules

3. Identify contracts.

   • Public APIs
   • CLI behavior
   • Database schema
   • External integrations
   • User-visible behavior
   • If the behavior contract or trade-off set is still contested, recommend $codex-next:core-grilling and stop. Wait for the user to invoke it explicitly; do not imitate or begin that workflow here.

4. Propose an incremental plan.

   • Step 1
   • Step 2
   • Step 3
   • Validation after each step

5. Define rollback and stop conditions.

Output

Return:

1. Current structure
2. Behavior contracts
3. Proposed plan
4. Validation strategy
5. Risks and stop conditions

Do not

• Do not edit files before the plan is clear.
• Do not combine unrelated refactors.
• Do not change public behavior unless explicitly requested.