Light System Design

System design lifecycle

Own system boundaries, runtime interfaces, operational data stores, system migrations, and architecture decisions. Do not equate a diagram, SQL file, or OpenAPI document with a working, safe, or scalable system.

Read references/system-design-resource-map.md before any existing-system task. It defines the lifecycle, artifact contract, decision stop, evidence states, access tiers, and cross-skill ownership. Read references.md only for the database/API/reliability branch that applies to the selected system.

Non-negotiable boundary

1. Treat repository, configuration, schema, API, dependency, and deployment intake as read-only access. It is not authorization to rewrite them.
2. Preserve absent facts as UNKNOWN. Do not infer traffic, SLOs, consistency, budget, compliance, migration windows, or team capability from the phrase “system design.”
3. Present at least a recommendation, a viable alternative, and explicit rejection/exit conditions. Stop before choosing the database, topology, compatibility policy, or migration strategy for the user.
4. Bind any later mutation to a user-selected option and exact authorized action IDs. Keep before/after locators, SHA-256, verification, and rollback.
5. Never mutate a production database or configuration. Apply only to a disposable environment explicitly placed in scope; otherwise deliver a reviewed plan and scripts.
6. Describe schema_lint.py as a lexical heuristic. It is not a SQL parser, query planner, lock simulator, schema diff engine, or zero-downtime proof.
7. Keep VERIFIED for checks that actually ran and retain their command, return code, locator, and hash. Use PLANNED, UNKNOWN, or UNAVAILABLE otherwise.
8. Keep this skill off the research DAG. Emit no light.findings.v1; add no STAGE_GATES, ROUTES, stage number, or back-edge; do not attach _shared.

Choose the mode

Phase 1 — Intake and protection

Capture or preserve as UNKNOWN:

• users, business goal, critical use cases, data classification;
• load range, latency, availability, durability, and consistency targets;
• team/operations capability, budget, deployment environment, compliance, and migration window;
• topology: greenfield, monolith, modular monolith, or services;
• components, owners, interfaces, stores, dependencies, write paths, trust boundaries, failure modes, versions, source locators, and freshness;
• existing clients, schema history, deployment/runtime constraints, and compatibility promises.

For an existing system, create an intake manifest from templates/system-intake.template.json and run:

python scripts/architecture_lifecycle.py intake <root> \
  --manifest <system-intake.json> --out <evidence-dir>

Keep --out outside the source root. Read all emitted artifacts and verify source_unchanged=true.

Phase 2 — Requirements and current state

Produce:

• context and quality-attribute scenarios with a measurable stimulus, environment, response, and target or UNKNOWN;
• capacity estimates for request rate, storage growth, fan-out, latency budget, and any dominant resource; if unknown, write UNKNOWN plus the measurement plan rather than inventing numbers;
• current-state → target-state mapping with explicit gaps. For greenfield, current state can be none, but the gap list still records missing evidence;
• architecture fitness functions: observable signals, thresholds, verification command/probe, and evidence state. A quality attribute without a fitness function is still only prose;
• a component/interface/store inventory with owner and fact provenance;
• synchronous/asynchronous data flows, transaction boundaries, delivery semantics, idempotency/deduplication, backpressure, timeout/retry, and failure handling;
• risk, assumption, unknown, and stale-fact registers.

Do not silently convert a code search into an architecture truth. Mark each fact as declared, observed, inferred, or unknown.

Phase 3 — Options and decision stop

Present at least:

1. a recommended option with reasons;
2. a viable alternative;
3. conditions under which each should not be used;
4. cost/complexity, migration risk, compatibility window, rollback, operations, and exit criteria;
5. unresolved facts that could reverse the recommendation.

Then stop. Ask the user to select an option and authorize exact action IDs. Do not prewrite the user's choice or generate the chosen schema/API/migration/ ADR as if approval already existed.

Before presenting the decision, validate that requirements, capacity estimates, current/target state, fitness functions, at least two genuinely different options, hard-constraint and fitness evidence, tradeoffs, rejection conditions, reversal costs, and migration/deprecation stance are present:

python scripts/design_readiness.py --input templates/design-readiness.example.json \
  --as-of 2026-07-05

In proposal, PASS means only ready_for_user_decision=true; it never writes the selection, and the report emits a canonical option_packet_sha256 for each option. In authorized, the selection must be paired with a light.system-design.v2.authorization whose option digest still matches, whose approved action IDs are a subset of that option, whose target is explicitly disposable, whose rollback cannot be waived, and whose date is not later than --as-of. The walking skeleton (entry/core_path/state_boundary/observable_result/failure_probe/verification/action_ids) may contain only approved actions before ready_for_implementation=true.

For each option, state whether migration/deprecation is applicable. If it is applicable, the option must be replacement-first. Consumer inventory is a list of stable consumer/interface IDs, owners, usage status, evidence state, evidence locator/date, or an explicit measurement plan. Telemetry is a structured metric/source/evidence record. Rollout is a sequence of phases with entry, exit, and rollback conditions; rollback has a trigger, action, and verification. A deprecation compatibility window has start, end, and removal conditions. Plain strings do not satisfy these fields. If migration is not applicable, record why; do not leave it blank.

Use templates/decision-authorization.template.json after the user responds. Copy the selected digest emitted by design_readiness.py; a changed requirement, state model, fitness function, or selected option changes that digest and requires fresh authorization.

Phase 4 — Build the architecture package

After authorization, produce only the selected scope:

• context and quality attributes;
• component/boundary and data-flow views;
• API/event contracts and consumer compatibility policy;
• schema and current-to-target change plan;
• rollout, backfill, rollback, and deprecation plan;
• ADR with alternatives and consequences;
• security/privacy design controls and items for specialist review;
• verification plan and delivery evidence.

Use templates/architecture-package.template.md. Treat bundled SQL/OpenAPI files as dialect/version-labeled examples, never as production defaults.