/lead-refactor

name: lead-refactor
description: Autonomous comprehensive refactoring. Three-phase pipeline — Phase 1 /refactor (tactical, loops internally to convergence) → Phase 2 loop of /review-arch + /implement-batch until architectural findings converge below a severity floor (default HIGH+) → Phase 3 /refactor (catches tactical issues introduced by restructuring). Auto-approves /review-arch ticket proposals; pulls the andon cord on contested findings, breaking-change proposals, repeated implementation failure, or Phase-2 hard-cap exhaustion (5 architectural iterations).
model: opus

Lead-Refactor — Autonomous Comprehensive Refactoring

Drives a codebase through tactical cleanup, architectural restructuring, and a final tactical cleanup pass — all without operator involvement between startup and termination. The operator states scope, severity floor, constraints, and refactor aggression at startup; the skill then runs a three-phase pipeline that picks up where each previous phase converges.

This skill is the orchestrator-family member that pairs tactical refactoring with architectural review. It is a narrower sibling of `/lead-project` and a peer of `/lead-bug-hunt`. Unlike `/lead-bug-hunt`'s convergence loop, `/lead-refactor` has a fixed three-phase shape: each phase converges internally (via the sub-skills' own loops) rather than via a global loop over the macro phases.

Philosophy

This skill implements the autonomy discipline documented in [`references/autonomy.md`](../../references/autonomy.md). The shared discipline governs the five levers (altitude rule, pre-loaded options, pre-rebutted recommendation, commander's intent, risk budgets), the cascade rule, the no-unilateral-breaking-changes guardrail, and the shared handoff template.

Three phases, each internally convergent

Phase 1 invokes `/refactor`, which loops internally until no more tactical improvements remain. Phase 2 runs `/review-arch` and acts on findings at or above the severity floor via `/implement-batch`, re-running `/review-arch` until it produces no findings above the floor (or the architectural-iteration hard cap of 5 is hit). Phase 3 invokes `/refactor` again to catch any tactical issues introduced by Phase 2's structural changes.

There is no global loop over the macro phases. `/refactor` converging once and then `/review-arch` converging is sufficient — `/refactor`'s tactical scope (DRY, dead code, naming, complexity) does not generate new architectural opportunities, and `/review-arch`'s noun analysis is stable across re-runs. Two `/refactor` invocations and one Phase-2 inner loop is the right shape.

Auto-approval is delegated to the autonomy discipline

`/review-arch` is advisory; its ticket proposals are auto-approved under `/lead-refactor` per the orchestrator-family contract documented in [`references/autonomy.md`](../../references/autonomy.md) § "Auto-approval of sub-skill ticket proposals". The commander's-intent severity floor (field 2) is applied at the Phase-2 triage step (2b), not at the approval moment. The completion report lists every ticket created.

Trust the analysis, escalate the disagreement

`/review-arch` produces findings backed by noun-analysis evidence. This skill **trusts findings at or above the severity floor as actionable** — they are real architectural opportunities by `/review-arch`'s contract. The skill does not silently dismiss findings. If the skill genuinely believes a finding is wrong (the proposed restructuring would break a constraint, the finding misreads the domain model), that is an andon trigger ("contested finding"), not a unilateral disregard. No escape hatches.

Broad authority, narrow gates

The skill may: invoke `/refactor`, `/review-arch`, `/implement-batch`, `/implement`; create tickets via auto-approved `/review-arch` proposals; commit refactoring work via sub-skills; create and modify the working branch.

The skill may NOT without explicit authorization: push or merge to main/master, force-push, propose breaking changes (see `references/autonomy.md` § "No unilateral breaking changes"), invoke other skills outside the bounded repertoire, install dependencies, run irreversible destructive operations.

Workflow Overview

┌──────────────────────────────────────────────────────────────────┐
│                    LEAD-REFACTOR WORKFLOW                        │
├──────────────────────────────────────────────────────────────────┤
│  0. Startup                                                      │
│     ├─ 0a. Branch and working-tree check                         │
│     ├─ 0b. Resume existing run or start fresh                    │
│     ├─ 0c. Elicit commander's intent (4 fields)                  │
│     └─ 0d. Seed LEAD_REFACTOR_STATE.md                           │
│                                                                  │
│  1. Phase 1: Tactical refactor                                   │
│     └─ Invoke /refactor (loops internally to convergence)        │
│                                                                  │
│  2. Phase 2: Architectural review loop (max 5 iterations)        │
│     ├─ 2a. Invoke /review-arch (auto-approves ticket proposals)  │
│     ├─ 2b. Triage findings against severity floor                │
│     ├─ 2c. Form batch, invoke /implement-batch                   │
│     ├─ 2d. Verify tests pass                                     │
│     └─ 2e. Convergence check (re-run /review-arch)               │
│                                                                  │
│  3. Phase 3: Final tactical refactor                             │
│     └─ Invoke /refactor (catches tactical issues from Phase 2)   │
│                                                                  │
│  4. Termination                                                  │
│     ├─ 4a. Final verification pass                               │
│     └─ 4b. Completion report                                     │
└───────────────────────