# Studio Develop Refactor Plan > Use inside an **existing app codebase** when the user wants a plan to bring the code in line with their ProductOS spec documents. Triggers on phrases like "create a refactor plan", "audit my codebase against the PRD", "plan the refactor", "what's different between my app and the PRD", "make REFACTOR.md", or any request to compare an existing codebase to `docs/PRD.md` and produce an actionable migration plan. Reads `docs/PRD.md` and `docs/ROADMAP.md` when they exist; when they don't, generates its own refactor-scoped PRD from `docs/PRODUCT.md`, `docs/DESIGN.md`, the codebase, and a short interview — no need to run `studio-develop-prd-roadmap` first. Audits the codebase, classifies every difference (missing / divergent / extra), walks the user through keep-or-remove decisions one at a time, then writes `docs/REFACTOR.md` — a phased, checkbox-tracked plan in the same format as the roadmap, executable by `studio-develop-refactor-build`. - Skill: `buildgreatproducts/studio-develop-refactor-plan` (Agent Skill) - Install (CLI): `npx skillmds@latest add buildgreatproducts/studio-develop-refactor-plan` - Raw SKILL.md: https://api.skillmd.com/api/skills/buildgreatproducts/studio-develop-refactor-plan/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: buildgreatproducts (https://skillmd.com/u/buildgreatproducts) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/buildgreatproducts/studio-develop-refactor-plan --- # Develop: Refactor Plan Audit the current codebase against `docs/PRD.md`, review the differences with the user, and write a phased refactor plan to `docs/REFACTOR.md`. Do not write the plan until the review in step 2 is complete. If `docs/PRD.md` is missing, do not stop — generate the refactor-scoped PRD first (step 0 below), then continue as normal. ## 0. No `docs/PRD.md`? Generate the refactor PRD Members refactoring an existing app don't need the full `studio-develop-prd-roadmap` interview — the app already answers most of its questions. Derive a **refactor-scoped PRD** instead: 1. Read `docs/PRODUCT.md` and `docs/DESIGN.md` in full (they're required by this phase; if either is missing, run its fast-track producer first — `studio-define-from-code` → `studio-define-product`, or `studio-design-design-system-from-code`). 2. Explore the codebase: structure, stack, data models, screens, auth/payment integrations — what the app *is* today. 3. Interview the user briefly, drawing on `productos/develop/guides/PRD-GENERATION.md` and `TECH-STACK-OPTIONS.md`: the core loop, what the refactored app must do that today's doesn't, what today's does that should go, and the target stack (confirm or change). 4. Write `docs/PRD.md` — the **target state** of this product, in the standard PRD shape, opening with the note `> Refactor-scoped PRD, generated by studio-develop-refactor-plan from PRODUCT.md, DESIGN.md, the existing codebase, and the member's decisions.` Spec what exists-and-stays, what changes, and what's added; skip from-scratch MVP scoping that doesn't apply. No separate `docs/ROADMAP.md` is needed on this path — `docs/REFACTOR.md` (step 3) is the executable plan, and its format below stands alone. Later feature work reads the PRD as usual. ## 1. Audit the codebase against the PRD Read both spec documents in full, then explore the repository: structure, dependencies, data models, API surface, screens, and auth/payment integrations. Build a complete list of differences, classified as: - **Missing** — required by the PRD but absent from the code (features, screens, entities, endpoints, states, requirements). - **Divergent** — present in both but implemented differently (stack mismatches, schema differences, different auth/payment providers, structure that doesn't match the PRD's repository layout, styling that ignores `docs/DESIGN.md` tokens). - **Extra** — present in the code but absent from the PRD (features, dependencies, dead code, abandoned experiments). For each difference, note the evidence: file paths, the PRD section it relates to, and a one-line impact assessment. ## 2. Review the differences with the user, one at a time Present differences one at a time — never as one giant wall. For each: what was found, what the PRD says, a recommendation (keep / remove / refactor / defer), and the cost of each option. Then let the user decide. Group trivially related items where it helps, but every **Extra** item needs an explicit keep-or-remove decision, and every **Divergent** item needs a decision on which side wins — the code or the PRD. If the user keeps something the PRD doesn't cover, flag that the PRD should be updated and note it for the plan's footer. Record every decision; these define the plan's scope. ## 3. Write `docs/REFACTOR.md` Once all decisions are made, show the user the proposed phase outline — titles, goals, rough task counts — and get approval. Then write the plan in exactly the same format as `docs/ROADMAP.md` (the format below stands alone when no roadmap exists): - **Header:** `# Refactor Plan — {productName}`, the note `> Generated by ProductOS. Checkboxes are updated as tasks are completed. The coding agent MUST mark tasks [x] as they are finished.`, a `**Status:** 0/{total} tasks complete` line, and a `**Current Phase:**` line. - **Refactor Philosophy:** the app must remain runnable after every phase; removals before rebuilds; one concern per task; test as you go; build straight through — commit at each phase boundary, no PR required, using the coding agent's built-in review for a quality pass. - **Phases** sized to the actual work (typically: cleanup and removals → foundation/stack alignment → feature parity → polish and verification). Every phase has a descriptive title, a one-sentence Goal, and a Reference sections list pointing at the exact `docs/PRD.md` and `docs/DESIGN.md` headings needed. - **Tasks** in the exact three-line format, IDs sequential across all phases (TASK-001 through TASK-NNN): ```markdown - [ ] **TASK-001** — Description of what to do Files: `file1.ts`, `file2.ts` Notes: Specific implementation details, gotchas. Verify: how to confirm it works. ``` Every task traces to a reviewed decision or PRD requirement, is ordered for sequential execution, sized to roughly one agent session (15–45 minutes), and ends its Notes with a verification step. - **Agent Session Guide**: read selectively via Reference sections, never skip tasks, update the status line, commit and push at each phase boundary. - **Footer:** the decisions made in step 2 (kept, removed, deferred) and any PRD updates the user agreed to. Finish by summarizing in conversation: phase count, task total, anything deferred — and point the user at `studio-develop-refactor-build` to execute the plan.