| 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. 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 findings with severity and a one-line summary.
-
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.
-
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 § "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:
# 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.
