team-refactor

A panel of refactoring lenses reviews a scoped piece of code in isolated contexts, a KISS/YAGNI gate kills speculative work, the human approves a backlog, then execution happens in tiny behavior-preserving steps. Same family as team-debate: evidence-backed, attributed, recorded under .council/.

Core principle: refactoring changes structure, never behavior. Everything else in this skill protects that line or keeps the refactoring from becoming its own over-engineering.

REQUIRED BACKGROUND: follow team-protocol for dispatch, writers, the run folder, the agent contract, counting positions, code scope, lane hand-offs, structural choices, the handoff, execution, weakened checks, the sweep and auto-accept.

Iron Laws

1. Behavior-preserving only. Any observable change — outputs, rounding, error types, side effects, call order, emails, logs relied on — is a For team-review item. It is never a backlog step, even if the user said "fix it while you're there" or "whatever, make it clean".
2. No safety net, no refactor. Code the step touches must be pinned by tests first, and the tests must be proven to bite (see Step 0). Characterization tests of unchanged behavior are this skill's work; a missing test for new or changed behavior is team-review's.
3. One named refactoring per commit. Structure and behavior never share a commit (Beck, Tidy First).
4. Red means revert. A failing gate after a step → git checkout the step, shrink it, retry. Never debug forward.
5. An abstraction needs a present second case. Roadmap talk ("we plan to add providers"), TODOs, and "might" are not cases. Two real call sites today, or it doesn't exist.
6. Stay inside the approved scope. No drive-by edits outside the files and steps the human approved.

Violating the letter of these laws is violating their spirit.

The Panel

Templates in roles/ (overridable per project, see team-protocol). Each role is a lens, not an impersonation.

Card IDs carry the panelist's prefix: RS, MC, SQ, SN, DP, and MN for the Minimalist.

Panel size

On fresh code, the panel is Mechanics, Depth and Safety Net, and the Minimalist sits only as the Round 2 gate. Fresh means the current branch added more than half the lines in scope (the Fresh line of Recon's reply). All six sit when the code is not fresh, when the scope comes from a review record (§ Intake), or when the human asks. On fresh code, five or six of the six name the same top smell; these three cover the vocabulary, the depth and the safety net.

Separation of Context

Every agent gets the minimum it needs (team-protocol § Dispatch). templates.md (copied into the run folder, see team-protocol) holds what each one writes.

Put this line first in each panelist's How to work block: - Start from the Code Brief. Open a file only to confirm or cite evidence.

Flow

0. Preconditions   → scope, clean tree, green tests, profile
1. Recon           → Code Brief (one agent)
2. Round 1 (blind) → the panel in parallel (3 or 6) → Finding Cards
3. Round 2         → Minimalist gate on every card + tension pairs
4. Synthesis       → Backlog + For-team-review + Rejected + Tensions
5. Gate            → approves steps (auto-accept: no page); record + exec brief
   ── fresh session ──
6. Execute         → from the exec brief: Step 0 safety net, then one Step Batch per fresh executor
7. Record          → .council/refactors/YYYY-MM-DD-<topic>.md

0. Preconditions

• Scope: a path, module, or diff, or one or more review records (§ Intake), sized by team-protocol § Code scope, counting the lines in scope. To narrow it, Recon ranks hotspots by churn × complexity, with the smells it sees; each option also names its main smell, and one more option is "all of them, by team-protocol § Sweep" (each zone reviewed first, refactored where its review asks). When the scope is a diff (a branch, a merge request), the panel flags only smells the diff introduces or worsens. A smell in code the diff leaves untouched is listed once under Leave alone, never a card.
• Clean working tree (.council/ excepted; the record is committed alongside Step 0) and a green test run.
• No pending review fixes: a review record on this scope with Status: approved, not executed is executed first (team-protocol § Sweep). Step 0 pins behavior as it is; it must pin the fixed one.
• Profile: read .council/project-profile.md if present; offer team-scan if not (not required).
• Proportionality: size the Code Brief (templates.md § Code Brief) by team-protocol § Code scope. The panel (§ Panel size) and the gate always run. A scope small enough that you write the brief yourself also runs at most 2 tension pairs.

1. Recon → Code Brief

One agent writes the brief by templates.md § Code Brief, following the Recon rules of team-protocol § Code scope.

2. Round 1 — blind panel (parallel)

Dispatch the panel (§ Panel size) in one message. In each prompt, resolve the role template's placeholders: {PROJECT_PROFILE} → the profile path (or "none"), {SCOPE} inline, {CODE_BRIEF} → the brief's path, {FINDING_CARD_FORMAT} → templates.md § Finding Card.

3. Round 2 — gate and tensions (parallel)

• Minimalist gate: {ALL_FINDING_CARDS} → the panelists' files. It returns KEEP, SHRINK or KILL per card and lists the cards independent panelists found. Its KILL is a gate, not a vote. A KILL — behavior change sends the card to For team-review (templates.md § Synthesis).
• Tension pairs: where two cards conflict (same code, opposite moves), send each side the other's card for one direct reply. Agreeing roles skip.

4. Synthesis

A separate synthesizer agent writes the backlog by templates.md § Synthesis, caps included.

5. Gate

REQUIRED SUB-SKILL: team-view. The gate writer builds and renders the page by § Gate page; you serve it and read the decisions block. On an auto-accept run no gate writer runs: the synthesis carries every item's options (team-protocol § Auto-accept). The human approves steps (all, some, or edits). Suspected bugs are listed for team-review, never decided here.

Then the record writer writes the record and the exec brief, and you hand off (team-protocol § Handoff) with the prompt execute the refactor in <exec brief path>.

6. Execute

Execute by team-protocol § Execution, from the exec brief. The steps are the approved Step Cards, sized S, M or L; each executor gets its batch's Step Cards and the exec brief's header.

Step 0 — safety net (Safety Net): add characterization tests for every unpinned behavior the approved steps touch, run them green against the untouched code, then prove they bite: break the code deliberately (flip a rounding, a comparison, a constant), confirm a test fails, restore. Commit test: characterize <scope>.

Then group the approved steps into Step Batches and dispatch a fresh executor per batch (team-protocol § Execution). It commits each step on its own, so Iron Laws 3 and 4 still hold per step.

Last, the final reviewer runs § Final review. Its fix findings go to fresh executors as fixup! commits of their step (team-protocol § Execution), each with the Step Card it names.

7. Record

Complete the record (team-protocol § Writers); its Notes that suspect a bug are For team-review lines, for the next intake. Delete the exec brief and the run folder: anything worth keeping is in the record by now. Every later Recon reads it (team-protocol § Code scope).

Then name the next step. In a sweep, its next command (team-protocol § Sweep). Otherwise, when the record's For team-review list is not empty, hand off (team-protocol § Handoff) with the prompt team-review the For team-review lines of <record path> (team-review § Intake); when it is empty, say so in one line.

Intake

team-refactor <review record>… refactors what one or more review records list For team-refactor (team-protocol § Lane hand-offs). The scope is the files those lines name, with their callers in the same package. Recon's Code Brief puts the lines first in Hotspots, ahead of churn, and the full panel sits (§ Panel size). A line a past refactor record settled (Settled) goes to Leave alone. Run it once that review's fixes are executed (see Preconditions).

Rationalizations

The shared ones are in team-protocol. These are the refactor's own.

Red Flags — stop and return to the flow

• Writing an interface, base class, registry or plugin point with one implementation
• A commit message containing "and"
• Changing an expected value in an existing test
• A weakened check (team-protocol § Weakened checks), or a TODO where moved code used to be
• Editing a file outside the fence
• Reasoning "they'll need this later"
• A step that merges copies the Minimalist never compared
• Refactoring code whose review fixes are approved but not executed