lead-refactor

What this skill does

# 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                                     │
└──────────────────────────────────────────────────────────────────┘
```

## Workflow Details

### 0. Startup

Follow the shared startup protocol in [`references/lead-startup.md`](../../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`](../../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`:

1. **Classify against severity floor:**
   - At or above floor → fix-list (blocks Phase 2 convergence).
   - Below floor → deferred list. Record in `## Deferred findings` with severity and a one-line summary.

2. **Screen for contested findings.** If the skill believes a finding is wrong on substance