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

## 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 (the proposed restructuring contradicts a constraint in commander's intent, the finding misreads the domain model), do not silently dismiss it. Record in `## Contested findings` and pull the andon cord.

3. **Screen for breaking-change implications.** If a finding's proposed restructuring would require a breaking change (per `references/autonomy.md` § "No unilateral breaking changes"), record in `## Breaking-change findings` and pull the andon cord. Do not auto-fix.

#### 2c. Decide

Three possible outcomes:

- **Form a batch and proceed to 2d** — fix-list non-empty, no contested or breaking-change findings.
- **Escalate and pull the andon cord** — contested findings or breaking-change findings exist.
- **Phase 2 converged, proceed to Phase 3** — fix-list empty (no findings above floor this iteration).

Batches are per-iteration. Don't co-mingle with prior iterations' tickets — verification stays tight.

Record the chosen outcome and rationale in the cycle log.

#### 2d. Act

Execute the batch via `/implement-batch` (or `/implement` for single-ticket batches when `/implement-batch` would be ceremony).

After the batch completes:
- Verify the full test suite still passes.
- Build/typecheck/lint clean.
- No constraint violations in the new commits.

If tests fail — andon cord (regression introduced by architectural change).

Sub-skill escalations cascade up per `references/autonomy.md` § "Cascade rule."

#### 2e. Convergence check

- Iteration counter increments by 1.
- If iteration counter reaches 5 → andon cord (Phase 2 hard cap; the architectural loop is not converging — operator should review).
- Otherwise → return to 2a.

Phase 2 ends when 2c determines the fix-list is empty (no findings above floor on the most recent `/review-arch` run). Update state doc: current phase becomes `phase-3`.

### 3. Phase 3: Final Tactical Refactor

Invoke `/refactor` again with the same scope and aggression as Phase 1. This catches tactical issues introduced by Phase 2's restructuring (renamed-but-not-cleaned modules, redundant code paths after consolidation, dead imports left from moves).

`/refactor` loops internally to convergence. Suppress its built-in `/tidy-docs` pass.

After `/refactor` concludes:
- Verify tests pass.
- Record outcome in the cycle log.
- Update state doc: current phase becomes `termination`.

If tests fail — andon cord.

### 4. Termination

#### 4a. Final verification pass

Before declaring done:

- Full test suite passes.
- No constraint violations in commits on this branch.
- Build/typecheck/lint clean.

If any check fails, treat as a blocker — return to Phase 3 to address.

#### 4b. Completion report

```
## Lead-Refactor Complete

### Commander's intent
[All four fields, verbatim]

### Outcome
[One paragraph: did the pipeline complete cleanly? Did Phase 2 converge
 within the 5-iteration cap? Were there contested or breaking-change
 findings that surfaced? Note any caveats.]

### Phase summary
- Phase 1 (tactical): N commits, net -X/+Y lines
- Phase 2 (architectural): N iterations, K tickets fixed, M tickets deferred
- Phase 3 (tactical cleanup): N commits, net -X/+Y lines

### Top things to scrutinize
[Three to five items where the skill's judgment is most likely to need
 review. Each item: one sentence + artifact (SHA, ticket ID, file:line).
 Examples: aggressive triage calls in Phase 2, batches with multiple
 attempts, areas where /review-arch findings were close-to-floor.]

### Tickets created and fixed (Phase 2)
- [#N] <title> — fix SHA <short> — /review-arch finding type
- [#N+1] <title> — fix SHA <short>
- ...

### Deferred findings (below severity floor)
[/review-arch findings not gated by the floor. Operator may run another
 iteration with a lower floor to address them.]
- [Medium | iteration 1] <description>
- [Low | iteration 2] <description>
- ...

### Contested or breaking-change findings (if any escalated)
- [contested | iteration 3] <description> — andon-cord SHA <short> in state doc
- ...

### Constraint adherence
[Confirm no violations. If any close calls, name them with commit SHAs.]

### Changes summary
- Branch: <branch name> (SHA <short>)
- Base: <base branch> (SHA <short>)
- Commits on branch: N (Phase 1: P1 + Phase 2 fixes: P2 + Phase 3: P3)
- Net lines: +X/-Y

### Run metadata
- Phase 2 iterations: N of 5
- Andon-cord pulls during run: N (each with handoff in state doc)
- Duration (wall-clock, approximate)
```

The operator decides whether to merge, run another iteration (e.g., with a lower severity floor), or pause.

## Commander's Intent — Field Reference

### Scope

Same shape as `/refactor`'s and `/review-arch`'s scope questions. Examples:
- "Entire codebase, excluding `vendor/` and `gen/`."
- "Just `pkg/auth` and `pkg/session` — recent rewrite, want comprehensive cleanup."
- "All production code, with extra attention to `pkg/legacy` (slated for restructuring)."

### Severity floor

The lowest `/review-arch` severity that gates Phase 2 convergence.

| Floor              | Effect                                                                                                       |
|--------------------|--------------------------------------------------------------------------------------------------------------|
| CRITICAL only      | Loops only on CRITICAL findings. Ships with HIGH+MEDIUM+LOW deferred. Use for "fix only the worst" sweeps.   |
| HIGH+              | **Default.** Acts on HIGH and CRITICAL architectural findings; defers MEDIUM and LOW.                        |
| MEDIUM+            | Acts on MEDIUM and above. Phase 2 may not converge in 5 iterations on large codebases.                       |
| All severities     | Not recommended. `/review-arch` tends to find LOW-severity opportunities indefinitely; unlikely to converge. |

### Constraints

Hard limits beyond the always-on guardrails (no breaking changes, no main/master writes).

Examples:
- "Do not modify the public API of package `auth`."
- "Do not touch `pkg/legacy` (slated for removal next quarter)."
- "Must remain Go 1.22 compatible."

### Refactor aggression

Aggression ceiling for both `/refactor` passes (Phase 1 and Phase 3). Mirrors `/refactor`'s vocabulary.

| Setting       | Effect                                                                                                                |
|---------------|-----------------------------------------------------------------------------------------------------------------------|
| conservative  | Only SAFEST and SAFE categories — dead code, formatters, simple DRY, single-use indirection.                           |
| moderate      | **Default.** Adds cross-module DRY, splitting files, removing abstraction layers.                                      |
| aggressive    | Adds removal of legacy code with unclear purpose, consolidating similar-but-not-identical behavior.                    |

## Severity & Triage

Triage is mechanical, not judgment-based. The severity floor is the only knob.

- **Floor and above** → fix-list, blocks Phase 2 convergence until resolved via `/implement-batch`.
- **Below floor** → deferred list, recorded in state doc and completion report, does not block.
- **Contested on substance** → andon cord, not silent dismissal.
- **Breaking change required** → andon cord, not auto-fix.

The skill does NOT:
- Re-rank `/review-arch`'s severity classifications. The reviewer's judgment stands.
- Bargain findings down to make convergence easier.
- Dismiss findings because "the analysis seems wrong" — that's the contested-finding path.

## Andon Cord Protocol

Follow the shared handoff template and per-skill extension protocol in [`references/autonomy.md`](../../references/autonomy.md) § "Shared handoff template" and § "Per-skill handoff extensions". Skill-specific values:

- **Title format** — `## Andon Cord — /lead-refactor — Phase N` (the phase is load-bearing).
- **Current-state additions:**
  - `Current phase: <phase-1 | phase-2 | phase-3 | termination>`
  - `Phase 2 iteration counter: <N>` (if currently in Phase 2)
  - `Findings ledger: <K fixed, M deferred, L contested>` (if currently in Phase 2)
  - `State doc pointer: see LEAD_REFACTOR_STATE.md`

### Andon cord triggers

Pull the cord when:

- **Contested finding.** The skill believes a `/review-arch` finding is wrong on substance — the proposed restructuring contradicts a constraint in commander's intent, or the finding misreads the domain model.
- **Breaking-change required.** A `/review-arch` recommendation requires a breaking change (per `references/autonomy.md` § "No unilateral breaking changes").
- **Regression introduced.** A `/refactor` or `/implement-batch` invocation made the test suite fail in ways unrelated to the targeted change.
- **Sub-skill cord cascaded up.** `/refactor`, `/review-arch`, `/implement-batch`, or `/implement` pulled its own cord for a reason this skill cannot resolve.
- **Phase 2 hard cap hit.** 5 architectural iterations elapsed without convergence. Something is likely structurally wrong (severity floor set too low, or the codebase has a recurring architectural pattern the reviewer keeps flagging).
- **Repeated batch failure.** `/implement-batch` fails on the same finding 3 times across different approaches.
- **Resume-time HEAD divergence.** On resume, recorded branch SHA does not match current HEAD.

## State Management

### `LEAD_REFACTOR_STATE.md`

Maintained at the repo root. Gitignored. Survives across invocations.

**Structure:**

```markdown
# Lead-Refactor State

Started: <timestamp>
Branch: <branch-name>
Branch SHA at startup: <short SHA>
Base branch: <main-branch>
Base SHA at startup: <short SHA>
Last cycle HEAD: <short SHA>
Current phase: <phase-1 | phase-2 | phase-3 | termination>
Phase 2 iteration: N (if applicable)
Status: <active | paused-on-andon | complete>

## Commander's Intent

### Scope
<verbatim>

### Severity floor
<CRITICAL only | HIGH+ | MEDIUM+ | All>

### Constraints
- <constraint 1>

### Refactor aggression
<conservative | moderate | aggressive>

## Cycle log

### Phase 1 — <timestamp> — HEAD <short SHA>
- /refactor invoked with aggression <X>, scope <Y>
- Outcome: N commits, net -X/+Y lines, tests pass

### Phase 2 — Iteration 1 — <timestamp> — HEAD <short SHA>
- /review-arch: <findings count by severity>, tickets proposed <#N..#M>
- Triage: <count above floor | below floor | contested | breaking>
- Decide: <form batch | escalate | converged>
- Act: /implement-batch outcome, fix SHAs
- Verify: tests pass / fail

### Phase 2 — Iteration 2 ...

### Phase 3 — <timestamp> — HEAD <short SHA>
- /refactor invoked, outcome: ...

## Findings ledger

### Fixed (Phase 2)
- [iteration 1 | ticket #14] <description> — fix SHA <short>
- ...

### Deferred (below floor)
- [Medium | iteration 1] <description>
- ...

### Contested
- [iteration 3] <description> — andon cord pulled, see § Andon Cord history

### Breaking-change-required
- [iteration 2] <description> — andon cord pulled, see § Andon Cord history

## Andon cord history

### Phase 2 iteration 3 pull
<full handoff text, pasted>

## Open questions

- <question>
```

**Update at every phase transition and every Phase 2 iteration.** The state doc is the durable orientation — losing it means losing the agent's memory.

### `.gitignore`

Ensure `LEAD_REFACTOR_STATE.md` is ignored. Commit the `.gitignore` change on the working branch at startup if needed.

## Hard Caps

- **Phase 2: 5 architectural iterations** — each iteration is one full `/review-arch` + one batch-implementation. If the loop hits 5 without convergence, the architectural shape is not stable under the current severity floor or scope; pull the andon cord.
- **3 consecutive failed batches** — if `/implement-batch` fails on the same finding 3 times across different approaches, pull the andon cord.
- **No file-touch or dependency-change budgets** — explicitly excluded per `references/autonomy.md` § "Risk budgets."

## Integration with Other Skills

**Relationship to `/refactor`:**

`/lead-refactor` invokes `/refactor` twice — once in Phase 1 (clear tactical noise before architectural analysis) and once in Phase 3 (catch tactical issues introduced by Phase 2's restructuring). Run `/refactor` directly when you want only tactical cleanup; run `/lead-refactor` when you want the full tactical + architectural + tactical pipeline.

**Relationship to `/review-arch`:**

`/lead-refactor`'s Phase 2 invokes `/review-arch` repeatedly until findings converge below the severity floor. `/review-arch`'s ticket proposals are auto-approved per the orchestrator-family contract. Run `/review-arch` directly when you want an advisory architectural read-out without implementation.

**Relationship to `/lead-project`:**

`/lead-project` is the open-ended orchestrator — it takes broad commander's intent and decides which skills to invoke. `/lead-refactor` is a fixed-shape three-phase pipeline for one specific outcome. Use `/lead-project` when refactoring is one of several concerns; use `/lead-refactor` when comprehensive refactoring is the sole objective. `/lead-project` may invoke `/lead-refactor` as a sub-skill when its Decide phase identifies a refactor sweep as the next move.

**Relationship to `/lead-bug-hunt`:**

Sibling orchestrator-family skill with a different outcome contract. `/lead-bug-hunt` eliminates bugs above a severity floor; `/lead-refactor` cleans up code structure above a severity floor. Both use the same auto-approval contract for sub-skill ticket proposals and the same 4-field commander's intent shape (scope, severity floor, constraints, aggression-or-finisher).

**Out-of-axis skills:**

`/review-*` skills other than `/review-arch`, `/scope-project`, `/test-mutation`, `/tidy-docs`, `/tidy-git`, `/bug-*` are not in this skill's repertoire. If your goal mixes refactoring with bug elimination, security review, doc tidying, or test surveying, use `/lead-project` instead. `/lead-refactor` is deliberately narrower.

If you want doc cleanup after refactoring, run `/tidy-docs` separately after `/lead-refactor` completes — structural changes in Phase 2 commonly invalidate inline docs and code examples.