ears-spec-writing

Files (3)

• SKILL.md
• SKILL.md.bundle
• SKILL.md.sig

SKILL.md (first lines)

# EARS Spec Writing

> Five sentence patterns. Zero ambiguity. Both humans and LLMs read them the same way.

**Tradeoff:** EARS feels formal compared to free prose. Worth it: the LLM cannot
"interpret" an EARS clause — there's nothing to interpret. Specs become tests.

---

## The five patterns

### 1. Ubiquitous (always-true requirements)

```
THE SYSTEM SHALL <action>.
```

Example:
> THE SYSTEM SHALL store all passwords using Argon2id with a work factor of at least 3.

### 2. Event-driven (response to an external trigger)

```
WHEN <trigger>, THE SYSTEM SHALL <action>.
```

Example:
> WHEN a user submits a valid email on the password reset form,
> THE SYSTEM SHALL send a one-time reset link valid for 30 minutes.

### 3. State-driven (behavior conditional on system state)

```
WHILE <state>, THE SYSTEM SHALL <action>.
```

Example:
> WHILE a reset link is unused and unexpired,
> THE SYSTEM SHALL allow exactly one password change before invalidating the link.

### 4. Unwanted behavior (handle the bad path explicitly)

```
IF <undesirable condition>, THEN THE SYSTEM SHALL <action>.
```

Example:
> IF a password is entered incorrectly 5 times within 15 minutes,
> THEN THE SYSTEM SHALL lock the account for 30 minutes and email the owner.

### 5. Optional features (conditional on feature presence)

```
WHERE <feature is present>, THE SYSTEM SHALL <action>.
```

Example:
> WHERE 2FA is enabled for the account,
> THE SYSTEM SHALL require a valid TOTP code before completing password reset.

### Complex (combinations, used sparingly)

```
WHEN <trigger>, IF <condition>, THEN THE SYSTEM SHALL <action>.
```

Example:
> WHEN the user clicks the reset link, IF the link has not been used and has not
> expired, THEN THE SYSTEM SHALL render the new-password form.

Use complex sparingly — most requirements decompose into 2-3 simple ones.

---

## Rules

1. **Use SHALL, not "must" / "should" / "may"**. SHALL is the requirement
   keyword. Other words signal preference, not requirement.

2. **One requirement per sentence**. If you say "and," it's probably two
   requirements.

3. **Quantify everything possible**. "Fast" is not a requirement. "Within 200ms
   p95 latency" is.

4. **Subject is always THE SYSTEM** (or a named subsystem like THE PAYMENT
   SERVICE). Not "the user does X."

5. **Number requirements**: REQ-1, REQ-2, … so you can reference them in
   tests, ADRs, and PRs.

---

## Anti-patterns

### "Should" instead of "shall"
> ❌ The system should validate email addresses.
> ✓ THE SYSTEM SHALL validate email addresses against RFC 5321 format.

### Implementation in the spec
> ❌ The system shall use Redis to cache the reset link with TTL=1800.
> ✓ THE SYSTEM SHALL invalidate the reset link 30 minutes after issuance.

(How you implement the 30-minute expiry is up to the engineer; the spec says
behavior, not technology.)

### Untestable requirement
> ❌ The system shall be user-friendly.
> ✓ WHEN a user enters an invalid email,
>   THE SYSTEM SHALL display an inline error message within 200ms identifying the specific format issue.

### Multiple requirements bundled
> ❌ The system shall validate emails, hash passwords with Argon2id, and rate-limit logins.
> ✓ Three separate REQs.

---

## Acceptance criteria from EARS

From MILTONADINA/DevOPs, MIT.

More from MILTONADINA/DevOPs