preflight

name	preflight
description	Pre-work ritual — spec, search, and (when needed) a 1-page implementation design doc before touching code

Before starting work on issue $ARGUMENTS, execute these phases in order. Do NOT write code until all gates are cleared.

Phase 1 — Mechanical context gathering

1. Run pnpm exec totem spec $ARGUMENTS to generate the implementation spec from the issue body. Output lands in .totem/specs/<issue>.md.
2. Call mcp__totem-dev__search_knowledge with a query describing the changes you're about to make. If the issue touches a specific system (hooks, orchestrator, compiler, extract pipeline, store layer, MCP server), ALSO query mcp__totem-strategy__search_knowledge for relevant ADRs and proposals.
3. Summarize in 3-5 bullets: what the spec says, which lessons are relevant, and any constraints or traps surfaced by the knowledge queries.

If totem spec fails, report the error and stop — do not proceed to Phase 2.

Phase 2 — Scope triage (decide if Phase 3 is needed)

Skip Phase 3 if this is a tactical change. Tactical means ALL of:

• Pure bug fix, wording change, or existing-test tightening
• No new types or required fields on existing types
• No new state containers (maps, sets, module-level variables, singletons)
• No new failure modes or classes of error
• No new cross-cutting concerns (logging, telemetry, caching, auth)
• Touches ≤3 files in a single architectural layer

Draft the design doc (Phase 3) if ANY of:

• Adds a new type, interface, or required field
• Adds a new state container or changes state ownership/lifecycle
• Introduces a new failure mode or changes existing error surface (hard error → warning, sync → async, blocking → non-blocking)
• Crosses architectural boundaries (core → cli, cli → mcp, etc.)
• Touches >3 files OR introduces a new cross-cutting concern
• Documents a new config field, new public API method, or new agent-facing tool surface (regardless of whether the doc is in the same PR as the implementation, and regardless of whether the implementation is yours or someone else's)

When in doubt, draft the doc. The cost of 10 minutes of design writing is always lower than the cost of a multi-round bot review cycle.

Why docs-that-describe-features count as architectural. A wiki page that describes a new config field has the same data-model verification requirement as the code that implements it — you can write incorrect documentation about a real feature surface just as easily as you can write incorrect code. If you're authoring docs for a feature you didn't just build (or built more than a session ago), READ THE SCHEMA before the prose. The Phase 3 data-model section will force you to enumerate the config fields, which is exactly the work that catches "I remember this feature as automatic but the schema says opt-in" errors before they ship to users. The mmnto-ai/totem#1297 docs PR cycle is the load-bearing example.

State your triage decision explicitly: "Tactical — skipping Phase 3" or "Architectural — drafting design doc."

Tactical path — no approval gate. If tactical, proceed directly to implementation after Phase 2 (triage) completes. The Phase 4 approval gate below only applies when Phase 3 was drafted, because the gate exists to catch architectural mistakes before code is written — there's nothing architectural to review for a tactical change. The user's normal PR-approval and merge-approval rules still apply to the finished code.

Architectural path — continue to Phase 3. Draft the design doc, then stop at the Phase 4 approval gate before writing any code.

Phase 3 — Implementation design doc (REQUIRED for architectural changes before code; skipped for tactical)

Append a new ## Implementation Design section to the spec file at .totem/specs/<issue>.md. The section MUST cover all six subsections below. Keep it tight — the whole design section should fit in ~1 page.

Scope (2 sentences)

What this implementation will do, and what it explicitly will NOT do. Negative scope is load-bearing — it prevents scope creep during review.

Data model deltas

List every new type, new field on an existing type, and every new state container (map/set/module variable). For each:

• What it holds
• Who writes it
• Who reads it
• What invariants hold (required vs optional, bounded vs unbounded, who guarantees the invariant)

Explicitly call out any "reserved keys" or sentinel values — those are collision hazards. Prefer separate fields over reserved keys.

State lifecycle

For each new piece of state, identify:

• Scope: per-request / per-session / server-lifetime / persistent
• Lifetime: when created, when mutated, when cleared, when destroyed
• Ownership: which function/module owns mutation

Call out any state that crosses lifecycle boundaries (e.g., a session-level flag consumed by a per-request operation). Those are the most common source of "one-shot flag consumed before its work succeeded" bugs.

Failure modes

A table. For each failure point:

Failure	Category	Agent-facing surface	Recovery
	init / runtime / transient / permanent	hard error / isError / warning / silent degradation	how state returns to healthy

Be exhaustive. Every place the code can throw, return null, return an empty result, or silently succeed with degraded output is a row. If a row has "silent degradation" in the surface column, justify it against Tenet 4 (Fail Loud, Never Drift) or change the design.

Invariants to lock in via tests

NOT test names. The guarantees you're testing. Example:

• "linked store named 'primary' must not collide with primary failure slot"
• "init-time warnings survive any reconnect cycle untouched"
• "one-shot first-query flags are consumed only after successful work"

These become the test assertions. If you can't articulate the invariant in English, you probably don't understand what you're testing yet.

Open questions

Anything that needs user judgment before coding starts. Format:

• Question:
• Options:
• Recommendation:

Phase 4 — Approval gate (architectural path only)

This phase applies ONLY when Phase 3 was drafted. For tactical changes that skipped Phase 3, there is no gate — see Phase 2.

After drafting Phase 3, STOP and output:

Design doc drafted at .totem/specs/<issue>.md. Please review the Implementation Design section and approve before I start coding. Open questions: .

Do NOT write code until the user explicitly approves the design. If the user wants changes, update the doc and re-stop for approval.

Controller-not-implementer (ADR-063): protect your own decision-making by surfacing architectural questions BEFORE they become bot review findings. A 10-minute design review with the user is strictly cheaper than a 7-round bot review cycle on the PR.