Plantillas y checklist de calidad

Esta sección reúne recursos listos para copiar y pegar: plantillas para los 5 patrones, checklist de revisión y guía rápida.

Plantilla 1: Ubiquitous

REQ-<area>-<num>: The <subject> shall <response>.

Ejemplo:

REQ-AUTH-001: The auth service shall store passwords using bcrypt with a cost factor of 12.

Plantilla 2: Event-driven

REQ-<area>-<num>: When <trigger>, the <subject> shall <response>.

Ejemplo:

REQ-NOTIF-010: When an order status changes, the notification service shall send a push notification to the customer's registered devices within 30 seconds.

Plantilla 3: State-driven

REQ-<area>-<num>: While <state>, the <subject> shall <response>.

Ejemplo:

REQ-UI-022: While the export job is running, the UI shall display a progress bar with the current percentage and an estimated time remaining.

Plantilla 4: Optional feature

REQ-<area>-<num>: Where <feature>, the <subject> shall <response>.

Ejemplo:

REQ-EXPORT-005: Where the user has a Premium subscription, the export service shall allow exporting files up to 1 GB.

Plantilla 5: Unwanted behaviour

REQ-<area>-<num>: If <unwanted condition>, then the <subject> shall <response>.

Ejemplo:

REQ-PAY-014: If the payment gateway returns HTTP 5xx, then the payment service shall retry the request up to 3 times with exponential backoff (1s, 2s, 4s) and shall return HTTP 503 to the client if all retries fail.

Plantilla combinada

REQ-<area>-<num>: [Where <feature>,] [while <state>,] [when <trigger>,] the <subject> shall <response>.
REQ-<area>-<num>: If <unwanted condition>, then the <subject> shall <response>.

Checklist de revisión

Antes de aprobar un requisito EARS:

Estructura

• Tiene identificador único (REQ-AREA-NNN)
• Usa una de las 5 plantillas (o es claramente ubiquitous)
• Palabras clave correctas: When (evento), While (estado), Where (feature), If/Then (error)
• Orden canónico: Where → While → When → subject → shall → response

Contenido

• Sujeto explícito (no “se hará”, sino “el módulo X hará”)
• Una sola respuesta (o múltiples atómicas e inseparables)
• Usa shall (o “deberá” si es en español)
• Voz activa

Verificabilidad

• La respuesta es observable (un test puede verificarla)
• Incluye métricas/plazos/cardinalidad cuando aplica
• No tiene palabras tóxicas (apropiado, rápido, etc, varios, aproximadamente)

Trazabilidad

• Está trazado a una historia de usuario o épica
• Está referenciado por al menos un test (o lo será)
• No referencia código específico (describe qué, no cómo)

Errores

• Si describe happy path, los casos de error están en REQ propios If/Then
• Los casos de error tienen respuesta verificable (no “manejará el error”)

Checklist de revisión de un documento completo

Al revisar un conjunto de requisitos:

• No hay requisitos duplicados (mismo trigger + misma respuesta con palabras distintas)
• No hay requisitos contradictorios (uno dice X y otro dice no-X bajo las mismas condiciones)
• Cada happy path tiene sus casos de error definidos
• Los requisitos no funcionales (performance, seguridad, a11y) están separados de los funcionales
• Existe trazabilidad explícita entre historia, REQ y test
• La numeración no tiene huecos sin explicación

Tabla de cuantificación común

Cuando escribas respuestas, usá estas dimensiones:

Dimensión	Ejemplos
Tiempo	within 200 ms, within 30 days, at next sync
Percentil	p50, p95, p99
Tamaño	up to 100 MB, at most 50000 records
Cardinalidad	exactly 1, at least 3, between 5 and 10
Código HTTP	HTTP 200, HTTP 401, HTTP 429
Formato	ISO 8601 UTC, RFC 5322 email, RFC 3339 datetime
Estado	transition to state Y, persist Z in the database
Concurrencia	1000 concurrent users, 10 req/s per user

Plantilla de spec completa

# Spec: <Feature>

**Versión**: 1.0
**Estado**: Draft / In Review / Approved
**Owners**: <PM>, <Tech Lead>

## Contexto

<Breve descripción del problema y por qué se aborda ahora>

## Historias relacionadas

- AUTH-101 — Como usuario, quiero ...
- AUTH-102 — Como admin, quiero ...

## Requisitos funcionales

REQ-AUTH-001: When ...

REQ-AUTH-002: While ...

## Requisitos no funcionales

REQ-PERF-001: The auth service shall respond to /auth/login within 200 ms at p95.

REQ-SEC-001: The auth service shall not log credentials, tokens, or PII.

## Out of scope

- Social login (OAuth) — se aborda en spec separada
- MFA — se aborda en spec separada

## Trazabilidad

| REQ            | Historia    | Test                                |
| -------------- | ----------- | ----------------------------------- |
| REQ-AUTH-001   | AUTH-101    | auth.spec.ts: "logs in with valid"  |
| REQ-AUTH-002   | AUTH-102    | auth.spec.ts: "rejects invalid"     |

Guía rápida (cheat sheet)

┌───────────────────┬──────────────────┬─────────────────────────────────────┐
│ Patrón            │ Palabra clave    │ Plantilla                           │
├───────────────────┼──────────────────┼─────────────────────────────────────┤
│ Ubiquitous        │ —                │ The X shall Y.                      │
│ Event-driven      │ When             │ When X, the Y shall Z.              │
│ State-driven      │ While            │ While X, the Y shall Z.             │
│ Optional feature  │ Where            │ Where X, the Y shall Z.             │
│ Unwanted          │ If ... then      │ If X, then the Y shall Z.           │
└───────────────────┴──────────────────┴─────────────────────────────────────┘

Reglas absolutas:

1. Sujeto explícito siempre
2. Voz activa siempre
3. shall como verbo modal
4. Una respuesta por requisito
5. Verificable (medible u observable)
6. Sin palabras tóxicas
7. ID único y trazable

En el siguiente y último capítulo revisamos casos de estudio en dominios regulados.