spec-format

context	fork
name	spec-format
description	SPEC format for structured requirements, acceptance criteria, and technical specifications. Use when the user asks about requirements, acceptance criteria, or technical specs. Triggers: spec, requirements, specification, acceptance criteria, EARS, user story.
lang	["en"]
level	2
triggers	["spec","requirements","specification","acceptance criteria","EARS","user story"]
agents	["architect"]
tokens	~3K
category	workflow
platforms	["claude-code","gemini-cli","codex-cli","cursor"]
source_hash	022945ba
whenNotToUse	Do not apply when the request is a quick exploratory spike, a one-liner fix, or when the stakeholder explicitly wants to prototype first and specify later. EARS overhead exceeds value for tasks under 30 minutes of implementation.

SPEC Format: Structured Requirements & Specifications

Contents

• When This Skill Applies
• Core Guidance
• Feature: [Name]
• Quick Reference
• Workflow Checklist
• Human Checkpoints
• Freedom Levels

When This Skill Applies

• Writing requirements for new features or systems
• Defining acceptance criteria for user stories
• Creating technical specifications for implementation
• Translating business requirements into testable statements
• Reviewing and improving requirement quality
• Communicating design intent to development teams

Core Guidance

1. EARS Requirement Templates

EARS (Easy Approach to Requirements Syntax) provides five patterns for unambiguous, testable requirements.

Ubiquitous Requirements

Always-active behavior with no conditions or triggers.

The [system] shall [action].

Examples:

• The API shall respond within 200ms for all GET requests.
• The system shall encrypt all data at rest using AES-256.
• The application shall support UTF-8 encoding for all text fields.

Event-Driven Requirements

Behavior triggered by a specific event or action.

When [trigger event], the [system] shall [action].

Examples:

• When a user submits the login form, the system shall validate credentials against the auth service.
• When a payment fails, the system shall retry the transaction up to 3 times with exponential backoff.
• When a file upload completes, the system shall generate a thumbnail and update the media library.

State-Driven Requirements

Behavior that applies only while a specific condition holds.

While [state/condition], the [system] shall [action].

Examples:

• While the system is in maintenance mode, the API shall return 503 for all non-health-check endpoints.
• While the user session is active, the system shall refresh the auth token 5 minutes before expiry.
• While offline, the application shall queue mutations and sync when connectivity is restored.

Optional (Feature-Gated) Requirements

Behavior that applies only when a feature or configuration is enabled.

Where [feature/configuration], the [system] shall [action].

Examples:

• Where two-factor authentication is enabled, the system shall require a TOTP code after password verification.
• Where the premium tier is active, the API shall allow up to 10,000 requests per hour.
• Where dark mode is selected, the UI shall apply the dark color scheme to all components.

Unwanted Behavior (Negative) Requirements

Behavior the system must prevent or handle.

If [unwanted condition], the [system] shall [response].

Examples:

• If a SQL injection pattern is detected in input, the system shall reject the request and log the attempt.
• If memory usage exceeds 90%, the system shall trigger garbage collection and alert the operations team.
• If an API response exceeds 30 seconds, the system shall timeout and return a 504 Gateway Timeout.

2. Complex (Combined) Requirements

Combine patterns for nuanced behavior specifications.

State + Event:

While [state], when [trigger], the [system] shall [action].

• While the user is authenticated, when they access a protected resource, the system shall verify their role permissions.

Feature + Event:

Where [feature], when [trigger], the [system] shall [action].

• Where email notifications are enabled, when an order ships, the system shall send a shipping confirmation email.

State + Feature + Event:

While [state], where [feature], when [trigger], the [system] shall [action].

• While the system is in production mode, where rate limiting is enabled, when a client exceeds 100 requests/minute, the system shall return 429 Too Many Requests.

3. Acceptance Criteria Format

Use the Given-When-Then pattern alongside EARS for testable criteria.

GIVEN [precondition/context]
WHEN  [action/trigger]
THEN  [expected outcome]
AND   [additional outcome]

Example:

Feature: User Registration

GIVEN a visitor on the registration page
WHEN  they submit a valid email and password (min 8 chars, 1 uppercase, 1 number)
THEN  the system shall create a new user account
AND   send a verification email within 30 seconds
AND   redirect to the email verification pending page

GIVEN a visitor on the registration page
WHEN  they submit an email that already exists
THEN  the system shall display "An account with this email already exists"
AND   not reveal whether the email is registered (timing-safe response)

4. Technical Specification Template

## Feature: [Name]

### Overview
[1-2 sentence description of the feature and its purpose]

### Requirements

#### Functional
- REQ-001: [Ubiquitous] The system shall ...
- REQ-002: [Event] When ..., the system shall ...
- REQ-003: [State] While ..., the system shall ...

#### Non-Functional
- NFR-001: [Performance] The API shall respond within [X]ms at p95
- NFR-002: [Security] The system shall [security requirement]
- NFR-003: [Availability] The service shall maintain [X]% uptime

### Acceptance Criteria
- AC-001: GIVEN ... WHEN ... THEN ...
- AC-002: GIVEN ... WHEN ... THEN ...

### Technical Design
- Architecture: [approach]
- Data model: [entities and relationships]
- API contracts: [endpoints and schemas]
- Dependencies: [external services, libraries]

### Constraints & Assumptions
- [Constraint or assumption with rationale]

### Out of Scope
- [Explicitly excluded items]

5. Requirement Quality Checklist

Every requirement should be:

Quality	Test	Bad Example	Good Example
Atomic	One behavior per statement	"The system shall validate and store data"	"The system shall validate input" + "The system shall store validated data"
Testable	Can write a pass/fail test	"The system shall be fast"	"The API shall respond within 200ms at p95"
Unambiguous	One interpretation only	"The system shall handle large files"	"The system shall accept files up to 100MB"
Complete	Covers all conditions	"When login fails, show error"	"When login fails, the system shall display the error reason and increment the failed attempt counter"
Consistent	No contradictions	Conflicting timeout values across specs	Single source of truth for all thresholds
Traceable	Links to source need	Orphan requirement	"REQ-042 (from: USER-STORY-15)"

6. Priority Classification

Priority	Label	SLA	Decision Rule
P0	Critical	Must have for launch	System cannot function without it
P1	High	Must have for release	Core user journey depends on it
P2	Medium	Should have	Improves experience significantly
P3	Low	Nice to have	Enhancement, can defer

Quick Reference

EARS Patterns:

Ubiquitous:  The [system] shall [action]
Event:       When [trigger], the [system] shall [action]
State:       While [condition], the [system] shall [action]
Optional:    Where [feature], the [system] shall [action]
Negative:    If [unwanted], the [system] shall [response]
Combined:    While + When, Where + When, etc.

Acceptance Criteria: GIVEN [context] WHEN [action] THEN [outcome]

Quality Gates: Atomic, Testable, Unambiguous, Complete, Consistent, Traceable

Workflow Checklist

Copy this checklist and track progress:

Progress:
- [ ] Step 1: Gather business requirements and user stories
- [ ] Step 2: Select EARS pattern(s) for each requirement
- [ ] Step 3: Write requirements using EARS templates
- [ ] Step 4: Write acceptance criteria (Given-When-Then)
- [ ] Step 5: Apply quality checklist (atomic, testable, unambiguous, complete)
- [ ] Step 6: Classify priority (P0-P3)
- [ ] Step 7: Review with stakeholders

Human Checkpoints

Checkpoint 1: 요구사항 의도 검토 (After Step 3)

Context: EARS 패턴을 적용하여 요구사항 문장이 작성된 시점. 문법은 맞더라도 원래 비즈니스 의도를 정확히 반영하지 못할 수 있어 검토가 필요하다. Ask: "작성된 요구사항이 원래 의도를 정확히 표현하고 있나요?" Options:

1. Approve — 요구사항을 승인하고 인수 기준 작성으로 진행
2. Revise wording — 표현을 수정하고 재검토 Default: 1 (EARS 패턴이 올바르게 적용된 경우) Skippable: No — 승인 또는 수정을 명시적으로 결정해야 함 Freedom: LOW

Checkpoint 2: 인수 기준 완성도 확인 (After Step 4)

Context: Given-When-Then 형식으로 인수 기준이 작성된 시점. 누락된 시나리오(엣지 케이스, 오류 케이스)가 있으면 나중에 테스트 커버리지 갭이 발생한다. Ask: "인수 기준이 테스트 가능하고 모든 시나리오를 포함하고 있나요?" Options:

1. Proceed — 완성도를 확인하고 우선순위 분류로 진행
2. Add missing scenarios — 누락된 시나리오를 추가한 후 재검토 Default: 1 (모든 주요 경로와 오류 케이스가 작성된 경우) Skippable: No — 진행 또는 추가 작성을 명시적으로 결정해야 함 Freedom: LOW

Checkpoint 3: 우선순위 분류 합의 (After Step 6)

Context: P0-P3 프레임워크로 각 요구사항의 우선순위가 분류된 시점. 우선순위는 비즈니스 컨텍스트에 따라 달라지므로 이해관계자 합의가 필요하다. Ask: "우선순위 분류(P0-P3)가 현재 비즈니스 상황에 맞게 결정되었나요?" Options:

1. Confirm priorities — 우선순위를 확정하고 이해관계자 검토로 진행
2. Reprioritize — 일부 항목의 우선순위를 조정하고 재확인
3. Escalate decision — 비즈니스 오너에게 결정을 위임 Default: 1 (팀 내 합의가 이루어진 경우) Skippable: Yes (skip 시 Confirm priorities로 처리) Freedom: MEDIUM

Checkpoint 4: 이해관계자 최종 승인 (After Step 7)

Context: 요구사항·인수 기준·우선순위가 모두 완성되어 이해관계자 검토를 마친 시점. 승인 없이 구현을 시작하면 나중에 재작업이 발생할 수 있다. Ask: "이해관계자가 현재 스펙 문서를 최종 승인했나요?" Options:

1. Approved — 승인 완료, 구현 단계로 이관
2. Changes requested — 피드백 반영 후 재검토 요청 Default: 1 (검토 미팅 후 명시적 승인을 받은 경우) Skippable: No — 승인 또는 변경 요청을 명시적으로 기록해야 함 Freedom: LOW

Freedom Levels

Step	Freedom	Guidance
Gather requirements	HIGH	Elicitation approach depends on context
Select EARS pattern	MEDIUM	5 patterns defined, but choosing the right one requires judgment
Write requirements	LOW	Must follow EARS template syntax exactly
Write acceptance criteria	LOW	Given-When-Then format mandatory
Quality checklist	LOW	All 6 quality attributes must be verified
Classify priority	MEDIUM	P0-P3 framework defined, but business context drives decisions
Stakeholder review	HIGH	Review format and cadence are flexible

Rationalizations

The following table captures common excuses agents make to skip the rigor of this skill, paired with factual rebuttals.

Excuse	Rebuttal
"specs slow down development"	unspec'd features cost 3x to fix post-launch; spec is the cheap refactor
"we are agile, specs are waterfall"	agile specs are lightweight and iterative — SPEC format is one page, not a requirements doc
"acceptance criteria are obvious"	if obvious, they are easy to write; if hard to write, they were not obvious
"the ticket description is enough"	ticket descriptions drift; SPEC is the durable contract between PM and engineering
"I will write the spec after coding"	post-hoc specs are documentation, not requirements — the whole value is up-front alignment

Common Rationalizations

Rationalization	Why it's wrong	What to do instead
"The ticket description is clear enough, no need for EARS"	Ticket descriptions drift and allow multiple interpretations; EARS produces a single unambiguous statement that is testable by definition	Convert the ticket description into at least one EARS sentence before implementation starts
"We are agile so formal specs slow us down"	Lightweight one-page specs prevent rework; the cost of writing EARS is always less than the cost of building the wrong thing	Use the EARS templates for user-facing requirements only; skip internal helper functions
"Acceptance criteria are obvious from the feature name"	If they were obvious, stakeholders would not argue about whether the feature is done; the arguments happen because nothing was written down	Write one Given-When-Then per happy path and one per known error path before coding
"I will add the spec after the prototype is approved"	Post-hoc specs encode the prototype's bugs as requirements; requirements written before implementation constrain the design	Write requirements for the approved scope, then implement — even a one-day prototype deserves a scope statement
"The three-tier boundary (Always/Ask first/Never) is overkill for this change"	Undocumented tier boundaries produce scope creep silently; every "small" unspecified change that shipped too far has no written boundary to point to	Add at minimum an "Out of Scope" section listing two or three explicit exclusions

Red Flags

• Writing requirements in natural language without any EARS pattern applied
• Acceptance criteria using words like "fast", "easy", "good" without measurable thresholds
• A spec document that contains no Given-When-Then blocks for error scenarios
• Requirements that were written after the implementation was already merged
• Priority classifications made without stakeholder input or documented rationale
• Any requirement containing both "and" and "or" in the same EARS sentence (compound requirement)