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):

  - [ ] **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.