quality-refactor

<required_reading> @/.maestro/workflows/run-mode.md @/.maestro/workflows/codex-run-mode.md </required_reading>

If not provided, prompt user for scope.

Pre-load context (before refactoring)

1. Coding specs: Run maestro load --type spec --category coding to load coding conventions. Apply conventions to all refactored code.
2. Review specs: Run maestro load --type spec --category review to load review standards. Use as quality gate for refactored code.
3. Role Knowledge:
   • Browse: maestro search --category coding
   • Identify task-relevant entries, then load: maestro load --type knowhow --id <id1> [id2...]
4. 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.

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 → Skill("spec", "add coding \"<title>\" \"<pattern>\" --keywords <kw1>,<kw2> --description \"<summary>\"").

--- 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 ralph complete <idx> --status {STATUS} [--evidence {path}]

Next-step routing

Condition	Suggestion
All tests pass	/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>

• Refactoring plan created and confirmed by user
• Changes implemented according to plan
• All tests pass after refactoring
• No regressions introduced
• reflection-log.md written with strategy and outcomes </success_criteria>