# Plantilla de Spec con Diagramas

> **Propósito:** Esta plantilla combina texto estructurado con diagramas visuales (Mermaid.js) para inmunizar tu spec contra ambigüedades antes de que llegue al equipo técnico.
>
> **Instrucciones:** Copia este archivo para cada nueva feature. Completa las secciones. Los diagramas están pre-escritos como ejemplos — reemplázalos con tu flujo real.

---

## 1. Encabezado del Spec

| Campo | Valor |
|-------|-------|
| **Feature** | `[Nombre corto de la feature]` |
| **Spec ID** | `SPEC-[YYYYMMDD]-[NN]` |
| **Autor** | `[Tu nombre]` |
| **Fecha** | `[YYYY-MM-DD]` |
| **Estado** | `Borrador / En revisión / Inmunizado / Aprobado` |
| **PR/FAQ Link** | `[Link al documento PR/FAQ si aplica]` |

---

## 2. Contexto (¿Por qué existe esto?)

```
2-3 párrafos explicando el problema de negocio, la oportunidad validada,
y cómo esta feature se conecta con el resultado deseado del equipo.
No entres en detalles técnicos ni de implementación.
```

---

## 3. Descripción del Comportamiento (Texto)

> Describe el flujo en lenguaje natural. Sé específico pero no técnico.
> Este texto es lo que compartirías con stakeholders no técnicos.

```
[Escribe aquí el comportamiento esperado en 3-5 párrafos.
Incluye el happy path, los casos de error más obvios,
y las reglas de negocio fundamentales.
]
```

---

## 4. Diagramas

### 4.1. Flowchart — Flujo Principal y Ramas de Error

```mermaid
graph TD
    A[Inicio] --> B[Paso 1]
    B --> C{Condición 1?}
    C -->|Sí| D[Paso 2A]
    C -->|No| E[Paso 2B]
    D --> F{Condición 2?}
    F -->|Sí| G[Flujo feliz]
    F -->|No| H[Manejo de error 1]
    E --> I[Manejo de error 2]
    G --> J[Fin]
    H --> J
    I --> J
```

**Reglas para tu flowchart:**
- [ ] Happy path completo (sin errores)
- [ ] Al menos 2 ramas de error documentadas
- [ ] Al menos 2 condiciones límite (timeout, cancelación, datos inválidos, concurrencia)
- [ ] Cada flecha tiene etiqueta explícita (Sí/No o condición)
- [ ] No hay nodos desconectados o flechas sin destino

### 4.2. State Diagram — Ciclo de Vida del Objeto Principal

```mermaid
stateDiagram-v2
    [*] --> EstadoInicial
    EstadoInicial --> EstadoIntermedio1: Evento A
    EstadoInicial --> EstadoIntermedio2: Evento B
    EstadoIntermedio1 --> EstadoFinal: Evento C
    EstadoIntermedio2 --> EstadoFinal: Evento D
    EstadoIntermedio1 --> EstadoError: Evento E
    EstadoFinal --> [*]
    EstadoError --> EstadoIntermedio1: Reintento
```

**Tabla de transiciones:**

| Estado Actual | Evento | Condición | Siguiente Estado | Acción / Efecto Secundario |
|--------------|--------|-----------|-----------------|---------------------------|
| `[Estado A]` | `[Evento]` | `[Condición]` | `[Estado B]` | `[Email, webhook, log]` |
| — | — | — | — | — |
| — | — | — | — | — |

### 4.3. Sequence Diagram — Coreografía entre Sistemas

```mermaid
sequenceDiagram
    participant Usuario
    participant Frontend
    participant Backend
    participant APIExterna
    participant DB

    Usuario->>Frontend: Acción inicial
    Frontend->>Backend: POST /api/endpoint
    Backend->>APIExterna: Llamada externa
    APIExterna-->>Backend: Respuesta
    Backend->>DB: Guardar estado
    DB-->>Backend: Confirmación
    Backend-->>Frontend: 201 Created
    Frontend-->>Usuario: Confirmación visual
```

**Preguntas que este diagrama revela (responder antes de pasar a desarrollo):**
- [ ] ¿Hay timeout definido para cada llamada entre sistemas?
- [ ] ¿Quién maneja los reintentos si una llamada falla?
- [ ] ¿La operación es atómica o tolera estados inconsistentes?
- [ ] ¿El usuario ve feedback visual mientras espera?
- [ ] ¿Qué pasa si el webhook llega antes que la respuesta síncrona?

---

## 5. Ambigüedades Identificadas (Post-Diagramación)

> Llena esta tabla después de traducir el texto a diagramas.
> Cada fila es una pregunta que el texto original no respondía.

| # | Ambigüedad | Decisión Tomada | Impacto en Diagrama |
|---|-----------|----------------|---------------------|
| 1 | `[Ej: ¿Qué pasa si el usuario cierra el modal a mitad del flujo?]` | `[Ej: Se cancela la operación, se limpia el slot reservado parcialmente]` | `[Se agregó rama de "cancelación" en el flowchart]` |
| 2 | — | — | — |
| 3 | — | — | — |

---

## 6. Trazabilidad: Diagrama → Tareas

> Cada rama del diagrama se traduce a una tarea del backlog.
> Usa esta tabla para alimentar tu refinamiento.

| Rama del Diagrama | Tarea Propuesta | Tipo | Esfuerzo Est. |
|------------------|----------------|------|---------------|
| `[Rama específica del flowchart]` | `[Ej: [BE] Endpoint POST /api/reserve]` | Feature / Validación / Error / Borde | `[XS/S/M/L/XL]` |
| — | — | — | — |
| — | — | — | — |

---

## 7. Checklist de Inmunización

> Marca solo cuando el spec haya pasado por las 3 rondas.

- [ ] **Ronda 1 — Traducción:** El texto fue convertido a diagramas. Las ambigüedades detectadas están documentadas en la sección 5.
- [ ] **Ronda 2 — Caminos infrecuentes:** Se recorrieron todas las ramas buscando casos borde (timeout, cancelación, concurrencia, datos corruptos, medianoche, sesión expirada).
- [ ] **Ronda 3 — Revisión por pares:** Un miembro del equipo técnico leyó los diagramas (sin el texto original) y no hizo preguntas aclaratorias. Si preguntó, se actualizó el diagrama y se repitió.

**Nivel de inmunización alcanzado:**
- [ ] Inmunizado (sin preguntas)
- [ ] Protegido (1-2 preguntas, no requirieron cambio)
- [ ] Vulnerable (3+ preguntas, requirieron re-dibujar)
- [ ] Infectado (no se usó el diagrama → reprocesar)

---

## 8. Historial de Cambios

| Fecha | Versión | Cambio | Autor |
|------|---------|--------|-------|
| `[YYYY-MM-DD]` | v1.0 | Spec inicial | — |
| — | — | — | — |

---

*Generado con la Plantilla de Spec con Diagramas — Módulo 15, Bootcamp Product Operator*