Systems Preflight

Start from what the system does now. Find the smallest sound change that survives real use, failure, and recovery.

Ground the review

1. Read the proposal and plan completely.
2. Inspect the code and maintained documentation it would change.
3. Trace the behavior that actually runs: entry points, callers, state reads and writes, authorization, effects, tests, deployment, and recovery.
4. Separate verified facts from proposed behavior, assumptions, and plausible risks.
5. Prefer current code when documentation is stale, and report the discrepancy.

Do not approve architecture from prose alone when the relevant system is available to inspect.

Map the affected system

Name:

• subsystems directly changed;
• indirect readers, writers, clients, operators, deployment surfaces, and recovery paths;
• contracts and invariants each depends on;
• scenario axes that make the change behave differently.

Trace behavioral dependencies, not just imports: identity, authorization, lifecycle, storage, tool availability, packaging, reconnect, backup, restore, and operator control. Distinguish a proven effect from a risk that still needs evidence.

Map state, ownership, and sovereignty

Classify each important state surface as:

• canonical durable fact;
• derived projection or index;
• in-flight execution state;
• bounded cache;
• interface-only representation;
• external or machine-local authority.

For each, name its owner, authorized writers, identity and scope, readers, retention rule, deletion authority, and recovery source. Flag two sources of truth, unclear writers, projections treated as authority, and state that cannot be rebuilt or reconciled.

If the software calls something user-owned, test practical control. Can the owner inspect it, export it in a usable form, verify completeness, move it, replace a provider or model, revoke delegated access, delete primary and derived copies, and recover after administrator or provider loss? A settings label or download button is not proof of ownership.

Find the existing wheels

Search for mechanisms already present in the codebase or platform: identity, authorization, storage, events, jobs, configuration, secrets, retries, observability, migration, packaging, extension points, and recovery.

Reuse a mechanism when its owner and contract fit. A new table, service, protocol, datastore, daemon, credential, privileged helper, or model call must name the concrete mismatch that makes reuse unsafe. Every new mechanism creates another lifecycle, failure mode, and often another security boundary.

Find one sound spine

Ask:

1. What is the smallest durable primitive?
2. What single execution, dispatch, or mutation seam can support the variants?
3. Which intents can be thin adapters or presets?
4. Which differences reflect real authority, location, failure, or lifecycle boundaries and must remain separate?
5. What old path becomes deletable after parity?

Seek one behavioral path, not one giant module. Do not create false unity across unrelated authorities.

Keep unlike concerns separate

Test for conflation between:

• interface affordance and server authorization;
• durable history and execution checkpoints;
• canonical truth and search or index projections;
• server-owned state and user-local files;
• memory scope and tool exposure;
• lifecycle state and process state;
• deterministic policy and model judgment.

Separate them when combining them would blur authority, truth, failure, or recovery.

Bound growth and repeated work

State limits and policies for every growing or repeated process:

• input and output size;
• history and context windows;
• concurrency and pool ownership;
• retries and repair attempts;
• recursion or task depth;
• leases and stale-work recovery;
• retained events, revisions, files, and derived data;
• model calls, evidence, latency, and cost.

Do not invent a hard ceiling because the first implementation needs a constant. Use bounded processing, compaction, backpressure, pagination, streaming, or explicit policy where the underlying system permits it. Report partial work truthfully.

Design failure with the happy path

Trace duplication, stale input, interruption, partial effect, restart, disconnect, invalid model output, dependency outage, permission loss, and rollback.

Require where applicable:

• stable idempotency identity;
• typed failure rather than silent fallback;
• atomic or transactional publication;
• durable cursor, receipt, or checkpoint;
• rebase, replay, reconciliation, or full-reload recovery;
• preserved canonical evidence;
• truthful degraded behavior;
• operator-visible health without leaking sensitive content.

An asynchronous derived process must not silently become a prerequisite for the foreground path.

Apply only the compatibility gates the change touches

For each applicable gate, mark supported, intentionally unsupported, or unresolved. Cite the code, test, or maintained documentation that proves it.

Deployment and operator lifecycle

Check development, source deployment, packaged deployment, local and remote operation, fresh installation, upgrade, rollback, backup, restore, secrets, certificates, storage, migrations, health checks, and continued administration after the original installer disappears.

Do not design an elaborate deployment matrix before one supported deployment works. Do not infer production readiness from a development server.

Tools and external runtimes

Identify where the operation executes: server, desktop, browser, external service, or more than one location. Verify provisioning, versioning, integrity, authentication, authorization, health, updates, packaged availability, and truthful removal when unavailable.

Installed, authenticated, authorized, and healthy are different states. Do not use one as proof of another.

Shared interactive surfaces

For documents, editors, canvases, or other co-creative work, identify the canonical object and mutation seam. Ensure people and agents act on the same state, with bounded live context, attribution, interruption, conflict handling, reconnect, replay, undo, and recovery.

Keep transient interface state in the interface unless the system has a reason to own it. Do not hard-code one extension's behavior into a generic host.

Agent runtime and conversation topology

When changing agents, tools, approvals, events, orchestration, or jobs, test applicable combinations of foreground and background execution; queued, running, paused, awaiting-decision, cancelled, failed, and resumed states; single- and multi-participant rooms; reconnect, duplicate delivery, interruption, and restart.

Define actor identity, scope, authority, tool visibility, approvals, event routing, and cancellation ownership for every distinct path.

Packages and runtime artifacts

For every new package, native dependency, generated artifact, or worker bundle, identify all runtime consumers. Verify build order, dependency resolution, exports, production bundling, containers, packaged applications, and development and test paths. Compiling in a workspace does not prove the artifact ships.

Keep model authority bounded

Use models for semantic judgment, not deterministic filters, authorization, exact state transitions, or obvious routing. Give models bounded untrusted evidence, require structured output where code consumes it, validate identifiers and transitions, preserve zero-result behavior, and prevent invalid output from advancing durable state.

No model output gains authority merely by sounding confident.

Plan migration, recovery, and deletion

Specify:

1. characterization of current behavior;
2. the new seam or path;
3. compatibility while old and new coexist;
4. parity and recovery proof;
5. cutover order;
6. rollback boundary;
7. drift detection where coexistence is unavoidable;
8. deletion of the predecessor.

Avoid dual writes unless ownership, reconciliation, and exit are explicit. Change the sequence when partial migration would create an authorization bypass or unsafe split state.

Calculate behavioral blast radius

List the axes that multiply scenarios: writer, storage zone, authority, lifecycle, client, reconnect state, data shape, provider, or deployment topology. Cover distinct implementations, not every mathematical combination.

Turn “what could regress?” into named deltas: the invariant or journey, trigger, observable failure, exposed scenarios, prevention, detection, recovery, rollback, and test.

Try to disprove the design

Ask:

• Does this create another source of truth?
• Is the mechanism larger than the problem?
• Which assumption could current code invalidate?
• What happens when the provider, model, administrator, credential, or network disappears?
• What evidence would make us abandon the design?
• Can we preserve the valid invariants while deleting more machinery?

Willingness to cancel or revert a mechanism is architectural strength.

Return the preflight

Lead with one verdict:

• Ready
• Ready with named decisions
• Needs architectural reconciliation
• Reframe before implementation

Then include only what helps:

1. Core judgment — strongest idea and central weakness.
2. Current-reality corrections — facts that change the proposal.
3. Affected system — direct and indirect contracts.
4. State, ownership, and sovereignty — canonical facts, writers, custody, recovery, and exit.
5. Proposed spine — primitive, owner, mutation seam, and thin adapters.
6. Bounds and failure — limits, partial effects, degradation, and recovery.
7. Compatibility — only applicable deployment, tool, shared-surface, agent-runtime, and package scenarios.
8. Migration and deletion — cutover, rollback, and what retires.
9. Unresolved decisions — only choices that materially change the design.

Be direct. Do not inflate the review into a replacement specification unless asked.