[Feature / System Name]

[One sentence describing the capability, the user outcome, and the system boundary.]

Status: [draft/proposed/current/reference] Owner: [team or role] Updated: [YYYY-MM-DD]

Decision

[The chosen end state in 2-3 sentences. Name the thing being built, what owns it, and what it replaces or avoids.]

TL;DR

[Meaningful summary. Include the core problem, selected design, main reuse point, quality gate, and expected outcome. Keep it readable as the only thing a busy reviewer reads.]

Why

The problem, value to protect, and evidence behind the design.

Problem

Current Failure

[What is broken, missing, slow, duplicated, or misleading today.]

User Need

[What the user must be able to decide, do, or trust.]

System Need

[What must become reusable, durable, observable, or safer.]

Goals

[Goal 1: concrete outcome.]
[Goal 2: quality or safety property.]
[Goal 3: reuse or operational property.]

Research Inputs

Durable research that informs this spec should be linked as a bounded report. Summarize only the conclusions this spec depends on; do not paste raw source dumps into the spec.

Input	What It Proves	Link
[Research report]	[Decision or requirement grounded by the report.]	`[report link]`
[Code / doc / customer signal]	[Why it matters.]	`[source link]`

What

The product capability, user-facing shape, and contracts.

Requirements

ID	Requirement	Acceptance Signal
R1	[The system MUST / SHOULD / MAY ...]	[Observable proof.]
R2	[The system MUST / SHOULD / MAY ...]	[Observable proof.]

User Experience

Primary View

[Where the user discovers the feature and what is shown first.]

Primary Action

[The main action, decision, or review path.]

Failure State

[How missing data, partial results, or blocked integrations appear.]

Contracts

Contract	Fields / Shape	Owner
[API / workflow / event / artifact]	`[schema or link]`	[module or service]

How

The implementation design, storage, orchestration, integration, and validation model.

Architecture

Owner

[Module/service/workflow that owns the capability.]

Boundaries

[What stays outside this feature and which interfaces are used.]

State

[Where durable state lives and what must not be persisted.]

Flow

1. Trigger[User action, routine, event, or API call.]

2. Plan[Input normalization and policy checks.]

3. Execute[Jobs, tools, services, or collaborators used.]

4. Store[Artifacts, events, database rows, or reusable records.]

5. Present[UI, API, notification, or report output.]

Operating Model

Concern	Model	Acceptance Signal
Trigger	[User action, webhook, timer, or lifecycle event that starts work.]	[Observable proof the trigger fires exactly when intended.]
Concurrency	[How concurrent requests, retries, duplicate events, and active runs are serialized or coalesced.]	[Test proving no duplicate mutation or race.]
Retries	[Retry policy, backoff, terminal failure, and idempotency key strategy.]	[Test proving retry is safe and bounded.]
State Machine	[Primary states and legal transitions.]	[Test or diagram proving invalid transitions are rejected.]

Data Model

Entity	Key Fields	Retention / Notes
[table/entity/document]	`[fields]`	[retention, privacy, ownership]

Observability

Signal	Purpose	Where It Appears
[metric/event/log/artifact]	[Debugging, trust, cost, latency, quality, or audit purpose.]	[UI/API/log/artifact/table.]

Security & Permissions

Action	Required Authority	Audit / Guardrail
[Mutation or external action]	[User, admin, service account, or delegated role scope.]	[Permission check, audit entry, denial behavior.]

Quality Gates

[Gate: no output if required evidence, contract, or check is missing.]
[Gate: partial output must name missing source or blocked capability.]
[Gate: no silent fallback or temporary workaround without an explicit follow-up.]

Test Coverage

Scenario	Expected Outcome	Test Type
[Happy path]	[User-visible or contract-level proof.]	[unit/integration/e2e]
[Missing source / blocked dependency]	[Safe degraded behavior.]	[unit/integration/e2e]
[Complex edge case]	[Correct ordering, dedupe, retry, auth, or state handling.]	[unit/integration/e2e]

Delivery Plan

Phase	Scope	Exit Criteria
1	[Smallest useful slice.]	[Checks and user-visible proof.]
2	[Expansion.]	[Checks and migration or ops proof.]

Rollout / Migration

Step	What Changes	Rollback / Compatibility
[Step]	[Schema, API, UI, routine, workflow, or data backfill.]	[How old state continues to work or how to undo safely.]

Why Not

Rejected alternatives, non-goals, and unresolved decisions.

Alternatives Rejected

Alternative	Why Not	When To Reconsider
[Alternative design]	[Concrete downside, not preference.]	[Future trigger.]

Non-Goals

[Explicitly out of scope.]
[Explicitly out of scope.]

Open Questions

Question	Owner	Decision Needed By
[Question]	[Owner]	[Date or phase]