Request Refactor Plan

Create a structured refactor plan through deep interview and codebase exploration, then file it as a Jira ticket for the team.

What the User Provides

$ARGUMENTS

Workflow

Step 1 — Understand the problem

Ask the user for a detailed description of:

• What problem they're trying to solve (not just "clean this up" — why does it matter?)
• Any ideas they already have for the solution
• What triggered this refactor now (new feature blocked by it? bug pattern? team pain?)

Step 2 — Explore and verify

Use the Explore agent to understand the current state:

• What does the code actually look like today?
• Does the problem the user described match what's in the codebase?
• What's the test coverage of this area?
• What other code depends on the area being refactored?
• Any recent git history that explains why it got this way?

Report back: "Here's what I found..." before proceeding.

Step 3 — Consider alternatives

Present 2-3 alternative approaches before interviewing on implementation. Ask:

• "Have you considered [alternative]?"
• "What makes your proposed approach better than [alternative]?"

This surfaces assumptions and ensures the planned solution is the right one.

Step 4 — Interview on implementation

Go deep on the specifics. Be thorough — vague plans produce bad refactors:

• Scope: What's changing? What's explicitly NOT changing?
• Interfaces: Which public APIs / component props / service methods change shape?
• Data model: Any schema or EF migration changes?
• Layering: Does this change which layer owns which logic?
• Consumers: Who calls the thing being refactored? Will they need updates?
• Feature flags: Does this need a flag or can it land clean?
• Rollback: If something goes wrong mid-refactor, what's the recovery plan?

Step 5 — Assess test coverage

Check the current test coverage of the area:

• Frontend: are there Vitest tests for the hooks/components being changed?
• Backend: are there xUnit tests for the services/repositories being changed?

If coverage is insufficient, ask: "There are no tests covering [area]. How do you want to handle this — write characterization tests first, or proceed carefully with manual verification?"

Don't proceed until there's a clear answer. Refactors without tests are the highest-risk code changes in the codebase.

Step 6 — Plan tiny commits

Break the refactor into the smallest possible commits. Follow Martin Fowler's rule: every commit leaves the codebase in a working state. Tests pass after every single step.

Format each commit as:

[n]. <verb> <what changes>
     Why: <one sentence on why this step is isolated>
     Risk: <low / medium — and what could go wrong>

Example pattern for a service extraction:

1. Add INewService interface (no implementation yet)
   Why: Establishes the contract before touching anything
   Risk: Low — additive only

2. Implement NewService behind the interface (not wired up)
   Why: Build and test in isolation before integrating
   Risk: Low — not called yet

3. Wire NewService into DI container alongside OldService
   Why: Both exist simultaneously — no callers broken
   Risk: Low — parallel run

4. Migrate callers one at a time to NewService
   Why: Each migration is independently rollbackable
   Risk: Medium — test each caller after migration

5. Delete OldService
   Why: Cleanup only after all callers verified
   Risk: Low — all callers already migrated

Step 7 — Create the Jira ticket

Write the plan to /tmp/refactor-plan-<slug>.txt then create the ticket:

acli jira workitem create \
  --project PLRS \
  --type Task \
  --title "Refactor: <concise title>" \
  --body-file /tmp/refactor-plan-<slug>.txt

Use this template for the body (plain text — no Jira wiki markup):

PROBLEM STATEMENT
-----------------
<The problem from the developer's perspective. Why does this need fixing?>

SOLUTION
--------
<The chosen approach and why it was selected over alternatives.>

COMMIT PLAN
-----------
<The full tiny-commit breakdown from Step 6. Be detailed.>

DECISIONS
---------
  - Modules affected: <list>
  - Interface changes: <describe — no file paths>
  - Schema/migration changes: <describe or "none">
  - API contract changes: <describe or "none">
  - Key architectural decisions made: <list>

TESTING APPROACH
----------------
  - What makes a good test here: only test external behavior, not internals
  - Modules to test: <list>
  - Existing test patterns to follow: <reference similar test files by description, not path>
  - Coverage gaps to address first: <if any>

OUT OF SCOPE
------------
<Explicitly list what is NOT changing in this refactor.>

NOTES
-----
<Anything else the implementer should know.>

After creating the ticket, print the ticket key and a one-line summary of the plan.

Step 8 — Offer next steps

• "Want to start implementation now? (/workspace-launch <TICKET_KEY>)"
• "Or leave it for sprint planning?"