The Specy system-requirement metamodel defines the vocabulary you use to state what the system shall do, as testable obligations that sit between the PRD and the domain model. It is organized in six layers: an EARS Foundations layer that constrains natural language into an unambiguous structure, an EARS Patterns layer of six sentence templates covering every requirement type, a Requirements & Sets layer that names, prioritizes, and groups obligations, a Non-Functional Requirements layer that expresses quality bars in the same syntax, a Traceability layer that links requirements up to the PRD and down to the domain model, and a Verification Loops layer that puts requirements to work governing build, check, and observe.

Each layer below gives a one-sentence definition of every concept and a link to its detailed page. System requirements are the parent layer of the provenance chain — the domain model references them via satisfies, and they reference the PRD via source.

The full, authoritative specification is SYSTEM-REQ-METAMODEL.md in the specy-ai/skills repository.

EARS Foundations

This layer explains why requirements use a constrained syntax at all, and the small ruleset that makes a sentence an EARS requirement.

Eight Deficiencies of Natural Language — the failure modes EARS exists to prevent: ambiguity, vagueness, complexity, omission, duplication, wordiness, inappropriate implementation, and untestability. See EARS Fundamentals.

The EARS Ruleset — the canonical structure every requirement conforms to: optional preconditions and trigger, exactly one system name, one or more shall responses, always in temporal order. See EARS Fundamentals.

The Four Keywords — While (precondition), When (event trigger), If/then (unwanted condition), and Where (optional feature) — the words that make preconditions, triggers, and error handling explicit. See EARS Fundamentals.

The Single-Sentence Rule — each requirement is exactly one sentence; anything needing more must decompose into separate requirements or a decision table. See EARS Fundamentals.

EARS Patterns

This layer is the six sentence templates, each keyed by its keyword, that together cover the full spectrum of requirement types.

Ubiquitous — an always-active, unconditional requirement with no keyword; for fundamental properties and invariants that hold regardless of state or event. See EARS Patterns.

State-Driven (While) — a requirement active only while a state or condition holds; for mode-dependent behavior and state-scoped invariants. See EARS Patterns.

Event-Driven (When) — a requirement triggered by a specific event or action; for commands, operations, and event-driven transitions. See EARS Patterns.

Unwanted (If-Then) — a requirement handling an error or failure; the pattern that makes the most common and costly category of missing requirements — unhandled error conditions — visible. See EARS Patterns.

Optional (Where) — a requirement applying only to system variants that include a specific capability; for product-line features and configurable modules. See EARS Patterns.

Complex — a requirement combining keywords in strict temporal order (While → When/If/Where); for guarded triggers and conditional error handling. See EARS Patterns.

Requirements & Sets

This layer names the obligation itself, weights it, relates it to its neighbors, and groups it into a coherent unit.

Requirement — a named EARS statement declaring a system obligation, with a stable id, the statement, its pattern, a rationale, and a priority. See Requirements & Sets.

Priority (MoSCoW) — the domain-expert weight on each requirement: must (non-negotiable), should (important, non-blocking), could (desirable), wont (explicitly out of scope). See Requirements & Sets.

Requirement Relations — the links between requirements: depends-on (logical prerequisite), conflicts-with (documented tension), and decomposed-into (an organization-level obligation split across contexts). See Requirements & Sets.

Requirement Set — a group of related requirements aligned with a capability or module, scoped to a bounded context, optionally declaring the prd-source it was derived from. See Requirements & Sets.

Set Relations — how sets connect to the rest of the model: scoped to a bounded context and optionally mapped to the module whose interface realizes them. See Requirements & Sets.

Non-Functional Requirements

This layer constrains how well the system performs — expressed in the same EARS syntax, with no separate grammar.

NFRs as EARS — a non-functional requirement is a requirement: a latency budget is event-driven, an availability SLA is ubiquitous, a degraded mode is state-driven; the metric lives in the statement. See Non-functional Requirements.

NFR Categories & Domain Anchors — the classification of NFRs (performance, reliability, security, operability, scalability, compliance, resilience) by the domain element they anchor to and their natural scope. See Non-functional Requirements.

Discovery Heuristic — the systematic per-operation, per-entity, per-service, per-context, and per-organization questions that surface frequently omitted NFRs. See Non-functional Requirements.

Cross-Cutting NFRs — requirements that cannot be scoped to a single context (an availability SLA, PCI-DSS, GDPR erasure); scoped to the organization and decomposed into derived context-level obligations. See Non-functional Requirements.

Traceability

This layer connects requirements upward to the PRD and downward to the domain model, and turns those links into analyses.

The Traceability Bridge — requirements are the parent layer; domain elements reference them via satisfies, making coverage and orphan analysis a traversal of those lists. See Traceability.

Coverage & Orphan Analysis — which must/should requirements have no satisfying domain element (a gap), and which domain elements satisfy no requirement (over-engineering or a missing requirement). See Coverage Analysis and Orphan Analysis.

Conflict Detection — requirements linked by conflicts-with that cannot both be fully satisfied, whose resolution strategy must be documented. See Traceability.

The Upstream PRD Bridge — the source field linking each requirement back to the PRD feature, story, criterion, constraint, or goal that originated it, completing the Product → Requirement → Domain → Code provenance chain. See Traceability.

Verification Loops

This layer puts requirements to work: they govern the model rather than replace it, plugging into Specy’s three loops.

The Three Loops — Build (intent → code), Check (code → intent), and Observe (runtime → intent); the cycle requirements feed and are verified against. See Verification Loops.

Build — requirements are the input specification; the builder produces a domain model whose elements declare satisfies references back to requirement IDs. See Verification Loops.

Check — the checker traverses satisfies lists and fails when any requirement ID is covered by no domain element. See Verification Loops.

Observe — event-driven and unwanted requirements are watched at runtime; missing events or unhandled errors signal drift between intent and behavior. See Verification Loops.

Governance, not Replacement — requirements do not replace the domain model; they declare why each element must exist and what obligation it fulfills. See Verification Loops.