Safe Refactor Planner

The Prompt

You are a principal {{language}} engineer planning a safe refactor. I need a low-risk, staged plan that protects production behavior and works for a {{workflow_surface}} delivery flow.

Current code:
{{current_code}}

Refactor goal:
{{refactor_goal}}

Constraints:
{{constraints}}

Performance budget:
{{performance_budget}}

Validation commands:
{{validation_commands}}

Return exactly:
1) Current architecture assessment (coupling, complexity, hotspots)
2) Refactor strategy (phases with entry/exit criteria per phase)
3) Surface-specific handoff plan
   - what a CLI agent can do safely
   - what an IDE agent can do safely
   - what should stay in a planning/review app or remain human-only
   - where a second-pass reviewer model should be used
4) Guardrail tests to add before changes
5) Commit and checkpoint plan (small reversible slices with stop points)
6) Risk map (top risks, blast radius, mitigation)
7) Rollback strategy for each phase
8) Performance validation plan against budget
9) Definition of done

Constraints:
- Preserve external behavior unless explicitly noted.
- Prefer small, reversible commits over large rewrites.
- Separate read-first investigation from write steps.
- Call out dependencies that must be upgraded first.
- Treat schema changes, dependency changes, and destructive commands as approval-required by default.
- Explicitly separate "must do now" vs "defer later."

When to Use

Use this when code quality needs improvement but stability is non-negotiable. It is ideal for legacy modules, high-traffic services, and areas where a coding agent could move quickly enough to create regressions unless the work is staged carefully first.

Common scenarios:

• Breaking apart a large, multi-responsibility file
• Replacing brittle abstractions with clearer boundaries
• Preparing code for new features without adding more debt
• Improving testability before expanding functionality

This prompt emphasizes planning discipline. Instead of jumping straight into edits, it gives you a phased roadmap, explicit verification commands, and a clearer handoff between terminal agents, IDE agents, planning surfaces, and reviewer passes.

Variables

Variable	Description	Good input examples
language	Main implementation language	TypeScript, Java, C#, Go
current_code	Existing code or representative slice	Current class/module, plus key dependencies
refactor_goal	Desired improvement outcome	”Split service into domain + infrastructure layers”
constraints	Non-negotiables and limits	”No API contract changes, 2-week window, no DB migration”
performance_budget	Latency/throughput/error constraints	”p95 <= 180ms, memory +5% max”
workflow_surface	Where implementation will actually happen	"CLI agent with local tests", "IDE agent in VS Code", "chat/app planning first, coding later"
validation_commands	Checks that must pass after each phase	bun run build, pytest services/billing -q, pnpm test --filter api

Tips & Variations

• If you are using a planning app first, ask for a one-page handoff brief and then move only phase 1 into a CLI or IDE agent.
• Add a do-not-touch list when the repo has sensitive files or generated assets.
• For risky modules, ask for a parallel-run or feature-flag cutover plan before any rewrite work starts.
• If deadlines are tight, request a two-track plan: minimum safe cleanup now, deeper refactor later.
• Pair this with the test-generation prompt to draft guardrail tests before the first implementation slice.
• If one tool will implement and another will review, ask for a dedicated reviewer checklist per phase so the review standard stays stable across commits.

Refactors fail when scope expands mid-flight. Keep this prompt anchored to concrete goals and explicit out-of-scope items.

Example Output

Phase 1: Add characterization tests around pricing rules and invoice formatting.

CLI handoff: Read billing-service.ts, pricing.ts, and existing Vitest patterns first. Do not edit migrations or shared config in phase 1.

Top risk: Hidden side effects in shared utility used by billing and reporting.

Mitigation: Introduce adapter layer, dual-run old/new path behind a feature flag.

Rollback: Toggle flag off, revert only phase-2 commits, preserve phase-1 tests.