| name | quality-refactor |
| disable-model-invocation | true |
| description | Systematic tech-debt identification and safe reduction — plan → confirm → execute with per-change test verification. For explicit refactoring requests; casual tech-debt mentions route via /maestro-next |
| argument-hint | [<scope>] |
| allowed-tools | ["Bash","Edit","Glob","Grep","Read","Write","followup_task","interrupt_agent","list_agents","request_user_input","send_message","spawn_agent","spawn_agents_on_csv","wait_agent"] |
| session-mode | none |
| version | 0.5.55 |
Targeted refactoring with safety guarantees: plan → confirm → execute with test verification per change → reflection-log.md.
Scope: $ARGUMENTS (required)
- Module path: "src/auth" - specific directory
- Feature area: "authentication" - conceptual scope
- "all" - full codebase scan
If not provided, prompt user for scope.
Pre-load context (before refactoring)
- Coding specs: Run
maestro load --type spec --category coding to load coding conventions. Apply conventions to all refactored code.
- Review specs: Run
maestro load --type spec --category review to load review standards. Use as quality gate for refactored code.
- Role Knowledge:
- Browse:
maestro search --category coding
- Identify task-relevant entries, then load:
maestro load --type knowhow --id <id1> [id2...]
- All are optional — proceed without if unavailable.
Output boundary: Refactoring modifies source files within the declared scope only. Ancillary outputs (reflection-log.md) MUST target {run_dir}/outputs/. NEVER modify files outside the confirmed scope without re-confirmation.
1. **Plan before change** — NEVER apply refactoring changes without a confirmed plan. Every modification traces to a plan item.
2. **Behavioral equivalence** — refactoring MUST preserve existing behavior. All tests MUST pass after each individual change, not just at the end.
3. **Scope is locked after confirmation** — once the user confirms the refactoring plan, do NOT expand scope to include additional files or changes without re-confirmation.
4. **Incremental verification** — each discrete refactoring step MUST be verified (tests run) before proceeding to the next. NEVER batch multiple unrelated changes into a single verification.
5. **No feature creep** — refactoring MUST NOT add new functionality, change APIs, or alter public interfaces. If a beneficial API change is discovered, log it as a recommendation, do NOT apply it.
6. **Rollback safety** — if any test fails after a refactoring step, revert that specific change before attempting alternatives. NEVER proceed with failing tests.
Follow '~/.maestro/workflows/refactor.md' completely.
Phase Gates (MANDATORY, BLOCKING)
GATE 1: Analysis → Plan
- REQUIRED: Affected files and dependencies identified.
- REQUIRED: Refactoring plan created with specific changes.
- BLOCKED if missing: cannot refactor without identified targets.
GATE 2: Plan → Execution
- REQUIRED: User confirmed refactoring plan.
- BLOCKED if not confirmed: do not apply changes without approval.
GATE 3: Execution → Completion
- REQUIRED: All changes applied with test verification per modification.
- REQUIRED: Zero regressions (all tests pass).
- REQUIRED: reflection-log.md written with strategy and outcomes.
- BLOCKED if tests fail: fix regressions before completing.
Knowledge inquiry on completion:
After successful refactoring, ask user once: "Record refactoring pattern as coding convention?" If yes → recommend /maestro-spec add coding "<title>" "<pattern>" --keywords <kw1>,<kw2> --description "<summary>".
### Standalone report
--- COMPLETION STATUS ---
STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
CONCERNS: {description if applicable}
--- END STATUS ---
Ralph-invoked completion
End the step by calling the CLI (no text block output):
maestro run complete --session {session_id} --verdict {done|done-with-concerns|needs-retry|blocked} [--evidence {path}]
(run-id 可省略 — 自动解析当前 running 步)
Next-step routing
| Condition | Suggestion |
|---|
| All tests pass | /maestro-manage sync codebase (update codebase docs) |
| Test failures after refactor | maestro run create debug --session YYYYMMDD-debug-{topic} --intent "test failures after refactor in {scope}" |
| No test suite available | maestro run create auto-test --session YYYYMMDD-auto-test-{topic} --intent "{goal}" -- {phase} |
<error_codes>
| Code | Severity | Condition | Recovery |
|---|
| E001 | error | Refactoring scope/description required | Prompt user for module path, feature area, or "all" |
| E002 | error | Test suite not available for affected area | Suggest creating tests first, or proceed with manual verification |
| W001 | warning | Partial test coverage for affected area | Note uncovered areas, proceed with extra caution |
| </error_codes> | | | |
<success_criteria>
