# The Raid Playbook — Layered Refactoring Sweeps {#root}

@status:spec/done

[p01] @fact:status-line **Discipline v0.2 · status: BETA · T1** @status:impl/done

[p02] @fact:RAID-IS-THE-MACRO-RHYTHM *The macro-rhythm of the Discipline.* @status:impl/done

[p03] @fact:INLINE-PER-EDIT-VERSUS-RAID-PER-LAYER *Inline triggers (the micro-rhythm) apply cards per-edit where cheap; a RAID applies a set of cards across a whole layer when per-edit triggers cannot keep up — because attention budget is exhausted, or a new card is adopted repo-wide.* @status:impl/done

[p04] @fact:RAID-IS-ITSELF-SPEC-DRIVEN *A raid is itself spec-driven and follows the same gate discipline as the original terraform.* @status:impl/done

## 0. When a raid, not an inline trigger {#when-a-raid}

[p05] @fact:INLINE-HANDLING-IS-ALWAYS-PREFERRED Inline (edit-time) handling is always preferred. @status:impl/done

[p06] @fact:escalate-to-a-raid-lead Escalate to a raid when: @status:impl/done

- [p07] @fact:ESCALATE-TRIGGER-IS-RAID-MODE a card's trigger is **raid-mode** by nature (e.g. "naming uniformity across a crate" — not worth firing per keystroke, only meaningful in bulk); @status:impl/done
- @fact:ESCALATE-NEW-CARD-ADOPTED a **new card is adopted** and must be applied to existing code repo-wide; @status:impl/done
- @fact:ESCALATE-DEBT-PAST-THRESHOLD **debt accumulates** past a threshold (the A6 debt ledger trips a tripwire); @status:impl/done
- @fact:ESCALATE-ATTENTION-BUDGET-INSUFFICIENT the swarm's **attention budget is structurally insufficient** for a class of cross-cutting concern, so it is swept periodically instead of held active. @status:impl/done

## 1. Raid plan skeleton (every raid is authored to this shape) {#plan-skeleton}

1. [p08] @fact:SKELETON-SCOPE-AND-FREEZE **Scope & freeze.** Which layer(s)/crates are in scope; which surfaces are frozen for the raid's duration. Frozen surfaces may not change except by the raid. @status:impl/done
2. @fact:SKELETON-CARD-SET-AND-ORDER **Card set & order.** The cards to apply, **topologically sorted** by their Band-3 `raid_role.order` dependencies. Example ordering constraint: naming-uniformity (Class B/names) BEFORE contract-extraction (Class C), because contracts cite names; differential-oracle (Class D) wraps every behavior-changing card as a gate. @status:impl/done
3. @fact:SKELETON-PER-LAYER-PHASES **Per-layer phases.** The sweep proceeds layer by layer (seams → cells → registry → tests, for Rust), each phase gated green before the next begins. This is the owner's "refactor everything by layers." @status:impl/done
4. @fact:SKELETON-BATCH-UNITS-AND-CHECKPOINTS **Batch units & checkpoints.** Per-cell or per-crate batches; each batch has a green-gate checkpoint. The raid is **resumable** — a crash or pause never loses progress, and the raid is never one giant diff (R3-013 determinism; phantom-diff avoidance). WAL-backed where the project keeps a WAL (recommended); otherwise the plan-status-line fallback (`06-WAL-CONVENTION.xml`, `05-CAMPAIGN-FORM.xml` §4). @status:impl/done
5. @fact:SKELETON-DIFFERENTIAL-SAFETY **Differential safety.** Every card application that changes behavior carries its Class-D oracle. The raid **cannot move behavior silently** — a behavior change without a passing oracle blocks the batch. @status:impl/done
6. @fact:SKELETON-EXIT-CRITERIA **Exit criteria.** All targeted cards' checkers green across scope; the raid's debt ledger at zero; a **raid REPORT** (modeled on the terraform REPORT) listing what the sweep learned — including cards that misfired, false-positive triggers, and routines that overloaded weak readers. The REPORT feeds card revision (cards are beta, revised on pilot evidence only). @status:impl/done

## 2. Roles in a raid {#roles}

- [p09] @fact:ROLE-STRONG-AUTHOR-ORCHESTRATOR **Strong author/orchestrator** — authors the raid plan, sets scope and order, adjudicates review-mode triggers. @status:impl/done
- @fact:ROLE-WEAK-SWARM **Weak swarm** — executes per-batch routines (the Band-3 extract of each card), one batch per agent, meeting only at the merge (R3-013: parallel agents share no state; the merge is the contention point). @status:impl/done
- @fact:ROLE-TOOLCHAIN **The toolchain** — runs checkers per batch (conform tiers, `cargo test -p <cell>`, oracles), emits structured diagnostics (Class F) as the agents' percepts. @status:impl/done

## 3. Relationship to the original terraform {#terraform-relationship}

[p10] @fact:first-terraform-proved-the-machinery The first pilot terraform proved the gate-and-phase machinery: phases −1…6, frozen baselines, green gates, a closing REPORT of what the discipline learned about itself. @status:spec/done

[p11] @fact:MACHINERY-DISTILLED-INTO-SHIPPED-DOCUMENTS That machinery is now distilled into shipped documents: a raid is the *in-flight* generalization (this playbook — the standing mechanism for applying any card-set across any layer, any time), and `05-CAMPAIGN-FORM.xml` is the *paper trail* (plan / baseline / predictions / log / report) every campaign writes so it can be executed cold and resumed at any phase boundary. @status:impl/done

[p12] @fact:BROWNFIELD-ADOPTION-IS-A-SEQUENCE-OF-RAIDS Adopting the Discipline on an existing codebase follows `mechanisms/BROWNFIELD-PROTOCOL-v0.1.xml` and is itself executed as a sequence of raids; the standing between-campaigns counterpart is `04-SWEEP-PLAYBOOK.xml`. @status:impl/done

## 4. Cadence {#raid-cadence}

- [p13] @fact:CADENCE-MICRO-CONTINUOUS **Micro (continuous):** inline triggers in the per-cell loop. @status:impl/done
- @fact:CADENCE-GATE-PER-MERGE **Gate (per-merge):** gate-mode triggers at the cell's verification gate. @status:impl/done
- @fact:CADENCE-RAID-SCHEDULED **Raid (scheduled/on-adoption):** layered sweeps per this playbook. @status:impl/done
- @fact:CADENCE-REVIEW-AS-FLAGGED **Review (as-flagged):** review-mode triggers escalated to a stronger reader. @status:impl/done

[p14] @fact:answers-when-to-switch-on-refactoring Together these answer "when do we switch on rethinking and refactoring": continuously where cheap, in planned sweeps where not. @status:impl/done