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 exh...
Scanned 5/27/2026
Install via CLI
Skills Directoryopenskills install chrisallenlane/claude-swe-workflows---
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.
No comments yet. Be the first to comment!
