/light-system-design

name: light-system-design
description: >-
  Design or modernize a software system from an evidence-backed current-state
  inventory through quality attributes, architecture options, API and schema
  contracts, migration/rollback plans, ADRs, and verification. Use for
  greenfield or existing monoliths, modular monoliths, services, system/API/
  database design, schema migration review, data-flow reliability, tenant/PII
  controls, or architecture evolution. Existing systems stay read-only until
  the user selects an option and authorizes exact mutations. Unknown facts stay
  UNKNOWN. This is an off-DAG engineering skill: do not emit findings or invent
  STAGE_GATES, ROUTES, stages, or back-edges.

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`](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`](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

| Situation | Mode | |---|---| | New system with no implementation | greenfield requirements and option design | | Existing repository/system | read-only intake, then current-state inventory | | Existing monolith or services changing gradually | modernization with compatibility and rollback | | API-only change | contract and consumer compatibility branch | | Schema-only change | dialect/version/context-specific migration branch | | User supplied a completed package | review and evidence verification |

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`](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 t