Systems Check

Read the system before the proposal

Read the plan fully, then go inspect the code and docs it would touch. Trace what actually executes — entry points, callers, state, authorization, deployment, recovery — and separate confirmed fact from hopeful assumption. When the docs and the code disagree, trust the code and flag the gap out loud.

Map who touches what

List every subsystem the change touches directly, plus the readers, writers, operators, and recovery paths it touches indirectly. Track behavioral dependencies — identity, lifecycle, storage, packaging — not just a list of imports.

Map ownership and who really controls the data

Classify each piece of state — canonical fact, derived index, cache, in-flight work — and name its owner, its authorized writers, and how it recovers after a loss. Watch for two systems that both claim to be the source of truth. Then test any claimed "ownership" for real: can the owner export the data, move it, revoke access, delete every copy, and recover if a provider disappears? A settings label that says your data proves nothing by itself.

Reuse the wheel before building a new one

Search for identity, storage, retry, and observability mechanisms already in the codebase before adding new ones. A new datastore, daemon, or credential has to name the concrete way the existing mechanism falls short — every addition is another lifecycle and another failure mode to carry.

Find one sound spine

Look for the smallest durable primitive and the single mutation path that can support every real variant, keeping thin adapters on top instead of repeated logic underneath. Split the path only where authority, safety, or lifecycle genuinely differ — not merely because the code happens to contain several functions.

Design for failure alongside the happy path

Trace repeated delivery, stale input, restarts, and dependency outages on the same day you trace the success case. Require stable retry identity, typed failures instead of silent fallbacks, and a durable checkpoint that survives a crash. A background process should never quietly become a prerequisite for the main path.

Bound growth before it becomes a limit

State real limits and policies for anything that can grow without end — history size, concurrency, retries, retained files. Do not invent an arbitrary ceiling just because the first version needs one round number; prefer pagination, streaming, and backpressure, and report partial results honestly.

Plan the exit before the migration

Specify how the old and new paths coexist, how parity gets proven, where the rollback boundary sits, and when the predecessor actually gets deleted. Avoid dual writes unless ownership and reconciliation are explicit — a half-finished migration should never open an authorization gap.