Legacy Module Refactor Roadmap Template

Operator-grade, milestone-driven plan that converts legacy code + techâ€‘debt notes into verifiable, reversible refactor milestones with interface contracts, tests, CI gates, and...

What You'll Get

Five ranked root-cause hypotheses with validation indicators and confidence guidance

3-7 prioritized, atomic milestones each including: objective, scope, minimal pseudo-diffs, interface contracts (signatures/behaviors), ordered migration steps, verification commands, acceptance criteria, rollback plan, and estimated timeline

Per-milestone automated test checklist: unit tests, integration/smoke tests, invariants, and performance/security checks with concrete commands

CI gating rules and required metrics to declare each milestone green (tests, coverage delta, latency thresholds), plus stop criteria

Final combined roadmap with estimated total effort and required reviewer roles

How to Use

1Collect required inputs before running: code excerpts (core files + public callers), repo root and module path, tech-debt notes, runtime constraints, desired end-state, CI/test commands, and current coverage/status. If any are missing, the template will request the exact files/snippets to proceed.

2Paste the collected inputs into the prompt placeholders (repo_root, module_path, tech_debt_notes, runtime_constraints, desired_end_state, risk_tolerance). Run in ChatGPT and iterate: answer missingâ€‘artifact queries first, then accept the generated milestones and apply minimal diffs in a feature branch for one milestone at a time.

3Use the included verification commands and CI gating criteria to validate each milestone. If a milestone fails acceptance criteria or violates stop criteria, execute the provided rollback steps and re-evaluate scope.

Make each milestone small, testable, and reversible

Limit each milestone to a single responsibility (ex: extract pure transform, split interface, add adapter). Require: (a) a minimal pseudo-diff that compiles, (b) two automated tests for every changed public API (happy + edge/failure), and (c) CI gating with clear thresholds. This minimizes regression risk and keeps rollbacks trivial.

Works Best With

Best used when you can provide code excerpts, CI config, and runtime SLOs

Include the exact files to refactor (paths and core file contents).

Provide CI pipeline config (.github/workflows or similar) and baseline test/coverage metrics.

Supply runtime SLOs and production release process (canary/blue-green) to produce precise gating and thresholds.

Prefer small modules with clearly identifiable public callers to enable atomic, reversible milestones.

Prompt Template


# Developer Productivity Prompt Blueprint (use EXACT section order)

## Goal
- Produce a prioritized, milestone-based refactor roadmap to break a legacy module into modular components without changing external behavior. Deliver milestones, interface contracts, migration steps, short-term mitigations, success metrics, estimated timelines, rollback strategy, and verification tests.

## Inputs
- Provide the following artifacts when running the prompt:
  - Code excerpts: core files under the legacy module and public callers.
  - Repo context: file paths and build/test commands.
  - Tech-debt notes: current issues, TODOs, known hacks.
  - Runtime constraints: latency, memory, cold-starts, concurrency, GC, deployment model.
  - Desired end-state: target module boundaries, public API surface, deployment units.
  - Constraints & non-goals: e.g., "no behavioral changes", "no major rewrites", "no new infra".
  - Current CI status and test coverage metrics.
- If any of the above are missing, the prompt will request the minimal missing artifacts before proceeding.

## Prompt
You are a senior engineer tasked with producing an operator-grade refactor roadmap for a legacy code module. Work from the repository root {{repo_root}} and focus on the legacy module at {{module_path}}. Use the tech-debt notes below and respect the runtime constraints below. The goal is to reach the desired end-state described below without breaking existing behavior and while minimizing scope creep.

Tech-debt notes:
{{tech_debt_notes}}

Runtime constraints:
{{runtime_constraints}}

Desired end-state:
{{desired_end_state}}

Risk tolerance (choose one): {{risk_tolerance}}

Deliverables required (produce all sections exactly as specified in Output Format). For each milestone, provide:
- Concrete files to change and minimal diffs (pseudo-diff snippets).
- Clear interface contracts (types/signatures/behaviors) for new modules.
- Migration steps with ordering, required build/test commands, and expected CI gating.
- Acceptance criteria (precise checks that confirm no behavioral change).
- Rollback instructions for each milestone.
- Estimated timeline (in days) and required reviewer roles.

Procedure:
1. First, list assumptions and unknowns derived from the inputs. If any critical artifact is missing, stop and list the exact files/snippets required.
2. Produce 5 ranked likely root-cause hypotheses that explain why the module accumulated tech debt; include confidence score (%) and indicators to validate each hypothesis.
3. Create a prioritized set of milestones (3-7), each with: objective, scope, required interface contracts, explicit migration steps (ordered), minimal patch examples (diff-like), verification commands, acceptance criteria, rollback plan, and estimated timeline.
4. For each milestone, list the top 3 risks and at least one short-term mitigation that preserves behavior.
5. Provide a minimal-attack surface strategy: which files/classes/functions must remain untouched until final integration to avoid regressions.
6. Provide an automated test/verification checklist per milestone: unit tests to add, integration tests to run, invariants to assert, smoke tests, and performance regression checks (commands and thresholds).
7. Provide CI gating rules and required metrics to declare a milestone "green" (e.g., test pass, coverage delta â‰¤ X, latency change â‰¤ Y%).
8. Produce a rollback plan and â€œstop criteriaâ€ that indicate when to halt the refactor and revert.
9. Provide a final summary roadmap combining milestones into a timeline with estimated total effort and required reviewers.

Formatting and strict requirements:
- Produce structured, ordered outputs only. Use numbered steps and bullet lists; avoid prose paragraphs.
- Output must include code-like pseudo-diff snippets for any suggested changes (5-20 lines) and explicit shell/CI commands to run verification.
- Prioritize minimal diffs and non-invasive changes; mark any suggested change that is invasive with a risk tag HIGH.
- When proposing interface contracts, include example signatures (language-appropriate), expected inputs/outputs, and error behaviors.
- Generate at least two concrete test cases per changed public API: one happy-path and one edge/failure case.
- All placeholders above are required and will be substituted before execution. If a placeholder cannot be filled, the agent must request it as per step 1.

Tone: decisive, engineering-first, risk-aware. Do not propose full rewrites. Keep each milestone atomic and reversible.

## Output Format
Output:
1) Assumptions/Unknowns
2) Likely root causes (ranked)
3) Fix plan (stepwise milestones with timelines)
4) Patch suggestions (minimal diffs / interface contracts)
5) Test/verification checklist (per milestone, with commands and thresholds)

Be exact and machine-parseable: use ordered lists, nested bullets, and code-like snippets where needed.

## Guardrails
- Do not assume files or behaviors not provided in {{repo_root}} and {{module_path}}.
- Prefer minimal, local changes; avoid touching unrelated modules.
- Do not introduce breaking changes to public APIs unless explicitly approved in {{desired_end_state}}.
- Every milestone must be independently verifiable and revertible.
- Mark any speculative recommendation (due to missing data) with "SPECULATIVE" and the missing evidence required.

## Examples
- Mini root-cause + fix excerpt:
  1) Root cause: Single god-class holding state and side-effects (confidence 85%). Indicator: many unrelated methods in one file and wide use of mutable singletons.
  2) Minimal fix excerpt (pseudo-diff):
     - src/legacy/service.js
       - remove: function processAll(items) { /* huge function with DB + metrics + formatting */ }
       + add: export function processItems(items) { return Worker.process(items) }
       + add: // new module src/legacy/worker.js with pure transform + injected DB client
  3) Quick verification: run npm run test:unit src/legacy/worker.test.js; expected: all tests pass and coverage delta â‰¤ 1%

Variables

Usage Notes

Not for

â€¢ Large greenfield rewrites or projects where you cannot provide code excerpts, build/test commands, and current CI status (the prompt requires repo-level inputs).

Do not include

â€¢ Concrete claims of performance/security improvement guarantees or certifications, numeric velocity/MTTR reductions, or any unverifiable benchmarks.

Legacy Module Refactor Roadmap Template

Convert a legacy module, techâ€‘debt notes, and runtime constraints into a prioritized, milestone-based refactor roadmap that preserves external behavior and provides minimal diffs, interface contracts, migration steps, per-milestone tests, CI gating, rollback plans, and an integrated timeline.

Turn this into a working asset in minutes.

Import into Workspace to auto-fill variables, adapt output style, and iterate with OctiAI's prompt editor.

Auto-fill & personalize from your inputs

AI-assisted edits: tone, structure, constraints

Attach context so outputs stay consistent

Iterate and save versions

What you'll get

Output format

Markdown

Best used when

When working on template or detailed.

Avoid when

Large greenfield rewrites or projects where you cannot provide code excerpts, build/test commands, and current CI status (the prompt requires repo-level inputs).

Made for

What to fill in

Use the guidance below to complete each placeholder with the right level of detail.

Repo Root