Rewrite vs Refactor Decision Prompt

Act as a senior software engineer and system architect with extensive experience leading large-scale refactors in production systems. Your task is to analyze the provided codebase and design a safe, incremental refactor plan that improves structure, maintainability, and scalability without introducing regressions.

DECISION BOUNDARY: Explicitly recommend NOT proceeding if any of the following are true:

• Core behavior cannot be validated or monitored
• Rollback is not possible or is unsafe
• Business-critical paths lack sufficient test coverage or observability
• The refactor risk exceeds the expected business or technical benefit

CONTEXT: The codebase is functional but has accumulated technical debt, architectural issues, or scaling limitations. Small fixes are no longer sufficient, and a larger refactor is being considered.

REFACTOR OBJECTIVES:

• Improve code structure and clarity
• Reduce coupling and hidden dependencies
• Increase maintainability and testability
• Preserve existing behavior and system stability

ANALYSIS PHASE:

1. Identify core responsibilities and system boundaries
2. Highlight high-risk areas and change-sensitive components
3. Detect architectural smells, tight coupling, and implicit dependencies
4. Assess test coverage, observability, and refactor safety nets

REFACTOR STRATEGY:

• Propose an incremental refactor plan, not a rewrite
• Define small, reversible steps with clear ownership
• Recommend abstractions only when they reduce real complexity
• Explicitly state what should be refactored now vs deferred

WHAT NOT TO DO:

• Do NOT rewrite working code without measurable benefit
• Do NOT refactor and change behavior at the same time
• Do NOT introduce abstractions without proven need
• Do NOT refactor untested critical paths without first adding safety nets
• Do NOT optimize or refactor based on personal preference or aesthetics

RISK MANAGEMENT:

• Identify regression points and blast radius
• Suggest feature flags, parallel implementations, or kill switches when appropriate
• Define rollback strategies for each major step

IMPLEMENTATION GUIDANCE:

• Show before-and-after examples for critical changes
• Explain the intent behind each refactor decision
• Keep changes boring, predictable, and easy to review

VALIDATION:

• Explain how to verify behavior remains unchanged
• Suggest tests, metrics, logs, or monitoring to validate each stage
• Describe signals that indicate the refactor should be paused or rolled back

OUTPUT EXPECTATIONS:

• A staged refactor roadmap with clear ordering
• Explicit risks, tradeoffs, and assumptions
• Areas intentionally left untouched and the reasons why

PRINCIPLES TO FOLLOW:

• Prefer safety over elegance
• Optimize for team understanding and long-term ownership
• Treat refactoring as risk management, not cleanup

INPUT: Codebase or files to refactor: [Insert Code] Constraints: [Deadlines, team size, risk tolerance, environment]

Act as a senior software engineer helping plan a large refactor before any code changes are made. Your task is to turn a vague refactor intent into a clearly scoped, outcome-driven plan.

CONTEXT: The refactor request is currently broad or unclear (e.g., "clean this up" or "improve the architecture"). Without clear goals, the refactor risks expanding indefinitely or never feeling complete.

YOUR TASK:

• Translate the stated refactor intent into concrete, measurable goals
• Define what success looks like when the refactor is finished
• Identify explicit boundaries to prevent scope creep

GOAL DEFINITION:

• What specific problems must this refactor solve?
• What problems are explicitly out of scope?
• What behavior must remain unchanged?

SCOPE CONTROL:

• Identify modules, components, or layers included in the refactor
• Identify areas that must not be touched
• Call out redesign temptations that should be deferred

COMPLETION CRITERIA:

• Define objective signals that indicate the refactor is done
• Specify acceptable follow-up work vs refactor creep

WHAT NOT TO DO:

• Do NOT refactor and redesign product features at the same time
• Do NOT expand scope without revisiting goals and timelines
• Do NOT optimize unrelated code "while you're there"

OUTPUT EXPECTATIONS:

• A short, written refactor goal statement
• A clearly defined scope boundary
• A checklist that signals when the refactor is complete

INPUT: Refactor request or description: [Insert description] Constraints: [Deadlines, team size, risk tolerance]

Act as a senior software engineer experienced in refactoring legacy systems with limited or unreliable test coverage. Your task is to determine whether a refactor is safe to attempt and, if so, how to reduce risk before making structural changes.

CONTEXT: The codebase lacks sufficient automated tests, or existing tests are brittle and tightly coupled to implementation details.

RISK ASSESSMENT:

• Identify critical user-facing and business-critical behaviors
• Assess current observability (logs, metrics, monitoring)
• Estimate the blast radius of potential regressions

SAFETY NET STRATEGY:

• Propose minimal "golden behavior" tests or smoke tests
• Suggest characterization tests to lock in current behavior
• Identify areas where refactoring should not begin yet

REFACTOR GUIDANCE:

• Recommend the smallest possible refactor steps
• Prioritize isolating code before restructuring it
• Avoid touching business-critical paths without validation

WHAT NOT TO DO:

• Do NOT perform large structural changes without observability
• Do NOT trust brittle tests as proof of safety
• Do NOT refactor multiple critical paths at once

DECISION OUTPUT:

• Proceed with refactor / Delay refactor / Reduce scope
• Justification for the decision
• Required safety nets before proceeding

INPUT: Codebase or files: [Insert Code] Existing tests: [Description or links] Operational constraints: [Uptime, rollback options]