Spike 360

---
name: spike-360
description: >
  Interrogate authority before planning a feature, refactor, migration, rewrite,
  backfill, event-sourcing design, dual-write setup, new authoritative store, or
  system-of-record change. Fire whenever a proposal might introduce, move,
  duplicate, or replace authoritative state — or involves event sourcing or
  "event sourced," a "source of truth," "authoritative" data, dual-writes,
  replay, projections, replacing persistence, a new data store, or "design the
  architecture for / rewrite X" — and classify authority before writing any plan
  or reaching for a seam or architecture spike. The five levels: audit-only, read
  projection, dual-written peer, source of truth, replacement runtime; for
  audit-only or read-projection cases, fire just long enough to classify and
  stop, and for dual-written peer and above, require the surface and
  failure-scenario checks first. Triggering is deliberately broad — the skill
  classifies first and stops fast when the level is light. Skip only for a
  localized bugfix with no authority change, or when the authority level is
  already classified, agreed, and its required surface and failure-scenario pass
  is already complete.
---

# Spike 360

Interrogate the premise before you design the architecture.

The failure this prevents: a plan jumps straight to "event-sourced core" and only discovers, three phases in, that "source of truth" changes the entire problem class — new invariants, new failure modes, a migration nobody scoped. The fix is to change the first move from *design the architecture* to *interrogate the premise*.

## Core idea

Before writing any plan, decide **what authority the new system will hold**. That classification — not the design — sets the problem class. Most proposals that sound like "a new system of record" are actually solved by a smaller, lower-authority mechanism — often just a ledger — that the existing source of truth never has to defer to. Find that out first, on purpose, before a single phase or schema is drawn.

## Hard rule

> Classify the authority level before you write any migration plan — and at dual-written peer or above, audit the current read / write / side-effect surfaces before writing it too.

If you catch yourself sketching phases, schemas, or an "event-sourced core" before Gate 2 is answered, stop and answer Gate 2.

## The five gates (in order)

**Gate 1 — Problem narrowing.** What user or business problem actually triggered this? What is the smallest change that solves *only* that? What would be overbuilding?

**Gate 2 — Authority classification (the pivot).** What authority does the new system hold?

- **Audit-only** — it observes; nothing reads it back as truth.
- **Read projection** — a derived view; the old store stays authoritative.
- **Dual-written peer** — written alongside the old store; both claim truth.
- **Source of truth** — other systems now defer to it.
- **Replacement runtime** — it *becomes* the system; the old one is retired.

This ladder is also a reversibility ladder: audit-only and read projection are Easy to undo; dual-written peer, source of truth, and replacement runtime run Costly to One-way door once two systems claim truth or readers depend on the new one. **Those three trigger the heavy checklist (Gates 3-4)** — and a far larger scope than the proposal usually admits. Dual-written peer is in that tier on purpose: two writers means divergence, ordering, and reconciliation risk from day one — one of the most failure-prone designs this skill exists to catch.

**Gate 3 — Current-state audit** (dual-written peer and up). Enumerate, concretely:

- every **reader** and every **writer** of the state being changed
- every **persisted field** and every **external side effect** (emails, webhooks, payments)
- **transient vs resting** state — what is mid-flight vs settled
- **startup / load / backfill** behavior — how state is reconstituted from cold

**Gate 4 — Failure-scenario pass** (dual-written peer and up). For each, does the design survive it?

- crash *before* the write
- crash *after* the write, before the downstream mutation
- crash *after* an external side effect, before the write
- concurrent handlers interleaving across an `await`, async boundary, transaction gap, or retry boundary
- replay from an empty / brand-new log
- replay from a partial or corrupt tail
- legacy import with missing fields
- (dual-written peer) the two stores disagree — which one wins, and when is the divergence detected and reconciled?

**Gate 5 — Stop / Go.**

- If a smaller, lower-authority mechanism solves the Gate 1 problem, **recommend that first** — name it (a ledger, projection, cache, report table, reconciliation view, or no new store at all).
- For a **dual-written peer**, do not approve the path unless the design names the winner rule, drift detection, reconciliation process, ordering key, idempotency boundary, and rollback plan.
- If **source of truth** or replacement runtime is still genuinely wanted, **require explicit approval** and list the new invariants it must guarantee from this day forward.

## Output format

Lead with the authority level — it is the line that must survive skimming, because it decides everything after it. Then add only the gates that change the call. A light classification is a few lines; the heavy checklist (Surfaces / Failure scenarios) appears *only* at dual-written peer and up. Never pad.

**Authority level:** [Audit-only / Read projection / Dual-written peer / Source of truth / Replacement runtime] — [one line: what that means for scope and reversibility].

**Real problem:** [the triggering problem, one sentence] → **Smallest fix:** [the narrowest change that solves only that].

**Overbuild:** [what the current proposal adds beyond the smallest fix — or "none, the proposal is already minimal."]

*Dual-written peer and up only — otherwise omit both blocks:*

**Surfaces at risk:** [the readers / writers / persisted fields / side effects / transient-vs-resting / startup-load-backfill that actually bite — not all of them.]

**Failure scenarios:** [only the ones the design does not yet survive, each with the gap in a phrase. If it survives every applicable scenario, say so.]

**Stop / Go:** [Smallest safe mechanism first, named — ledger, projection, cache, report table, or no new store — or: authority shift approved, with the new invariants listed.]

## How this differs from its siblings

- **take-a-step-back** is the general pre-commit reset ("am I solving the right problem?"). spike-360 is its architecture-specific form: it forces a concrete authority classification and, above a threshold, a failure-scenario pass.
- **blast-radius** sizes a path you have *already chosen*. spike-360 fires earlier and questions whether the path's authority level is even the right one — its verdict can feed straight into blast-radius.
- **recon** — the read-only trace of the current system. spike-360 classifies authority *first*; once the level is settled, recon maps the readers, writers, and contracts the approved shape has to live with, and the plan is written against that map. A light audit-only or read-projection verdict stops spike-360 early but does not excuse the trace: recon still runs if the remaining implementation plan meets its trigger. Gate 3's surfaces pass is the classification-sized sample of that audit, not a replacement for it.
- **phase-0-spike** (an external workflow in `~/.claude/workflows/`, not a skill in this repo) maps seams, contract owners, and rollout invariants *after* you have committed to the refactor — it already assumes a source of truth exists (it asks each analyzer for the "contract owner"). spike-360 runs upstream and decides whether a new source of truth should exist *at all*. Run spike-360 first; only a "source of truth — approved" verdict makes phase-0-spike's seam-mapping worth doing.

## When not to escalate

If Gate 2 lands on audit-only or a read projection that the smallest-fix gate already satisfies, **stop there** — dual-written peer and above do not qualify, since a second writer or a new system of record already carries the heavy invariants. Classify it, say "a ledger or projection is enough — ship it," and skip Gates 3-4 entirely. Running the full crash-replay failure pass on an append-only log nothing reads back is exactly the manufactured gravity this suite warns against. The heavy checklist is *earned* by the authority level, not applied by default.

## Example 1 — source-of-truth creep, caught early

Input: "Let's make the orders subsystem event-sourced so we have a full history and a single source of truth for order state."

Output:

> *Before any event-sourcing design — one classification decides the whole scope here.*
>
> **Authority level:** Source of truth, edging toward replacement runtime — every reader of order state would now defer to the event log, not the orders table. One-way door once they do.
>
> **Real problem:** "We can't tell why an order's status changed." → **Smallest fix:** an append-only `order_events` ledger written beside the existing table for history and audit; the table stays authoritative.
>
> **Overbuild:** Event-sourcing makes the log the source of truth, which drags in replay, projections, and a migration of every reader — none of which the "why did status change?" problem requires.
>
> **Surfaces at risk (if you proceed to source of truth):** every order reader (API, fulfillment, billing), the `status` / `total` persisted fields, the payment-capture side effect, and order-load on startup.
>
> **Failure scenarios not yet survived:** crash after payment capture before the event writes (double-charge on replay); replay from a partial tail (orders resurrect in a stale status).
>
> **Stop / Go:** Ledger first — it solves the stated problem with no new invariants. If a true source-of-truth event log is still wanted, that is a separate, explicitly approved decision that must guarantee idempotent, deduplicated side effects (don't rely on exactly-once external effects — design for at-least-once delivery plus idempotency), deterministic replay, and a backfill for every legacy order. Get that approval *before* any plan is written.

## Example 2 — correctly not escalated

Input: "I want to log every admin permission change to a new table so we have an audit trail."

Output:

> **Authority level:** Audit-only — nothing reads the table back as truth; permissions still live where they live. Easy to undo.
>
> **Real problem:** "We have no record of who changed permissions." → **Smallest fix:** an append-only `permission_audit` row written in the same transaction as the change. That *is* the whole job.
>
> **Overbuild:** none — keep it append-only and resist adding reads against it later. The moment something defers to it for current permission state, re-run this check.
>
> No current-state audit or failure-scenario pass needed: an audit log no one reads back does not carry source-of-truth invariants.

## What success looks like

The operator learns the authority level — and therefore the true scope — in the first line, before a single phase or schema is drawn. A proposal that was about to become an event-sourced rewrite gets resized to a ledger; or, if the larger change is genuinely wanted, it walks in with its new invariants named and approved instead of discovered in phase three.