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. 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 § "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 │
└──────────────────────────────────────────────────────────────────┘
Workflow Details
0. Startup
Follow the shared startup protocol in references/lead-startup.md. Skill-specific values:
- 0a. Branch and working-tree check — branch-name pattern:
lead-refactor/<date>(e.g.,lead-refactor/2026-05-12). - 0b. Resume existing run or start fresh — state-doc filename:
LEAD_REFACTOR_STATE.md. "Resume as-is" semantic: re-verify the current phase's state, then continue. - 0c. Elicit commander's intent — four fields per the schema in
references/autonomy.md§ "Commander's-intent schemas per skill //lead-refactor". Push-back examples specific to this skill: "Clean it all up" is not a scope — ask which modules; "Whatever severity" is not a floor — push for HIGH+ as the productive default. - 0d. Seed
LEAD_REFACTOR_STATE.md— include the four pinned intent fields,Current phase: phase-1, an empty cycle log, and an empty findings ledger. Gitignore the state doc per the protocol.
1. Phase 1: Tactical Refactor
Invoke /refactor with:
- Scope — from commander's intent field 1.
- Aggression ceiling — from commander's intent field 4.
/refactor loops internally until no more tactical improvements remain. Suppress /refactor's built-in /tidy-docs pass (step 7 in /refactor) — /lead-refactor does not include a documentation finisher; the operator can run /tidy-docs separately if needed.
After /refactor concludes:
- Verify tests pass.
- Record outcome in the cycle log: commits made, net diff, batches completed.
- Update state doc: current phase becomes
phase-2.
If tests fail after Phase 1 — andon cord (regression introduced by tactical refactor).
2. Phase 2: Architectural Review Loop
Bounded loop with max 5 architectural iterations. Each iteration has five sub-phases.
2a. Invoke /review-arch
Run /review-arch with:
- Scope — from commander's intent field 1.
When /review-arch reaches its ticket-proposal step, auto-approve. Record in the cycle log: ticket IDs proposed, scope of the proposal, and the fact that auto-approval was applied per commander's intent.
2b. Triage findings
For each finding produced by /review-arch:
-
Classify against severity floor:
- At or above floor → fix-list (blocks Phase 2 convergence).
- Below floor → deferred list. Record in
## Deferred findingswith severity and a one-line summary.
-
Screen for contested findings. If the skill believes a finding is wrong on substance (