refactor

What this skill does

<!-- plugin/skills/refactor/SKILL.md -->
---
name: refactor
description: This skill should be used when the user asks to "refactor this", "restructure code", "reorganize modules", "rename and move", "safe restructuring", "reorganize code", "move and rename", or wants to reorganize code without changing behavior.
argument-hint: "[refactoring goal]"
disable-model-invocation: true
---

# Safe Refactoring

> **Requires:** Claude Code Agent Teams feature.

Architect-planned, reviewer-validated code restructuring with per-step compilation checks.

**Arguments:** $ARGUMENTS

## Instructions

1. **Parse arguments** (optional):
   - Any text -> use as the refactoring goal/context for the architect

2. **Determine context**: What code to refactor, the goal of the restructuring, and any constraints. If no context is obvious, ask the user what they'd like refactored.

---

### Phase 1: Analysis

3. **Launch for analysis**: Call the Mira `launch` MCP tool to get the architect agent spec:
   ```
   launch(team="refactor-team", scope=user_context, members="atlas")
   ```

4. **Create the team**:
   ```
   TeamCreate(team_name=result.data.suggested_team_id)
   ```

5. **Create and assign** the analysis task:
   ```
   TaskCreate(subject=atlas_agent.task_subject, description=atlas_agent.task_description)
   TaskUpdate(taskId=id, owner="atlas", status="in_progress")
   ```

6. **Spawn Atlas (architect)** using `Task` tool:
   ```
   Task(
     subagent_type="general-purpose",
     name="atlas",
     model=atlas_agent.model,
     team_name=result.data.suggested_team_id,
     prompt=atlas_agent.prompt + "\n\n## Refactoring Goal\n\n" + user_context,
     run_in_background=true
   )
   ```
   IMPORTANT: Do NOT use `mode="bypassPermissions"` -- Atlas is read-only.
   IMPORTANT: Always pass model="sonnet" to the Task tool. This ensures read-only agents use a cost-efficient model.

7. **Wait** for Atlas to report via SendMessage.

---

### Phase 2: Validation

8. **Launch for validation**: Call `launch` to get the reviewer agent spec:
   ```
   launch(team="refactor-team", scope=user_context, members="iris")
   ```

9. **Spawn Iris (safety reviewer)** using `Task` tool:
   ```
   Task(
     subagent_type="general-purpose",
     name="iris",
     model=iris_agent.model,
     team_name=result.data.suggested_team_id,
     prompt=iris_agent.prompt + "\n\n## Refactoring Plan\n\n" + atlas_plan,
     run_in_background=true
   )
   ```
   IMPORTANT: Do NOT use `mode="bypassPermissions"` -- Iris is read-only.
   IMPORTANT: Always pass model="sonnet" to the Task tool. This ensures read-only agents use a cost-efficient model.

10. **Send Atlas's plan** to Iris via `SendMessage` so she has the specific plan to validate.

11. **Create and assign** the validation task.

12. **Wait** for Iris to report via SendMessage. Then shut down both analyst agents.

---

### Phase 3: Synthesis

13. **Combine** Atlas's plan with Iris's feedback:
    - If Iris found missing callers or risks, incorporate them
    - If rated "needs revision" or "too risky", revise accordingly

14. **Present** the validated refactoring plan to the user and **WAIT for approval**.

---

### Phase 4: Implementation

15. **Execute the refactoring steps** yourself. For each step:
    - Make the changes
    - Run `cargo test --no-run` to verify compilation (NEVER use --release)
    - If it doesn't compile, fix before moving to the next step

16. For **large refactors** (5+ files), launch implementation agents:
    ```
    launch(team="refactor-team", scope=implementation_plan, members="ash")
    ```
    Spawn implementation agents with `mode="bypassPermissions"`:
    - Group steps by file ownership to avoid conflicts
    - Max 3 steps per agent
    - Each agent verifies with `cargo test --no-run`

---

### Phase 5: Verification

17. **Launch for verification**: Call `launch` to get the verifier agent spec:
    ```
    launch(team="refactor-team", scope=summary_of_changes, members="ash")
    ```

18. **Spawn Ash (build verifier)** using `Task` tool:
    ```
    Task(
      subagent_type="general-purpose",
      name="ash",
      model=ash_agent.model,
      team_name=result.data.suggested_team_id,
      prompt=ash_agent.prompt + "\n\n## Changes Made\n\n" + summary_of_changes,
      run_in_background=true,
      mode="bypassPermissions"
    )
    ```

19. **Wait** for Ash to report. If tests fail: fix regressions or update test imports/paths.

---

### Phase 6: Finalize

20. **Report** summary of structural changes to the user.
21. **Cleanup**: Send `shutdown_request` to remaining agents, then `TeamDelete`.

## Examples

```
/mira:refactor
-> Prompts for what to refactor, then runs the full analysis -> validation -> implementation cycle

/mira:refactor Split the database module into separate files per concern
-> Atlas analyzes the DB module, plans the split, Iris validates, then implements

/mira:refactor Rename the "watcher" module to "file_monitor" across the codebase
-> Safe rename with caller analysis and per-step compilation checks
```

## Agent Roles

| Phase | Agent | Focus |
|-------|-------|-------|
| Analysis | Atlas (architect) | Map current structure, design target, plan migration steps |
| Validation | Iris (safety reviewer) | Verify completeness, check for hidden behavior changes |
| Verification | Ash (build verifier) | Run tests, compilation, linters between steps |