Multi-File Refactoring Plan Generation Prompt

This prompt is designed for tech leads and senior engineers who have already identified a structural improvement goal and need a safe, ordered execution plan before touching any code. The ideal user has access to the relevant source files and understands the target architecture, but needs the AI to reason about cross-file dependencies, ordering constraints, and verification gates. Use this when the refactoring involves renaming symbols, extracting interfaces, reorganizing modules, changing shared contracts, or migrating patterns across a codebase where the order of changes determines whether the build stays green.

The prompt assumes you provide the refactoring goal and the relevant source files or file paths. It does not perform the refactoring itself—it produces a step-by-step plan that a developer or coding agent will execute. The output includes explicit preconditions per step (what must be true before a file is touched), verification checks (how to confirm the step succeeded), and rollback triggers (what failure signals mean the step should be reversed). This makes it suitable for high-stakes changes in production codebases, monorepos, shared libraries, and any system where a broken intermediate state is unacceptable.

Do not use this prompt for single-file refactorings where ordering is trivial, for greenfield code generation where no existing dependencies exist, or when you lack access to the source files the plan must reference. The prompt also should not be used as a substitute for actual build verification—it plans the verification steps but does not run them. For changes involving database schema migrations, infrastructure-as-code, or polyglot codebases where dependencies cross language boundaries, supplement the prompt with explicit cross-system dependency documentation. After generating the plan, always review the ordering for deadlocks, validate preconditions against your actual build system, and run the verification checks before marking any step complete.

The following prompt template is designed to be pasted directly into your AI coding agent or LLM interface. It instructs the model to act as a senior software architect and produce a structured, actionable refactoring plan. The plan will decompose a high-level refactoring goal into an ordered sequence of file-level changes, ensuring that each step's preconditions are met by prior steps and that the codebase remains in a compilable, testable state throughout the process.

markdownCopy
You are a senior software architect planning a multi-file refactoring. Your task is to produce a detailed, step-by-step plan that can be executed safely and reviewed by a human engineering lead.

**Refactoring Goal:** [REFACTORING_GOAL]

**Repository Context:**
- Primary Language & Build System: [LANGUAGE_AND_BUILD_SYSTEM]
- Key Files/Modules Involved: [KEY_FILES_AND_MODULES]
- Existing Test Infrastructure: [TEST_INFRASTRUCTURE]
- Known Constraints: [CONSTRAINTS]

**Output Requirements:**
Generate a refactoring plan as a JSON object with the following structure. Do not include any text outside the JSON object.

{
  "goal_summary": "A concise restatement of the refactoring goal.",
  "overall_risk_assessment": "Low|Medium|High",
  "steps": [
    {
      "step_id": 1,
      "description": "A clear, actionable description of the change.",
      "files_to_modify": ["path/to/file1.ts", "path/to/file2.ts"],
      "preconditions": [
        "All prior steps must be completed and verified.",
        "The project must build successfully.",
        "Existing unit tests for [specific module] must pass."
      ],
      "verification_checks": [
        "Run command: [specific build or test command]",
        "Manually verify that [specific behavior] is unchanged."
      ],
      "rollback_instructions": "Use `git revert` on the commit for this step. If this step is part of a larger commit, manually revert the changes to the listed files."
    }
  ],
  "final_verification": {
    "command": "[e.g., npm run test:all]",
    "expected_outcome": "All tests pass and the build is green."
  }
}

**Critical Constraints:**
- **Ordering:** A step's preconditions MUST be satisfied by the completion of all previous steps. Do not create a step that depends on a change that hasn't been made yet.
- **Atomicity:** Each step should be as small as possible while keeping the project in a buildable state. Avoid combining unrelated changes in a single step.
- **Verification:** Every step must include a concrete verification check (e.g., a specific command to run, a test suite to execute, or a manual check to perform).
- **Rollback:** Every step must include a clear, safe rollback instruction.

To adapt this template, replace the square-bracket placeholders with your specific context. The [REFACTORING_GOAL] should be a high-level description of the change, such as "Extract the authentication logic from UserService into a dedicated AuthService." The [KEY_FILES_AND_MODULES] should list the primary files you know are involved, giving the model a starting point for its dependency analysis. The [CONSTRAINTS] field is critical for grounding the plan in reality—include details like "Must maintain backward compatibility with the v1 API" or "Cannot introduce new third-party dependencies." After receiving the output, you should validate the plan's ordering logic before executing any steps, as described in the full playbook.

This prompt is not a chat command; it is a planning step inside a larger refactoring pipeline. The typical harness calls this prompt after a change request is parsed and before any file is modified. The application layer must supply the repository map, the change intent, and any static analysis results as structured inputs. The prompt returns a plan, not code. That plan must be validated, ordered, and reviewed before execution begins.

Wire the prompt into a state machine with clear gates. First, assemble the input context: a dependency graph (from a build tool or static analyzer), a file inventory with symbol tables, and the refactoring goal expressed as a structured change description. Feed these into the prompt template as [DEPENDENCY_GRAPH], [FILE_INVENTORY], and [REFACTORING_GOAL]. The model returns a JSON plan with steps, preconditions, verification checks, and rollback triggers. Validate the output immediately: check that every step's preconditions reference files or symbols that exist in the input inventory, that no step depends on a later step's output, and that verification checks are testable. If validation fails, retry with the validation errors appended to [CONSTRAINTS] or escalate for human review.

For production use, log every plan generation attempt with the input hash, model version, and validation result. Store the validated plan as an immutable artifact before execution begins. When the plan executes, track each step's completion state and verify post-conditions before proceeding. If a verification check fails, halt execution and trigger the rollback sequence defined in the plan. Never let the agent continue past a failed verification without human approval. The prompt itself is stateless; the harness owns all execution state, retry logic, and safety gates.