SPEC Writing Expert

Requirement Specification Standards

Format: EARS (Easy Approach to Requirements Syntax)
Traceability: TAG-based (SPEC→TEST→CODE→DOC)

Overview

Standardized approach to writing clear, testable requirements.

SPEC Components

1. Functional Requirements: What the system does.
2. Non-Functional Requirements: Performance, security, usability.
3. Acceptance Criteria: Testable conditions for completion.
4. TAG Assignment: Unique identifier for traceability.

EARS Format (5 Types)

1. Ubiquitous Requirements

Always true, no conditions.

Template: The [system] shall [action].

Example:

The authentication system shall encrypt passwords using bcrypt.

2. Event-Driven Requirements

Triggered by events.

Template: When [trigger], the [system] shall [action].

Example:

When a user submits login credentials, the system shall validate against the database.

3. State-Driven Requirements

Depends on system state.

Template: While [state], the [system] shall [action].

Example:

While user is authenticated, the system shall display personalized dashboard.

4. Optional Requirements

May or may not occur.

Template: Where [condition], the [system] shall [action].

Example:

Where MFA is enabled, the system shall require second factor authentication.

5. Complex Requirements

Multiple conditions.

Template: If [condition], then [action], else [alternative].

Example:

If password validation fails, then system shall display error message, else proceed to dashboard.

SPEC Template

# SPEC-001: User Authentication

## Overview

Implement secure user authentication with JWT tokens.

## Functional Requirements

### @AUTH-001: Login Validation

**Type**: Event-Driven
**Requirement**: When user submits credentials, system shall validate email and password format before database lookup.
**Acceptance Criteria**:

- Email format: RFC 5322 compliant
- Password: min 8 characters
- Return validation errors within 100ms

### @AUTH-002: Password Hashing

**Type**: Ubiquitous
**Requirement**: System shall hash passwords using bcrypt with 12 rounds.
**Acceptance Criteria**:

- Bcrypt algorithm (OWASP recommended)
- 12 salt rounds (2025 standard)
- Unique salt per password

## Non-Functional Requirements

### @AUTH-NF-001: Performance

- Login response time: <500ms (p95)
- Concurrent logins: 1000/sec

### @AUTH-NF-002: Security

- OWASP Top 10 compliance
- TLS 1.3 for transmission
- Rate limiting: 5 attempts/min per IP

## TAG Traceability

- SPEC: @AUTH-001, @AUTH-002
- Tests: test_auth.py
- Code: auth/login.py
- Docs: api/authentication.md

Best Practices

1. One Requirement Per TAG: Don't combine multiple requirements.
2. Testable: Each requirement must be verifiable.
3. Unambiguous: Use "shall" (mandatory), "should" (recommended), "may" (optional).
4. Measurable: Include quantifiable acceptance criteria.

Validation Checklist

• EARS Format: Correct template used?
• TAG Assignment: Unique @TAG-### assigned?
• Testable: Can be verified with tests?
• Complete: Acceptance criteria defined?
• Traceable: Linked to TEST/CODE/DOC?

Related Skills

• moai-foundation-ears: Detailed EARS syntax
• moai-foundation-tags: TAG management
• moai-foundation-trust: Quality principles

Last Updated: 2025-11-20