ops — execute a milestone's Operational & Investigation tasks

Companion to groom (backlog→Ready) and design (design tasks): this skill works the 🔧 Operational and 🔎 Investigation tasks — the interactive, judgment-bound ones that are not auto-dispatched. Its whole value is a verification discipline that refuses to trust premises, statuses, or convenient shortcuts, and that treats an unattended pass as staging, never as conclusions. Follow it even when a task "looks like a one-liner."

This skill shares its planning-procedure core with /groom and /design — see ../_shared/reference/hard-rules.md (canonical source packages/backend/src/planning/procedureCore.ts) for the rules this skill also follows: deterministic load, not hand-fetch (Flow step 2 below), the human/operator is the gate (see § Status handling), and no silent writes (verdicts land on the journal, never the task page, until the operator confirms).

Scope: this skill runs 🔧 Operational + 🔎 Investigation, plus observational / E2E 🧪 Testing folded in as an Investigation variant (run the system live → a disposition: pass / blocked-pending-fix / pass-with-caveat — there is no "fail"). Test-authoring 🧪 Testing (writing test code, no live-data dependency) and 📝 Docs stay out — the former is really 💻 Code, so reclassify it (the loader lists any it caught in test_authoring; flag the rest at triage). (Legacy 🛠️ Tooling tasks that predate the split are grandfathered; treat a live one as whichever mode it actually is.)

The two modes

🔧 Operational — change prod/environment state through a sanctioned surface, and verify it landed. The decision is already made; the work is the doing + verification. Uncertainty is in breadth / source / mechanics, never in whether or what. Failure mode = a bad write (wiped siblings, wrong source, a re-derive never run). Two flavors:

• Directed — fully-specified change: a backfill/re-derive from a known-good state, a dependency install, wiring a tool/MCP into sessions, a machine migration. Little/no research.
• Research-first — the what to author needs research (which teams/tournaments/streams/ aliases): governed by "research → present → author on confirmation; never apply before presenting."

🔎 Investigation — produce a defensible decision about a live issue from production data. The decision is the deliverable. Output = filed follow-on tasks (Code / Operational / more Investigation) + an occasional inline change. Uncertainty is in the conclusion itself. Failure mode = a wrong conclusion. Includes spikes (verify an external surface before code depends on it). An Investigation may produce a Code task — that is a legitimate output, never a reason it should have been Code. It must never contain "implement module X" as its own acceptance criterion; that gets filed as a separate Code task.

Variant — observational / E2E 🧪 Testing. A Testing task that runs the system live and observes is an Investigation whose deliverable is a disposition (journal field). There is no "fail" state — the outcome is one of:

• pass — completed: demonstrated by value (verified working, not a green-looking degenerate/zero result);
• blocked-pending-fix — it surfaced an issue: file the fix task and set this task to 🗂️ Ready + Depends On the fix (it re-runs after the fix lands). Carries the observed evidence
  • the filed fix — same root-cause bar as any Investigation (name the mechanism, never "it broke"). This is not a dead end and not "Done" — it's a dependency.
• pass-with-caveat — done, with one aspect superseded/deferred and noted.

Breadth before depth: run every check in the check table to at least a by-value first reading and present the table before deep-diving any single failing check — unless an incident freeze applies. Digging one family's outage while the other checks sit unrun is the failure.

Test-authoring (writing test code) is not this — it's 💻 Code.

Execution context — autonomous vs interactive (this replaces "Phase 1 / Phase 2")

The old two-phase framing conflated two orthogonal things. Keep them separate:

• Read-only diagnosis before any write is a safety ordering — it holds inside every run, every mode. Never mutate to learn something you can read.
• Who may commit a verdict or a write is the execution context — autonomous (overnight, no operator: --print / no TTY) vs interactive (an operator is present). Context is auto-detected from the invocation; an operator may override it explicitly.

An autonomous run stages; it emits a staging report; a later interactive run resolves it. But the split governs what you may commit, not whether to do the first-pass. Every run — autonomous and interactive — does the full read-only first-pass over every task first (Flow step 3). An interactive run does not get to skip staging and jump straight to resolving: unless it is consuming a prior autonomous run's journal, it must run that first-pass itself before it walks any task. Skipping the first-pass is the single most common way this skill is mishandled — treat step 3 as a gate, not a suggestion.

Commit-authority matrix

The load-bearing rule: in the autonomous column, nothing ever flips to ✅ Done and nothing records a definitive verdict — not even a directed Operational change it successfully applied (that records "applied + verified, pending operator confirmation"). Status-flips and verdicts are always interactive. This lets a "run-only-from-known-good-state" backfill actually run unattended while still keeping a human on every close.

Disciplines

Universal — every run, every mode

• Read-only diagnosis before any write. Never mutate to learn what you can read.
• Acknowledgement is not compliance — the next action is what agreement looks like. Saying "you're right" and then proceeding with your own plan is a null response that costs the operator the correction twice. On accepting a correction: state what you are doing differently, then do that — not the plan you already had. A correction persists for the rest of the run; a rule conceded once does not need re-conceding each time it applies.
• Ambiguous input: resolve it before acting. If you call an input ambiguous, you may not act on your interpretation in the same turn — ask, then act. Real run: a bare + was read as approval, said aloud to be ambiguous, and acted on anyway. Flagging an ambiguity and then proceeding is worse than either asking cleanly or acting silently: it transfers the risk to the operator while keeping the action. This binds hardest on anything that writes or files.
• The sanctioned read surface is the default — use it freely, no permission needed. The analyst MCP + the /ops HTTP read endpoints are the normal read path; reach for them without asking the operator. "Read by value" almost always means these, not raw SQL. Ad-hoc read-only SQL through the project's read-only role (direct PG) is a lighter, still-sanctioned fallback for what the endpoints don't cover; only a write (or the write DSN) is break-glass.
• Never force blocked or prod-risky actions (deploys, fleet/DB restarts, dumping live credentials, instrumented prod deploys). Document, hand to the operator, move on. One blocker never stalls the run.
• Incidents: freeze → capture → classify → file → don't loop. A live prod incident gets the incident sub-protocol — see reference/incident.md. The one rule to remember without opening it: capture volatile evidence (a stack dump, pg_stat_activity, thread states) BEFORE any restart — a restart destroys it. Risky recovery (a fleet/daemon restart, a pgbouncer bounce) is the operator's call — but "operator's call" = their decision, your execution under phase auth. In a co-hosted interactive session the operator often has no server access; never hand a command back to an operator who can't run it — get the decision, then you run it. And don't recover-in-circles: killing a stuck session/backend to clear a lock is pointless while the root code bug is still live — it recurs and leaves the fleet in an unknown state. Capture + file the fix; don't loop on restarts.
• Drill-budget / conversion tripwire — it caps fixing, never understanding. Diagnostic depth has no budget: an Investigation digs until the root cause is proven (see § 🔎 Investigation). A diagnosis is never paused to ask whether to continue — carry it to the proven root cause and report; the only legitimate stops are a genuine external / access blocker, or the work turning from diagnosing to implementing. What the budget stops is open-ended doing solo — implementing a fix, building a module, excavating a large change. The moment the work turns from diagnosing to implementing, stop — file a Code task carrying the proven root cause, capture the state, and surface it. Don't build solo. Concretely:
  • An Operational task that can't be completed via a sanctioned surface without new code is blocked-pending-Code (or was mis-declared Investigation). Stop, file, surface — don't excavate a code change solo.
  • A workaround that hands the operator code to run (a script, a patched copy, a one-off tool) is new code: file the fix as a 💻 task, wire Depends On, and wait. Never paste or ship an untracked copy, however well tested.
  • An Investigation keeps diagnosing to root cause; it stops only to file (a Code / Operational task carrying the proven cause) when the remaining work is doing, not understanding. One that turns out to be a well-defined change dressed as a question → downgrade to Operational and do it (within the autonomous ceiling).
• The buck stops with this run — don't deflect your own work into a deferral ("it's not my problem"). The drill-budget above stops open-ended building solo; it does not license the opposite and more common failure — under-doing: reflexively reaching for "file a task / defer to a next session / satisfied by a future move / record it as deferred" for work that is this session's to do and executable now. The judgment-bound doing that IS the task — exercising the change, verifying execution by value (never "it'll be tested later / in prod"), triaging what you backfilled, closing every AC item — is yours, not a follow-on's. Before you defer or file anything, ask: is this genuinely blocked (a proven external / access / Code blocker), or am I defaulting to the easy option? A follow-on is for what's out of scope or genuinely blocked, never a place to offload the part of the task you'd rather not do. And when a deferral IS correct, it must be kept honest by a real forcing function (a one-time precondition at the point of resumption, a hard dependency) — never a rot-able backlog note, and never a standing per-run check that taxes every future execution to police a finite, shrinking condition.
• A throughput/latency cause is named only with its measured share — never as host contention. "The host is IO-busy" is contention, not attribution. State the cause with its share of the producer's own time: an idle-inclusive profile or a statement-time delta (e.g. pg_stat_statements) on the producer's own process. Real run: a slow backlog drain was blamed on a busy host; the profile and statement deltas showed five distinct causes in the producer itself.
• Point dumps locate a stuck thread; they do not rank costs. Rank costs with an idle-inclusive recording over ≥ 60 s (e.g. py-spy record --idle). Real run: 5/5 dumps named a function that the 60 s recording put at 4.6% while the real costs sat elsewhere (29%, 22%).
• Recommend from the proven mechanism and the project's stated priorities — never a revert or an easy-out lever as the default. A rollback, or a lever that trades live freshness for correctness (e.g. capping a live watermark behind a backlog), is not offered as the recommendation, least of all under time pressure. Real run: "revert three commits" was proposed; investigating instead found two more proven defects the revert would have hidden. Live first, then historical, unless the project says otherwise.
• Every issue met during the run is this run's to investigate — on or off the task list. A live anomaly, an alarm, a degenerate reading, an unexpected cost, a stated blocker: dig it in-session to the proven root cause under § Evidence law and file the follow-on carrying it. Deferring it to /investigate or "a later session", or noting it and moving on, is the failure mode — including for an unrelated daemon or a restart loop spotted in passing. Real run: a memory-thrash loop was pointed at /investigate; the dig proved the root cause and filed three tasks.
• A committed live window stays watched. When a run names a future live window as the re-run or measurement target for a check, keep a watch armed for it — or state explicitly, in that same turn, that you are stopping and the window will be missed. Naming a window and then doing nothing leaves it silently unmeasured.

Evidence law — the claim shape dictates the admissible evidence

Wrong conclusions in an ops run share one mechanism: a cheap check returned a result consistent with the hypothesis, and the search stopped. Reciting "falsify before you assert" does not prevent it — the discipline gets recited and violated in the same session. What prevents it is mechanical. Before stating a claim — in a journal entry, a verdict, a filed task, or to the operator — find its shape here and confirm you ran that evidence, not the cheap substitute.

Row 2 is a gate, not a preference: no claim about what a session / daemon / job did — or why — before you have read its own record. State rows, intent rows, and artifacts describe the envelope; they cannot distinguish "it never supplied the value" from "it supplied the value and something downstream ate it." Real run: nine intent members all showed a null proposal field and the cause was reported as "the session didn't supply one"; the transcript showed a 3,272-character proposal supplied every time, silently discarded by the envelope. A supporting base rate does not corroborate a cause you have not read the record for — that wrong answer came decorated with 191/557 rows and looked well-evidenced.

Validate the instrument before trusting what it returns — state the coverage. A query is not a read of the record until you know what it dropped. Before concluding from any filtered, joined, or type-coerced query, state the fraction of the population it covers: rows returned vs rows that exist. A filter that drops more than ~20% of the population is not a read of the record — it is a sample, and must be described as one or widened until it isn't. Real failure: a transcript reader filtered to two event types, dropping 489 of 571 events, while the preceding command had already printed the type histogram proving it — the number was generated, then ignored, and the remainder was reported as complete.

A fraction is a claim about what the excluded part contains, not only how many. Stating "E only affects 9% of attribution segments" reads as low-impact until you check what's in that 9% — those 82 windows in a real run were exactly the stage-day parallel-stream slots, the live match chat, and the small percentage hid that entirely. Before citing a coverage/exclusion fraction as evidence of low impact, state what the excluded (or included) rows are, by value — never the count alone.

A zero or a thin result is a claim about the instrument before it is a claim about the world. Before reporting any zero, confirm the comparison can be true at all: types match (an ISO string compared against epoch-ms columns matches nothing, ever), the filter value equals what the producer writes, the id-space is the same. This is the false-negative checklist in § 🔎 Investigation, applied one step earlier — to the instrument rather than the result.

Replicate a predicate exactly, or you are measuring a different question. When you reconstruct a check the system performs — a budget, a capacity, a coverage count, an eligibility or backfill filter — copy its predicate verbatim from the source. Every condition you add that the code lacks, and every loosening you allow that it doesn't, changes the question while the number keeps looking authoritative. Real run: a dispatch budget computed with an archived = 0 filter the code does not have returned 9 where the true budget was 0, and that one added condition hid the root cause across a dozen reads; a coverage scan reported 5 by prefix-matching and 22 by exact match. Neither was bad arithmetic — both answered a question nobody asked. Paste the predicate, don't paraphrase it; if you must diverge, say which condition you changed, in the same breath as the number.

Column types vary per table — print one raw value before reading meaning into a filtered result. The epoch-ms trap has an inverted twin: a started_at stored as ISO TEXT compared with >= Date.now() - N returned rows from nine days earlier presented as "since this morning" — a silent coercion producing plausible, wrong history. Never infer a timestamp column's type from a sibling table: SELECT one row, read the literal value, confirm your comparison can be true against it. And never conclude absence from truncated output — a head -40 on a list nearly became "those rows were deleted." Truncation is your formatting, not the data's.

State the disconfirming test in the same clause as the claim — before the operator asks, not after. "Not running — systemctl list-units across the host shows no matching unit, and the supervisor config names none." A claim whose disconfirming test you cannot name in one clause is not ready to state, let alone journal.

Timestamps spanning more than one day carry their date. Format YYYY-MM-DD HH:MM:SS. Bare HH:MM:SS collapses a multi-day window into an apparent single day and inverts before/after conclusions.

🔧 Operational

• Writes only through the project's audited path (its config-CRUD / ops affordance), never raw SQL / hand-edits. Verify each write; prefer reversible, greppable-for-rollback changes.
• Read-modify-write any replace-semantics shared state (a binding/linkage/config row the CRUD replaces wholesale) — read current, merge, write the full set. Blindly creating wipes siblings.
• Verify the daemon reconciled AND actually captured — it heard the config change, built the actor, and a post/signal/record landed. Authoring a row is not ingesting.
• "Done ≠ deployed ≠ seeded ≠ working." A merged task may be un-deployed; a deployed code path may have no operational seed applied (a recurring silent-degradation trap). Confirm the seed is present on prod, then that the behavior actually runs. When the task at hand is the milestone's config-seed task, work it via § Milestone config-seed below, not by reading its task body as the worklist.
• No accepted gaps — every step closes or is filed. A multi-step Operational task is Done only when every step is completed or filed as a follow-on that closes the gap. "Accept the gap" is never an option to present — silently dropping the price side of a backfill and shipping trades-only is the exact failure this prevents. If a step can't be done now, file the follow-on that will and say so; never narrow the deliverable to what happened to work.
• Verification that must wait for a future event is a gate item, not a blocker. If a reconcile/capture step can't be observed until a future event (a live match, a timer firing), accrete it on the task via gate-state-client.mjs accrete as an atomic item (classification usually Read-Only; text naming the exact query + the expected observable). It does not block proposing Done. Never a scheduled one-time self re-check, never a standing per-run check.
• Research-first: research, decide, apply under the step-4 authorization. Pull authoritative per-entity data (the source's own page), verify each item exists the project's way, lay out what the task assumed vs. what you found, choose source/scope/breadth, and apply via the audited path; the walk records the choice. Stop before the write only at a § Stop condition (an irreversible action, or a source/scope choice between materially different outcomes the task does not settle).
• Writes and the write-DSN are break-glass — deliberate, logged, not the default. (Reads are not — see the sanctioned-read-surface rule under Universal.) Never run session-level read-only GUCs over a pooled connection (they leak to other clients); for ad-hoc read SQL use the project's read-only role over the direct/unpooled path, and route every write through the audited CRUD.
• A service config reload goes through the deploy, not a hand restart. An env or config file change to a long-running service takes effect through the project's deploy path, which rolls the service. Record it as pending the next deploy rather than restarting the service by hand. A hand restart is break-glass, needs explicit operator approval, and must first confirm from source which unit the restart verb actually targets.
• Operational execution is a phase, not per-action break-glass. The break-glass framing above is for one-off actions; a task's execution is a sustained burst of them (one run: a price backfill + 8 per-market trade backfills + a re-match ≈ 10 prod actions). Metered one approval-prompt at a time, that's death-by-a-thousand-prompts — an operator had to abandon a run, flip to auto mode, and resume. So at the phase boundary, state the shape and request phase-level authorization once: "this phase is ~N prod actions via the audited path (writes / daemon restarts / secret-DSN reads); recommend auto/accept for the duration — I'll narrate each and stop at any real decision point." That converts N prompts into one decision + running narration. In an interactive run this is the Flow step 4 order sign-off — it is the authorization. It's safe because Operational writes are already required to be reversible + greppable-for-rollback (above) — and you still stop at the § Stop conditions (anything irreversible, an outcome choice the task does not settle, a harness block).

🔎 Investigation

• The buck stops here — dig to the proven root cause. An Investigation's job is to find the mechanism — demonstrated by value + the exact code path/line (or config row / state), not hypothesized. Keep asking "why, really?" until the cause is proven, not plausible. Stopping short is legitimate only at a genuine external/access blocker (no read access to the evidence). Never discharge the undug question into a "next fix" — a lead_lag family got "fixed" while the real align() root cause sat unfound for a whole milestone precisely because the investigation stopped at "a fix was filed."
• A filed follow-on carries a proven root cause — never another investigation of the same question. If your follow-on title starts with "Investigate…", you haven't finished investigating — you punted. File a Code / Operational task that names the proven cause and the fix, not a re-run of the diagnosis.
• Run every claim through § Evidence law before stating it. For any conclusion — "it's fine", "no bug", "will self-heal", "the numbers say X" — find the claim's shape in the table and confirm you ran the admissible evidence, not the cheap substitute; then state the disconfirming test in the same clause. Ask "why, really?" and "would that actually fix it?" one level deeper than feels necessary — that flips the answer more than half the time.
• Read one instance of the data before proposing a mechanism. Structural reasoning about carriers, fields, schemas, and where a value could live — with no payload read — produces confident nothing. Real run: four turns proposing carriers for a payload (a new intent kind, a group-level field, a designated bearer) without reading a single instance of the payload; one query showed the required structure already existed, in a kind already in the set and already used for exactly that. Before designing a mechanism, SELECT one row and read it.
• Find the precedent before proposing a mechanism. Search the same subsystem for how this shape of problem is already solved, and prefer extending that to inventing a parallel path. Real run: a fix was proposed for a broken auto-adjudication step when the answer was that the step should not exist — "replace a broken machinery by some extra broken machinery"; and a closure design anchored on the wrong precedent while the right one sat forty lines above code already read three times. Corollary — a deviation from a consistently-applied pattern is usually the defect, not a gap to fill with machinery. Where a system applies one rule everywhere (sessions stage, the operator disposes), the place that departs from it is the bug. Fix the deviation; don't build a second mechanism to service it.
• Silent-success paths — can the record tell "no work" from "blocked"? A component reporting status=ok, items_processed=0 is indistinguishable from one that is wedged, and reads as healthy everywhere. When you find one, ask whether the record separates the two cases — if it cannot, that is itself a finding, independent of which case is live. Same family as "deployed but inert", one layer out: the mechanism fires, does nothing, and says so in the voice of success.
• When the operator holds the one instrument you lack, ask for a single scoped observation — never ask them to diagnose. Ask for one observation, and enumerate what each possible answer would mean, so their reply resolves the question instead of starting a discussion ("which of these four strings is in the panel?", "is the element present at height 0?"). That is using an instrument, not escalating. "Can you look and tell me what's wrong?" hands back the diagnosis that is yours.
• An explanation of why the system might be right is not a finding. On hitting something odd the reflex is "is this actually correct?" — not "here is why this might be intentional." A docstring, a naming convention, an apparent symmetry: each is a claim to check, and the check is usually thirty seconds of reading. When the operator rejects a rationale, drop it — do not re-offer a weaker one (latency, performance, "probably deliberate") to salvage the position. That spends the operator's scrutiny defending a guess.
• Treat a registered number as a claim to re-derive, never a fact. A prior task's stated figures, a "known" count — re-derive it from live data before you build on it.
• A degenerate/zero reading is attributed only after replicating the producer's own predicate on one scope by value — never from the shape of the inputs. A plausible-sounding input-side explanation ("thin prices", "the destroyed tag corpus", "sparse tags on outrights") is not a finding until you have run the producer's own query on one concrete scope — its CTE (e.g. a stage1 post_counts CTE), its funnel counters, its run-duration/crash record — and read what it says by value. Real run: three separate degenerate readings, each initially explained by a plausible input-side cause, each turned out to be something else entirely once the producer's own predicate was run — markets closed before the pairing window, a cohort fan-out that had replaced the channel scope, sub-horizon burst slices, and a 10-hour actor crash loop a deploy-health check reported as healthy. The tell that you're still guessing from input shape: you can name a cause but not the producer's own query/counter that shows it.
• Read outputs by value, not by row-count/existence, and check provenance. N rows of zero/degenerate output looks identical to real work; a row's presence never proves it's current or correct (version + timestamp vs the relevant deploy). Before concluding 0 / dark / broken, run the false-negative checklist: (a) does your filter value equal what the producer actually writes — the exact source string, enum member, id-space? (two premise-inversions this way this run: a livestats filter vs the actual source='lol'; an esports tournament_id false-negative); (b) is the scoping key a known false-negative (documented in context.md / the retrospective)?; (c) is provenance/version current? A "0" that's really a filter mismatch is the single most common wrong conclusion.
• Verify a source the project's own way. A browser/WebFetch success ≠ the daemon's success — fetch with the project's actual client/UA/auth; confirm a walled surface clears via the client the daemon uses.
• Consult the authoritative source-of-truth doc first — not optional. Before interpreting any zero, anomaly, or "this looks broken," read the relevant findings / retrospective / architecture page (surfaced by the loader / Flow step 2). It very often documents the exact case and the interpretation trap — skipping it flips real findings (it inverted a seed-verification finding this session). Do this at the moment of interpretation, before you record even a candidate.
• "Mirror the existing X" is the highest-risk sentence in a filed task. It reads as safe and low-effort, which is why it ships unexamined — it delegates a semantics question to an implementer who resolves it by pattern-match. Never write "mirror X" alone: name the exact helper, counter, or guard, state what carries across, and state what does not. Two regressions from one run came from this one sentence shape — a completion path mirrored across a type boundary where the source's terminal state and the target's were different state machines (result: a record marked ✅ Done with its required field NULL), and a budget mirrored onto an unnamed counter whose DB-backed variant counted 104 archived idle corpses (result: the budget pinned at 0). Test before writing it: if the implementer resolves this mirror the most obvious way and the obvious way is wrong, does anything catch it? A mirror across a type boundary almost never transfers whole.
• Output is filed tasks, not code. File 🔲 Backlog tasks (Code / Operational / Investigation) for what you find. Accurate-the-first-time beats file-then-correct — run the one-level-deeper check before filing, and set priority from the verified severity, not the first impression. Interactive: file the follow-on under the step-4 authorization — no stop before filing unless a § Stop condition applies (e.g. an outcome choice the task does not settle). Because it is filed unreviewed, the one-level-deeper check above is mandatory, and the consolidated close lists every filed follow-on so the operator can reframe, defer, or reject it there.
• Milestone routing for filed follow-ons: critical / blocks the current milestone → the current milestone; non-critical / needs-a-migration / a next-theme concern → the next milestone. (This run: the lock fix + windowing → M12; index-sargability + catchup-daemon → M13.)

The staging journal

Long ops runs must not discard expensive research, but must not persist unverified decisions either. Those reconcile only if research and verdicts live in different places with different durability rules.

The staging journal lives in the backend's ops_journal DB table — one row per eligible task, pre-seeded and reconciled server-side by GET /api/ops-context (Flow step 2; same reconcile job loadOpsContext always did, now the only path to it). Read it with node ~/.claude/scripts/ops-client.mjs journal --milestone <M> (wraps GET /api/ops-journal?milestone=<M>). Documented shape (one entry per task id):

• mode (operational|investigation), flavor (directed|research-first|null), worked_in (autonomous|interactive)
• evidence[] — the durable, expensive part: probes/queries run, values observed with provenance (version + timestamp vs deploy). This is what survives context exhaustion.
• finding_or_proposal — the candidate finding (Investigation) or staged authoring proposal (Operational)
• falsification — Investigation: "what I'd observe if false, and did I look."
• state — the provisional marker: pending (loader-seeded, not yet worked — the first-pass must advance every entry off this) | candidate | staged-proposal | applied-pending-confirm | blocked | incident-frozen | resolved
• filed_followons[], needs_from_operator
• resolution — null until interactive; on operator confirmation, { decision, by, at, persisted_to } (task page / follow-on / arch page)
• disposition — 🧪 Testing variant only: pass | blocked-pending-fix | pass-with-caveat | null (loader-seeded null; no "fail" — a surfaced issue → blocked-pending-fix + a filed fix + a Depends On). Set with ops-client.mjs set-state … --disposition <value>.

Rules that make it safe:

• Research persists in evidence[], always tagged provisional by state. A fresh interactive session (new process) reloads the journal and resumes without re-excavating.
• Verdicts don't leak. The autonomous pass writes only to the journal — never to the Notion task page. A decision reaches the task page only at state: resolved (after interactive operator confirmation).
• Multi-session durability. If even the interactive review runs long, unreached tasks stay staged for the next session. A task becomes resolved only when the operator confirms and its residue is persisted to its proper home.
• Trimming — the journal holds open work, not history. Once an entry reaches resolved and its residue is persisted to its proper home, that home (the task page / follow-on / arch page) is the audit trail — so drop the entry. Trimming happens server-side, on every GET /api/ops-context call: any ops_journal row whose task is now ✅ Done or no longer on the open board is deleted as part of that request's reconcile (the DB-backed twin of the old loader's job 3 — see reconcileJournal in packages/backend/src/ops/opsJournal.ts). Never hand-edit the DB. On resolve, set state: resolved + resolution with ops-client.mjs set-state --task <id> --state resolved [--resolution '<json>'] (wraps POST /api/ops-journal/:taskId/state — deterministic field write, validated against the allowed state-transition graph server-side); the next ops-context call trims it: deletion is the fragile part, not the write, and it's no longer yours to get wrong. A non-🔎 Investigation → resolved from any state other than applied-pending-confirm (e.g. a 🧪 Testing task at candidate) is rejected with 400 unless the call carries one of: --no-change-reason '<text>' (non-empty; nothing needed changing) or --reconciliation '{"description":"<what was reconciled>","passed":true|false}' (object with a string description and boolean passed). set-state's response on success is the updated ops_journal row itself (same shape as one entry in journal --milestone <M>'s entries[]) — not { entry } — and ops-client.mjs also prints a one-line <taskId> -> <state> confirmation to stderr.
• Interactive-throughout is a lighter path. The full pending → candidate / staged-proposal / applied-pending-confirm → resolved vocabulary exists to protect the autonomous→interactive handoff. When a run is interactive from minute one (no autonomous pass to hand off), the journal is a live scratchpad, not a handoff artifact — you may collapse the provisional states to just pending → resolved, still recording resolution per task. Here evidence[] can stay in-conversation and land on the task page (that's what worked) — by design ops-client.mjs set-state writes only state / resolution / disposition / reconciliation / noChangeReason, not evidence: a fragile evidence append isn't worth it when the operator is present and the task page is the durable home. Don't carry the full staging ceremony when there's no handoff to protect.
• This is ops-native and distinct from /wrap (which sweeps broad session residue).

Milestone config-seed — driven by the seed-state API

The milestone's one accreted config-seed task (config-template/task-writing.md § Milestone config-seed) is orchestrator-tracked state, not a task-body checklist to read top to bottom. Every seed a Code task contributed at grooming time lives as a seed_item row — applyable once its min_deployed_commit is an ancestor of the target project's current deploy SHA. Every apply attempt is a seed_item_event — that log is the durable record, the operational twin of the gate's gate_item_event. Do not read the config-seed task's body as the seed worklist — the live worklist is seed_item rows, never a bulk load of the whole applyable set.

This is a thin human-driven loop over the seed-state API (packages/backend/src/routes/seedState.ts, business logic in packages/backend/src/seed/seedService.ts), called through the sanctioned node client:

node ~/.claude/scripts/seed-state-client.mjs <command> ...

seed-state-client.mjs is the vendored sanctioned node client (see packages/backend/scripts/seed-state-client.mjs, re-vendored via the /sync-guidelines skill), using $ORCHESTRATOR_DEVICE_TOKEN (host/port default to 127.0.0.1:3000, overridable via $ORCHESTRATOR_BACKEND_HOST / $ORCHESTRATOR_BACKEND_PORT) the same way the other sanctioned session clients (ops-client.mjs, gate-state-client.mjs) do.

1. Readiness — node ~/.claude/scripts/seed-state-client.mjs readiness --project <P> --milestone <M> → {status: 'green'|'blocked', blocking}. green — nothing left to apply this milestone; report and stop. blocked — every unconfirmed seed with its project/state, as a worklist map only — pull the actual batch via next, never disposition straight off this summary.
2. Pull one applyable batch at a time — node ~/.claude/scripts/seed-state-client.mjs next --milestone <M> --deploySha <sha> [--limit <N>] (default limit 1). deploySha is the target project's currently-deployed commit — resolve it the project's own way (its context.md documents the deploy-tracking surface); never guess it. Applyability = deploy-included (the seed's min_deployed_commit is an ancestor of deploySha) AND not yet confirmed. Never bulk-load the milestone's full seed set.

3. Apply through the target project's own audited config-CRUD, then record the outcome. For each pulled item: read item.spec (node ~/.claude/scripts/seed-state-client.mjs detail <id> for sources + prior events before re-attempting one). The operator applies the seed via the target project's audited config-CRUD / ops affordance — never raw SQL, and the orchestrator never applies another project's config on its behalf (that's why next requires a deploySha the caller supplies rather than applying anything itself). Batch consent is fine here — one up-front "these N seeds, go" per pulled batch, the same phase-level authorization an Operational execution phase gets, not a prompt per seed. Then verify reconcile + capture the ops-native way ("Done ≠ deployed ≠ seeded ≠ working" — confirm the row landed AND the consuming worker picked it up AND the mechanism actually emits) and record every attempt, not just resolving ones:

   node ~/.claude/scripts/seed-state-client.mjs event <seedItemId> \
     '{"outcome":"applied","evidence":"<what was authored + how verified>"}'

   outcome is applied (authored, reconcile/capture not yet fully confirmed), confirmed (reconcile + capture verified — resolves the item), or blocked (could not apply — must carry filedFollowon, the id of the follow-on filed for the blocker; the server rejects a blocked event without one). Include evidence (freeform) and operator when known.

4. Loop — repeat 2–3 until readiness reports green, or the operator stops for the session; remaining seeds stay pending/applied and nothing is lost, state persists server-side.

5. Correcting a seed recorded applied in error — applied is non-terminal (authored, reconcile/capture not yet confirmed), and recording it is the step most likely to be wrong (a session's own claim, ahead of actual verification). To return it to pending:

   node ~/.claude/scripts/seed-state-client.mjs reopen <seedItemId> "<reason>" [operator]

   reason is required when the item is currently applied (the server rejects the reopen with a 400 otherwise) — an erroneous applied is an operator correction and must say why. The resulting reopened event carries {reason, priorState: 'applied'} in its evidence, so the log shows what was undone. pending items cannot be reopened (no-op guard); confirmed/blocked/discarded reopen as before, with reason optional.

What this replaces: it does not fetch or parse the config-seed task's body as the seed worklist, and it does not bulk-load a milestone's full seed set.

Built, not activated. This ships in the skill now, and seed-state-client.mjs is vendored to ~/.claude/scripts (via the /sync-guidelines skill), but the seed-activation task still owns confirming it runs live end-to-end for a real milestone — do not fold that actuation here.

Flow

1. Invoke → detect context (autonomous vs interactive) and state which you're in. If interactive and the run will enter an operational execution phase — a sustained burst of audited-path prod actions — get phase-level authorization up front, not per-action (see § 🔧 Operational → operational execution phase). It isn't only writes that trip the auto-mode classifier — break-glass reads (fetching a DSN from /etc/… secrets) and daemon restarts do too; scope the up-front authorization to all three.
2. Load context deterministically — call the ops-context backend route. It is the sanctioned Flow-2 load, now served in-process by the backend instead of a vendored shell-out: node ~/.claude/scripts/ops-client.mjs context --milestone <M> --project <dir> (wraps GET /api/ops-context?milestone=<M>&project=<dir>; loopback + device-authed — set ORCHESTRATOR_DEVICE_TOKEN in the session env first). It deterministically (a) loads the fixed context pages — the master Project Context page + the source-of-truth docs (findings / retrospective / architecture / guidelines), returned in the response's contextPages; (b) enumerates the 🔧 Operational / 🔎 Investigation tasks — plus observational / E2E 🧪 Testing folded in as an Investigation variant (mode investigation, flavor testing), while excluding test-authoring Testing to the worklist.test_authoring triage list (reclassify → 💻 Code) — into worklist.executable / dep_blocked / needs_grooming / closed_not_done (worklist.newly_unblocked further flags which executable entries were dep_blocked on the previous ops-context load for this milestone and have since cleared every blocking dependency — call these out explicitly in step 4; they read identically to an always-ready task otherwise.); and (c) pre-seeds + reconciles the ops_journal DB table server-side — one row per eligible (Ready / In-Progress) task at state:"pending", preserving prior worked fields and trimming rows whose task is now Done / off-board (same job the old loader did to its on-disk journal, now done to the DB on every call — see reconcileJournal in packages/backend/src/ops/opsLoad.ts / opsJournal.ts). Then also Read the project's context.md (write paths, prod/deploy, operator read-surface & break-glass). Do not hand-load a partial subset — skipping the master page / source-of-truth docs is the #1 load failure this route exists to prevent. (If the route is truly unreachable, load all of the above by hand — and record what you loaded as a context_loaded: [...] note for the run.) This load is a precondition: a successful ops-context response — or a hand-load with context_loaded recorded — MUST exist before you interpret any zero/anomaly. A failed call must never silently become a skipped load; that is exactly how the master Project Context + source-of-truth docs get skipped.

3. First-pass — work every eligible task. Mandatory in every context, before resolving any one. Order doesn't matter here. Respect Depends On (only ✅ Done satisfies a dep; where it gates deployed behavior, confirm it's actually deployed). For each: re-derive the task's premise and blocker before working or blocking it — (a) is the deliverable already settled elsewhere (a sibling task / prior resolution)? (b) is the stated blocker actually the only path? The loader's Ready/blocked and a task's stated dependency are claims to check, not facts (81f3 was already settled by 81c7; 81e4's Liquipedia wasn't the only source — Twitch was). Then read-only diagnose the premise the project's way, by value, checking provenance — and consult the source-of-truth doc before interpreting any zero/anomaly (Investigation discipline); then work it to its mode's autonomous ceiling (matrix above); journal the evidence + state. File Backlog tasks for gaps; freeze+capture incidents. Never let one blocker stall the run. Any "why only N rows?" / low-volume question is answered from the producer's own run record FIRST — run count, run-duration metrics, actor-crash/restart history (§ Evidence law, "S's own record") — before it gets classified as a property of the analyzer/query itself. Do this as the first move on the question, not as a check applied after a classification is already drafted: a real run walked past lead_lag_v1 = 70 rows as an analyzer property, with deploy-health reporting the service healthy, and only the run record (7 runs in 20h, a Postgres-restart wedge) showed the true cause.

   Spot-verify delegated first-pass reports. When the first-pass is delegated to subagents, every load-bearing claim in a returned report (counts, file:line, "absent / not wired", "fresh") is re-checked by value by the parent before it is journaled or presented. Subagents have cited non-existent files and columns, concluded "no unbind path" when the deployed code had one, and reported row counts off by ~80× and a stale meta as "fresh".

   GATE — do not start step 5 (working tasks to end state) until step 3 has advanced every journal entry off pending. The ops-context load seeds one ops_journal row per eligible task at pending; the first-pass must move each off pending via ops-client.mjs set-state — from pending the only legal targets are candidate, blocked, or incident-frozen (the server rejects pending → staged-proposal with 400). staged-proposal / applied-pending-confirm follow from candidate (a second set-state once the proposal/application exists). The dominant failure is grabbing the first interesting task and resolving it before the rest are diagnosed — resist it; the cost is an uninformed order and missed cross-task context. Any pending entry means the first-pass isn't done.

4. Present the overview + a suggested review order. Open with the coverage line — "N eligible · N advanced off pending" (they must match; any entry still pending in ops-client.mjs journal --milestone <M>'s output means step 3 isn't finished — go back). Summarize: what's staged, what's blocked and on what, what was filed, incidents frozen, and which tasks are newly_unblocked (name them by id — a dependency just landed and they were stuck last run). Then propose a review order (like design), favoring in this priority:
   1. Incidents / blockers — safety, first eyes.
   2. High-confidence items — cheap, mechanically-verified directed-Operational completions and clear-cut resolutions; bank the certain value before a long session risks not finishing.
   3. Thematic clusters — grouped by theme; within a cluster, Investigation before Operational (a diagnosis often gates whether the authoring change is even right). Get the operator's sign-off on the order. This sign-off is the one authorization point: it also grants phase authorization for the run's audited-path actions (writes, daemon commands, seed applications, filing Backlog follow-ons). After it, execute — do not ask per action or per task. Only the § Stop conditions stop the run.
5. Work every task to its end state — before the walk. For each task in the signed-off order: execute via the audited path, reconcile and capture, file the gap-closing follow-ons, write the task page notes, and set the journal to applied-pending-confirm or blocked (with the filed blocker). Every task must reach one of those two states before step 6 starts. Work long lanes (backfills, seed passes, scoped runs) one command at a time and watch them; while one waits, work the next task — never idle. Every issue met on the way is dug in-session to a proven root cause (§ Universal → every issue is this run's to investigate). Never mark a task Done.
6. Walk = one consolidated confirmation pass per the Interactive walk protocol below: per task, what was done, what was filed, the proposed status; the operator confirms Done per task. No execution and no new investigation inside the walk.

Stop conditions

The run stops and asks only at these; everything else proceeds under the step-4 authorization. Lead with one recommendation (§ Interactive walk protocol).

• An irreversible action — anything the audited path cannot undo or roll back.
• An outcome choice the task does not settle — a choice between materially different outcomes (e.g. "Pairing after map_ended: defect or intended?"). Dig to the proven facts first; ask only for the choice itself.
• A harness / classifier block — follow the procedures.md escalation order: request explicit approval of that action, then an approval-mode change. State the single needed action and why it is blocked.

Not stop conditions: a write, a daemon command, a seed application, filing a follow-on, moving to the next task, or an anomaly (an anomaly is investigated, not asked about). Autonomous (no-operator) runs still only stage.

Interactive walk protocol

Step 6 (the walk) is where this skill is most often mishandled. Codified:

• The walk is a confirmation pass. It starts only after the first-pass (step 3), the order sign-off (step 4) and the work-to-end-state step (step 5). Never walk from a cold board. The walk confirms actions already taken; it executes nothing and opens no new investigation. A walk question that needs a fresh query / DB read / write means step 5 was incomplete: stop walking, finish the work, then resume. Execution-time discovery belongs in step 5 — applying a change is exactly what surfaces the real bugs (a precision bug, a /trades truncation, a config.entities vs config.entity hot-reload mismatch). That's a legitimate output of Operational work: dig it to a proven root cause in-session, file the follow-on, keep going.
• Never walk a dep-blocked task. The loader excludes any task whose hard dep isn't ✅ Done from the walkable set (it lands in dep_blocked, surfaced for re-groom — fix the Depends On or wait for the dep, only ✅ Done satisfies). Do not resurrect one into the walk because it "looks ready"; a 🗂️ Ready or ⏭️ Deferred dep still blocks.
• One consolidated close; the operator confirms Done per task. The close lists, per task: the actions taken (ids, counts, before/after), the follow-ons filed (ids), and the proposed status. Every task keeps its own entry and the operator confirms (or reopens) each Done individually. Batching is the default, not an operator-requested exception; the operator may still ask to go task-by-task, in which case present one entry per message.
• Stop conditions are listed once, in § Stop conditions below. Nothing else stops the run — no stop before each write, none per task, none before filing a follow-on.
• Open each task with context — never cold. Lead with (a) what the task is for and (b) what the read-only diagnosis found; then the decision / recommendation. The operator should be able to engage from your message alone, without re-reading the task body.
• One handle per task. Name a task by its short name + Notion ID once, then use that handle consistently. Don't interchange IDs, ordering numbers, and paraphrased names across turns. An ad-hoc grouping label ("cluster", "the sidecar batch") is a device for the review-order overview only — never refer to it as if it were a task or a unit of work.
• Lead with a recommendation, not a menu. At a stop condition (§ Stop conditions), state a single proposed change + its rationale, then stop and wait — not a menu-style option list ("your options: (a)… (b)… (c)…, which do you want?"). A prose menu pushes the framing and the decision-work back onto the operator and reads as hedging; form a view and state it. Genuinely load-bearing alternatives may be named in prose, but the default shape is "here's the change I need to make and why — authorize?", never "(a)/(b)/(c), your pick." This governs how a choice is framed, not whether you stop; whether to stop is decided by § Stop conditions.
• A harness / permission-guardrail block is not a menu prompt. When the auto-mode classifier or a permission hook blocks an already-authorized action, state the single needed action + exactly why it is blocked, then stop — do not enumerate resolution options ("add a permission rule vs. run it yourself"). Surfacing the block is required; turning it into an option list is the same menu anti-pattern above and offloads a call that is the operator's to make however they choose.
• Background watches must not flood the operator. A Monitor / background watch emits only on a state change or terminal state — never a per-interval heartbeat or "still waiting" line.
• Check a task's current Status immediately before writing to it. Before any write to an existing task page, fetch its current Status in the same turn; never rely on the status seen when it was filed or loaded (it may have reached ✅ Done in between — a filed task is read-only once past Backlog).

Status handling

The operator owns every status transition — including reopening or reverting. You propose; the operator disposes. Never change a task's status on your own reasoning — not to ✅ Done, and just as importantly never reopen or revert a status either (reverting a task unprompted on a re-reading is the same violation as self-closing one).

• Autonomous: change no task's status. Staging is neither "in progress" (it awaits review) nor "in review" in the vocab's sense. The journal is the record; the board stays truthful.
• Interactive: set 🔄 In Progress when you actively open a task to resolve it, cleared on resolution. On operator confirmation, propose the terminal move — never self-mark ✅ Done.
• Skip 👀 In Review for these Types. Its meaning ("PR open / Notion changes formally proposed, awaiting merge-or-lock") doesn't fit an ops task whose resolution is usually filed follow-ons + a task-page note. Keep staged-ness in the journal.

Keep the explicit close turn — do not collapse it. The final "here's the outcome + filed follow-ups; propose Done" turn, and the operator's confirmation of it, is a deliberate review checkpoint — the last place the result and the follow-ons surface before the task is buried. Even when the operator's prior reply was a terse "LGTM" / "good," do not fast-forward it into "task done, on to the next": present the close, let them confirm. The operator wants that turn. The close is the consolidated confirmation (see § Interactive walk protocol): per task, only that task's outcome + its filed follow-ons + proposed status — no next-task preview, no run-level narrative beyond the per-task entries. Each task's entry stays separate so the operator can confirm or reopen it individually. This also excludes arm-state / groom-mechanics narration — e.g. "groom is armed on M15, so this will be picked up on its own." Whether some other task gets auto-dispatched is neither this task's outcome nor one of its filed follow-ons; it is not this session's to assert in a close, the same way arm state is not this session's to pre-flight before filing a task.

When is a task Done? (propose it — the operator confirms.)

• 🔎 Investigation is Done only when the root cause is proven — the mechanism demonstrated by value + the exact code path/line (or config row / state), not merely hypothesized — with any inline fixes made and follow-on tasks filed (each carrying that proven cause, never another "investigate…" task). It does not wait on those follow-ons landing; filing them is the deliverable. The only excuse to stop short of a proven root cause is a genuine external/access blocker (e.g. no read access to the evidence) — recorded as such, not as Done.
• 🔧 Operational is Done when the change is applied and reconcile + capture is verified on prod — not gated on anything downstream — and no step was silently dropped (every part of a multi-step task is closed or filed as a gap-closing follow-on; "accept the gap" is never offered). A reconcile/capture step that cannot be observed until a future event (a live match, a scheduled timer firing) does not block proposing Done: accrete it as an atomic gate item (see § 🔧 Operational) and propose Done. Never keep the task In Progress to wait, and never schedule a self re-check.
• 🧪 Testing (observational/E2E variant) reaches a disposition, not a Done/fail verdict. pass (verified by value, not a degenerate/zero that looks green) or pass-with-caveat → the task is Done. blocked-pending-fix is NOT Done — file the fix task and set this task to 🗂️ Ready + Depends On the fix (it re-runs after). There is no "fail": a surfaced issue becomes a filed fix + a dependency, never a dead end.

Dispositions land on the board, not only the journal. The journal is evidence; the board is truth. Any disposition that changes how a task should be groomed, worked, or run — supersede, re-scope, defer, "don't run as-is" — must be written to the task page (body / Notes + the proposed status) once confirmed. Recording it only in ops_journal is a silent loss: /groom and future workers never read the journal. (Autonomous stages the disposition as a candidate in the journal; the interactive pass lands it on the board.)