Spec and EARS Requirements

Purpose

The Project spec is the unit of truth. It is a living document in Linear, not a ticket stretched with ad-hoc notes. This document defines the required sections of a spec and the EARS notation used to write verifiable requirements.

A Project without a complete spec cannot pass Spec Review and therefore cannot reach Prioritized.

Spec Structure

Every Project spec has the following sections. The PM drafts them during Shaping; QA adds the Test Plan; the CPO validates at Spec Review.

Problem

What we observe. Who it impacts. The evidence that supports it.

The problem section is quantitative when possible (metrics, percentages, user segments). It is not a feature request dressed as a problem.

Objective

A single testable sentence. If the Project succeeds, this sentence becomes true.

EARS Requirements

The Acceptance Criteria of the spec, one per sentence. EARS covers three families of requirements (R-13):

1. Functional behavior — what the system does.
2. Tracking events — every user-triggered event the system must emit, with payload, written as Event-driven EARS.
3. State behaviors — empty, error, loading, and offline states with their user-facing copy, written as State-driven or Unwanted-behavior EARS.

Tracking and states live inside the EARS list, not in the Quality Bar. See EARS Notation below.

No-Goals

Explicit list of what this Project does not do. No-goals prevent scope creep during execution and set expectations with stakeholders.

Quality Bar

Open questions and suggestions for the Refining stage (R-16). Three items:

#	Item	What to surface
1	Metric	Open questions about baseline, target, measurement window
2	Performance	Open questions about LCP, TTI (web) or response time (admin)
3	Accessibility	Open questions about WCAG AA scope on user-touched surfaces

The Quality Bar may stay open during Shaping. All three items must be answered before Spec Review (Gate 3). Tracking events and state behaviors are not in the Quality Bar: they are EARS Acceptance Criteria.

Risks

What can go wrong, plus the mitigation for each risk.

Test Plan

Drafted by QA inside the spec during Shaping. Every EARS requirement maps to at least one test case. The Test Plan must be complete before the spec can move to Spec Review.

Milestones

Key dates from Spec Approved to Monitored, used to track the Project against its appetite.

EARS Notation

EARS (Easy Approach to Requirements Syntax) produces requirements that are unambiguous and testable. One sentence, one pattern, one test case.

If a requirement cannot be tested, it is not a good EARS.

The Five Patterns

Pattern	Template	When to use
Ubiquitous	The <system> shall <response>.	Always-on behavior
Event-driven	When <trigger>, the <system> shall <response>.	Reaction to a discrete event
State-driven	While <state>, the <system> shall <response>.	Behavior active under a condition
Unwanted behavior	If <condition>, then the <system> shall <response>.	Errors and edge cases
Optional feature	Where <feature on>, the <system> shall <response>.	Feature flags, plan gating

Writing Good EARS

• One requirement per sentence. No "and" chains.
• Name the system precisely (storefront, reader, admin panel), not "the system."
• The response must be observable. If QA cannot write a test, rewrite the requirement.
• Identify each requirement with a short code (E1, UB1, O1) so Issues and test cases can reference it.

EARS for Tracking Events

Each tracking event is one Event-driven EARS. The "response" names the event and lists its payload fields. Tracking ACs do not live in the Quality Bar.

Examples:

• When the reader marks a tag as public, the reader app shall emit tag_made_public with {tag_id, user_id, tenant_id}.
• When the storefront completes a checkout, the storefront shall emit checkout_completed with {order_id, total_cents, currency, tenant_id}.

EARS for State Behaviors

Each state (empty, error, loading, offline) is one State-driven or Unwanted-behavior EARS, with the user-facing copy named. State ACs do not live in the Quality Bar.

Examples:

• While the library has no products, the storefront shall display "Aún no tenés contenido en tu biblioteca." with a primary action to explore the catalog.
• If the reader loses connectivity while reading, the reader app shall display the offline banner "Modo offline. Tus marcas se sincronizarán al volver a conectarte." and persist annotations locally.
• While a search request is in flight, the storefront shall display the skeleton loader for the results grid.

Review Checklist

Before Spec Review, the PM and the CPO confirm:

• Every requirement fits one of the five patterns.
• Every requirement is verifiable.
• Every requirement has at least one test case in the Test Plan.
• No requirement encodes an implementation detail (that belongs in Issues).

Who Writes What

Section	Drafted by	Validated at
Problem, Objective, No-Goals, Risks	PM	Spec Review with CPO
EARS Requirements	PM (with QA input on tracking events and state behaviors)	Spec Review with CPO
Quality Bar (open questions)	PM (raised in Shaping, answered in Refining)	Spec Review with CPO
Test Plan	QA	Completed before Spec Review
Milestones	PM	Spec Review with CPO

Related Documentation

• Product Framework Overview
• Project Lifecycle — when each section is written and when checkpoints are evaluated.
• QA Collaboration — how QA participates in shaping and Test Plan authoring.
• Product Principles — the Quality Bar in depth.