Stage

Resumen

Stage es un documento de encadenamiento para un ciclo de cambios de ingeniería. No reemplaza los resultados de ninguna skill, sino que registra qué produjo cada skill, cómo se relacionan esas producciones y la historia completa del ciclo de cambios.

Stage responde a cuatro preguntas:

¿Qué planeábamos hacer? (MISIÓN + documentos normativos)
¿Cómo se delegó de forma segura el trabajo de implementación? (Índice directo de Task Contracts)
¿Qué logramos realmente? (Documentos factuales + ADR)
¿Por qué existen diferencias? (Diferencias entre normativo y factual + resumen de aprendizaje)

                          STAGE.md
                   (Capa de encadenamiento / Índice + Narrativa)
                          │
    ┌────────┬────────┬────┴────┬────────────┬────────┬────────┐
    │        │             │    │            │        │        │
  MISIÓN   Documento normativo Plan de implementación (plan+todo) Task Contract (límites de delegación) Documento factual (resultado)    Verificación
    │                                                │
                                              ADR
                                      (Obligatorio, al menos uno por Stage)

Cuándo usar

La creación de un Stage es decisión exclusiva del usuario. Solo se crea cuando el usuario lo solicita explícitamente; no hay condiciones de activación automática.

El usuario suele iniciarlo de las siguientes maneras:

"Crear Stage" / "Iniciar un Stage"
"Crear Stage para este ciclo de trabajo"
"Sellar Stage" / "Seal Stage"
Después de que /plan genere el plan, el usuario responde "sí" a la pregunta "¿Necesita un documento Stage?"

Escenarios típicos de uso (para referencia del usuario, no son reglas de activación):

Cambios que abarcan múltiples tareas y constituyen un conjunto lógico
Nueva funcionalidad que abarca varios módulos
Refactorización que cambia la estructura interna pero mantiene el comportamiento
Cadena completa de corrección de errores en producción
Cualquier cambio que requiera registrar decisiones arquitectónicas

No se activa automáticamente:

Tareas aisladas únicas o cambios mecánicos no crean un Stage automáticamente
Actualizaciones puramente documentales no crean un Stage automáticamente
El agente no decide por sí mismo basándose en la cantidad de tareas o el alcance entre módulos; debe ser confirmado por el usuario

Cuando delegated-task-contract necesite un Stage al que pertenecer, tampoco debe activar automáticamente la creación del Stage; si aún no existe un Stage, debe detenerse y solicitar al usuario una decisión explícita. La pertenencia al directorio, el índice unidireccional, la sincronización de estado y los controles de sellado siguen las reglas de Integración entre Stage y Task Contract.

Tipos de Stage

Tipo	Motivación	Criterio de éxito	Normativo vs factual	Enfoque documental
feat	Añadir nueva capacidad	Nuevo comportamiento aparece y cumple especificaciones	Las diferencias son normales, deben registrarse	spec + api-contract + api-doc
opt	Mejorar comportamiento existente	Los indicadores alcanzan el valor objetivo	Registrar brevemente la comparación del efecto de optimización	Línea base de rendimiento + resultados de optimización
debug	Reparar comportamiento erróneo	El error no se reproduce + pruebas de regresión cubren la ruta raíz	Normativo = factual (la reparación es el objetivo)	Fenómeno + causa raíz + estrategia de reparación + medidas preventivas
refactor	Cambiar estructura interna, comportamiento invariante	Todo el comportamiento existente permanece sin cambios, pruebas de regresión pasan al 100%	Normativo = factual es un requisito estricto	Diseño arquitectónico + descripción del cambio estructural

Ciclo de vida del Stage

Después de la salida de /plan     Durante la implementación          Después de completar toda la implementación   Al ejecutar /ship
     │                          │                            │                      │
     ▼                          ▼                            ▼                      ▼
  Crear esqueleto           Mantener documentos e índice de Contract  Sellar STAGE.md             Verificar existencia del Stage
  (MISIÓN +                (Estado, desviaciones, resumen de         (Control final, documento  (checklist de pre-lanzamiento,
   rutas de documentos       evidencia)                               factual, ADR,               elementos bloqueantes)
   normativos,                                                 análisis de diferencias,
   enlace al plan de                                           resultados de verificación,
   implementación)                                            resumen de aprendizaje)

Creación (fase de esqueleto)

Después de que /plan genere tasks/plan.md y tasks/todo.md, el agente pregunta al usuario si necesita un documento Stage. Una vez que el usuario confirma:

Crear el directorio stages/<stage-id>/ (stage-id es un título corto en kebab-case)
Crear el esqueleto STAGE.md, rellenando previamente:
- Tipo (feat | opt | debug | refactor)
- Estado establecido como draft
- Tomador de decisiones
- MISIÓN (extraída de la especificación)
- Ruta del documento normativo (marcado como TODO)
- Enlace al plan de implementación (rellenar con tasks/plan.md y tasks/todo.md)
- Tabla de índice directo de Task Contracts (inicialmente vacía)
- Documento factual (marcado como TODO—rellenar después de la implementación)
- ADR (marcado como TODO—al menos uno por Stage, rellenar después de la implementación)
- Resultados de verificación (marcado como TODO)
Añadir una línea en stages/INDEX.md

Rellenado (fase de construcción)

Durante la implementación:

Al completar una tarea normal no es necesario modificar STAGE.md; pero al crear un Contract por primera vez, cambiar su estado o reportar una desviación/evidencia, debe sincronizarse
Cuando se produzcan documentos normativos (spec, api-contract), actualizar los enlaces correspondientes y eliminar la marca TODO
Los Contracts solo son indexados por STAGE.md; no añadir campos de Stage ni enlaces inversos en los Contracts
Las desviaciones de Contract que no sean none deben sincronizarse en la tabla de "Diferencias entre normativo y factual", sin esperar al sellado para rellenarlas de memoria

Sellado (después de completar)

Una vez que todas las tareas estén completadas y verificadas, el agente recuerda al usuario que selle el Stage. Una vez que el usuario confirma:

Comparar task-contract/ con la tabla de índices para asegurarse de que no haya omisiones, enlaces rotos o desviaciones de estado
Confirmar que todos los estados del cuerpo del Contract son COMPLETED o CANCELLED; cualquier DRAFT, READY o BLOCKED_BY_ARCHITECTURE impedirá el sellado
Rellenar los enlaces de documentos factuales (api-doc, ADR)
Rellenar la Tabla de diferencias entre normativo y factual (incluyendo la columna "¿Actualizar documento normativo retroactivamente?"), incorporando las desviaciones significativas reportadas por los Contracts
Rellenar los resultados de verificación y enlazar la Evidencia Requerida de los Contracts
Extraer un Resumen de aprendizaje ("Qué hacer la próxima vez" y "Qué no hacer la próxima vez")
Cambiar el estado a done
Actualizar el estado de la línea correspondiente en stages/INDEX.md

Verificación (antes del lanzamiento)

El checklist de pre-lanzamiento de /ship incluye:

"□ ¿Existe un documento Stage para cambios significativos?"—Si este ciclo de trabajo creó un Stage, este es un elemento bloqueante

Plantilla de Stage

La siguiente es la plantilla estándar para stages/<stage-id>/STAGE.md:

# Stage: [Título corto]

**Tipo**: feat | opt | debug | refactor
**Fecha**: YYYY-MM-DD — YYYY-MM-DD
**Estado**: draft | in-progress | done | abandoned | superseded | split
**Tomador de decisiones**: @username

---

## MISIÓN (Objetivo del ciclo)

<!-- feat / opt / refactor usan la MISIÓN estándar -->

- **Objetivo**: [Una frase que describa qué se quiere lograr en este ciclo]
- **Usuario**: [Quién se beneficiará]
- **Criterio de éxito**: [Cómo saber que está completo—condiciones específicas y verificables]
- **Restricciones**: [Límites vinculantes—técnicos, recursos, tiempo]
- **No se hará**: [Contenido excluido explícitamente y el motivo]

<!-- El tipo debug reemplaza con la siguiente estructura: -->
<!--
- **Fenómeno**: [Qué hizo el usuario, qué vio, qué debería haber visto]
- **Impacto**: [Alcance del impacto, duración, riesgo de integridad de datos]
- **Hipótesis de causa raíz**: [Juicio inicial—actualizar con la causa raíz confirmada después de la implementación]
- **Estrategia de reparación**: [Plan de parada + reparación de causa raíz + medidas preventivas]
- **Criterio de éxito**: [El error no se reproduce, pruebas de regresión cubren la ruta de la causa raíz, existe verificación estática para problemas similares]
-->

→ Ver [MISSION.md](./MISSION.md)

---

## Documentos normativos (cómo planeábamos hacerlo)

| Documento | Skill de origen | Descripción |
|-----------|-----------------|-------------|
| [spec/xxx.md](./spec/xxx.md) | spec-driven-dev | Especificación funcional |
| [design/api-contract.md](./design/api-contract.md) | api-and-interface | Contrato de API |
| [design/xxx.md](./design/xxx.md) | — | [Descripción adicional] |

> Rellenar antes de comenzar la implementación. Si algún tipo de documento no es relevante para este ciclo, eliminar la fila correspondiente.

---

## Plan de implementación

| Documento | Skill de origen | Descripción |
|-----------|-----------------|-------------|
| [tasks/plan.md](./tasks/plan.md) | planning-and-task | Plan técnico |
| [tasks/todo.md](./tasks/todo.md) | planning-and-task | Lista de tareas atómicas |

---

## Task Contracts (Límites de delegación de ejecución)

> Solo indexa las delegaciones de escritura que requieren el control de acceso de `delegated-task-contract`. El cuerpo, estado y evidencia requerida del Contract se basan en el archivo correspondiente; esta tabla solo guarda enlaces directos y resúmenes, sin escribir enlaces inversos al Stage en el Contract.

| Tarea | Contract | Estado | Desviación / Evidencia |
|-------|----------|--------|------------------------|
| [ID de tarea] | [ID de tarea](./task-contract/TASK-XXX.md) | DRAFT \| READY \| BLOCKED_BY_ARCHITECTURE \| COMPLETED \| CANCELLED | [Bloqueo, desviación, evidencia o motivo de cancelación; si no hay, escribir `—`] |

> Si no hay Contracts todavía, mantener el encabezado de la tabla y eliminar la fila de ejemplo. Sincronizar esta tabla cada vez que se cree un Contract por primera vez o cuando cambie su estado, desviación o evidencia.

---

## Documentos factuales (cómo resultó realmente)

> Rellenar esta sección después de completar la implementación.

| Documento | Skill de origen | Descripción |
|-----------|-----------------|-------------|
| [docs/api/xxx.md](./docs/api/xxx.md) | documentation-and-adrs | Documentación real de la API |
| [docs/adr/XXX-title.md](./docs/adr/XXX-title.md) | documentation-and-adrs | Registro de decisión arquitectónica (obligatorio, al menos uno por Stage) |

### ADR (Obligatorio)

Cada Stage **debe** producir al menos un ADR. Los ADR registran decisiones arquitectónicas clave y su contexto.

| ADR | Contenido de la decisión | Alternativas |
|-----|--------------------------|--------------|
| [ADR-XXX](./docs/adr/XXX.md) | [Descripción de la decisión en una frase] | [Esquemas rechazados y motivos] |

**Requisitos de contenido del ADR:**
- Registrar "por qué se eligió A en lugar de B"
- Enumerar las alternativas consideradas y rechazadas, junto con los motivos del rechazo
- Describir las restricciones y consecuencias de la decisión
- Si la decisión se relaciona con un ADR existente, citarlo explícitamente

**Enfoque del ADR según el tipo de Stage:**

| Tipo de Stage | Contenido típico del ADR |
|---------------|--------------------------|
| **feat** | Por qué se eligió esta arquitectura/marco/protocolo; compensaciones en el diseño del modelo de datos |
| **opt** | Por qué se eligió esta estrategia de optimización; por qué no se eligieron otras opciones (por ejemplo, caché vs optimización de índices) |
| **debug** | Por qué surgió la causa raíz; por qué se eligió este esquema de reparación; diseño de las medidas preventivas |
| **refactor** | Por qué se eligió esta nueva estructura; por qué no se unificaron ciertos casos límite; comparación entre la estructura nueva y la antigua |

---

## Diferencias entre normativo y factual

> Rellenar después de completar la implementación. Registrar cada desviación significativa entre el plan y la realidad.

Cuando el informe de `Evidencia Requerida` del Contract reporte una desviación no `none`, sincronizar la desviación en esta tabla al mismo tiempo que se acepta el Contract; no dejar rastro solo en el Contract.

| Diferencia | Normativo (Plan) | Factual (Resultado) | Motivo | ¿Actualizar documento normativo retroactivamente? |
|------------|------------------|---------------------|--------|---------------------------------------------------|
| [Breve descripción] | [Cómo se planeó] | [Cómo se hizo realmente] | [Por qué hubo desviación] | Sí / No |

**Explicación de la columna "¿Actualizar documento normativo retroactivamente?":**
- **Sí**: La diferencia se considera una dirección de diseño correcta; se ha modificado retroactivamente la especificación o el contrato de API para que coincida con la realidad
- **No**: La diferencia es un compromiso temporal o una solución intermedia; el documento normativo se mantiene tal cual para referencia en Stages posteriores
- Todas las filas marcadas como "No" son candidatos para el backlog del siguiente ciclo

---

## Resultados de verificación

| Elemento de verificación | Estado | Evidencia |
|--------------------------|--------|-----------|
| [Criterio de aceptación 1] | ✅ / ❌ | [Informe de pruebas, datos de rendimiento, capturas de pantalla, etc.] |
| [Criterio de aceptación 2] | ✅ / ❌ | [Evidencia] |
| Sin regresión | ✅ / ❌ | Enlace a la ejecución de CI |

→ Ver [VERIFY.md](./VERIFY.md)

---

## Resumen de aprendizaje

> Rellenar al sellar. No más de dos frases.

- **Qué hacer la próxima vez**: [Qué se hizo bien en este ciclo—vale la pena reutilizarlo en otros Stages]
- **Qué no hacer la próxima vez**: [Qué se hizo mal en este ciclo—debe evitarse, tenerse en cuenta o mejorarse]

---

## Relaciones

- **Stage anterior**: [STAGE-XXX](../stage-XXX/STAGE.md) (o "Ninguno")
- **Plan para el siguiente ciclo**: [Breve descripción, o "Ninguno"]

Incrementos (añadidos después del sellado)

Después de que un Stage se selle (estado done), si se encuentra un pequeño problema que necesita corrección pero no constituye un nuevo Stage, se puede añadir una sección de incremento al final de STAGE.md:

---

## Incremento 1 (2026-07-28)

- **Cambio**: [Breve descripción de lo que se corrigió]
- **Motivo**: [Por qué se necesitó esta corrección después del sellado]
- **Alcance del impacto**: [Qué archivos/módulos]

Al añadir un incremento:

El estado del Stage permanece como done, no se revierte a in-progress
Las entradas de incremento se añaden en orden cronológico
Si la corrección implica una nueva decisión ADR, añadirla a la tabla de ADR en los documentos factuales y marcarla con [Incremento 1]
Cuando se acumulen más de 3 incrementos, considerar si se debe crear un nuevo Stage en lugar de seguir añadiendo

INDEX.md

stages/INDEX.md es el punto de entrada de navegación para todos los Stages. Se mantiene al crear y sellar cada Stage.

# Índice de Stages

| ID | Título | Tipo | Estado | Módulos involucrados | Fecha |
|----|--------|------|--------|----------------------|-------|
| 001 | raft-election-optimization | opt | done | consensus, rpc | 2026-07-15 — 2026-07-17 |
| 002 | wal-checksum-verification | feat | done | storage, wal | 2026-07-18 — 2026-07-20 |
| 003 | replica-sync-refactor | refactor | done | replication, net | 2026-07-22 — 2026-07-23 |
| 004 | multi-az-placement | feat | abandoned | placement, scheduler | 2026-07-23 |

Reglas de mantenimiento:

Añadir una línea al crear un Stage, con estado draft
Actualizar el estado a done al sellar un Stage
Sincronizar la actualización cuando el estado de un Stage cambie a abandoned, superseded o split
Módulos involucrados enumera los módulos/directorios de nivel superior afectados, para facilitar la búsqueda por módulo

Modelo de estados

Estado	Significado	Cuándo usar
`draft`	Esqueleto creado, implementación aún no iniciada	Después de crear el Stage
`in-progress`	Implementación en curso	Durante la implementación (uso opcional)
`done`	Completado según lo planeado, sellado	Todas las tareas completadas, verificación pasada, resumen de aprendizaje escrito
`abandoned`	Abandonado a medio camino	Dirección incorrecta, requisitos cancelados, interrumpido por prioridad más alta
`superseded`	Reemplazado por otro Stage	Stage-B abarca el alcance de Stage-A
`split`	Dividido en varios Stages más pequeños	Stage demasiado grande, dividido en sub-Stages independientes

Manejo de abandoned:

Actualizar la sección MISIÓN, añadiendo un párrafo con el "motivo del abandono"
Mantener al menos un ADR en la tabla de ADR, registrando "por qué no continuar"
Rellenar el resumen de aprendizaje como de costumbre—las lecciones del abandono suelen ser más valiosas que las del éxito
El tomador de decisiones decide si es necesario revertir el código/documentos ya completados en el Stage abandonado, y lo registra en el ADR
En la sección Relaciones, el "Plan para el siguiente ciclo" se cambia a "Ninguno (abandonado)"

Manejo de superseded:

Actualizar la sección MISIÓN, añadiendo un párrafo con "qué Stage lo reemplaza y por qué"
Añadir en la sección Relaciones "Reemplazado por: STAGE-XXX"
Cambiar el estado a superseded
No seguir añadiendo incrementos en el Stage reemplazado—todo el trabajo posterior se transfiere al Stage que lo reemplaza

Manejo de split:

Actualizar la sección MISIÓN, añadiendo un párrafo con "en qué sub-Stages se dividió y por qué"
Añadir en la sección Relaciones "Dividido en: STAGE-XXX, STAGE-YYY"
Cambiar el estado a split
El Stage original ya no recibe incrementos—todo el trabajo se transfiere a los sub-Stages

Estructura de directorios

stages/
  INDEX.md                      ← Índice, una línea por Stage
  001-raft-election-optimization/
    STAGE.md                    ← Documento de encadenamiento del Stage
    MISSION.md                  ← Descripción detallada del objetivo (opcional, recomendado para proyectos complejos)
    spec/                       ← Normativo: especificación funcional
    design/                     ← Normativo: contrato de protocolo, diseño de datos
    tasks/
      plan.md                   ← Plan de implementación
      todo.md                   ← Lista de tareas
    task-contract/              ← Límites de delegación de ejecución, al mismo nivel que tasks/spec
      TASK-001.md
      TASK-002.md
    docs/
      protocol/                 ← Factual: documentación de protocolo, interfaz RPC
      adr/                      ← Factual: registro de decisiones arquitectónicas (obligatorio)
    verify/                     ← Evidencia de verificación
      fault-injection-report.md
      consistency-check.txt
      perf-before-after.json
  002-wal-checksum/
    ...
    ...

Excepto por la ruta de pertenencia de los Task Contracts, la estructura de directorios es un paradigma recomendado. La restricción principal es: STAGE.md debe existir, cada Stage debe contener al menos un ADR; si existen Task Contracts, deben estar ubicados en task-contract/ de ese Stage y ser indexados directamente por STAGE.md.

Interacción con otras skills

Skill	Modo de interacción
spec-driven-development	La MISIÓN del Stage se extrae del Objetivo de la especificación
planning-and-task-breakdown	Después de la salida de `/plan`, el agente pregunta si se debe crear el esqueleto del Stage
delegated-task-contract	El Contract se guarda en `task-contract/` del Stage actual; `STAGE.md` indexa unidireccionalmente su estado, desviación y evidencia; el Contract no indexa inversamente el Stage
api-and-interface-design	Tanto los contratos de protocolo (gRPC/protobuf) en los documentos normativos como los documentos de interfaz en los documentos factuales se enlazan al Stage
failure-injection-testing	Cuando se trata de tolerancia a fallos y recuperación de errores, el plan de inyección de fallos y el informe del experimento de caos se enlazan a los documentos factuales del Stage
consistency-and-durability-verification	Cuando se trata de almacenamiento o replicación de estado, el informe de verificación de consistencia/durabilidad se enlaza a los resultados de verificación del Stage
Flujo de implementación nativo del agente	Una vez que todas las tareas están completadas y verificadas, el agente recuerda sellar el Stage
documentation-and-adrs	El ADR es un requisito obligatorio del Stage; cada Stage debe tener al menos uno
shipping-and-launch	`/ship` verifica si existe un Stage (lo bloquea si se creó uno en este ciclo)

Excusas de racionalización comunes

Excusa de racionalización	Realidad
"Este cambio es demasiado pequeño, no necesita Stage"	Si el cambio es tan pequeño que no necesita Stage, entonces probablemente tampoco necesita ADR. Pero el usuario ya decidió crear el Stage—confía en el juicio del usuario.
"Los requisitos son demasiado simples, no habrá diferencias entre normativo y factual"	Las diferencias están en todas partes—incluso el cambio más simple puede desviarse del plan durante la implementación. El valor central del Stage es precisamente registrar estas diferencias.
"Primero escribe el código, el Stage se hace después"	El Stage antes del sellado es un directorio vivo, no necesita escribirse de una sola vez. Pero reescribirlo después significa que el análisis de diferencias depende de la memoria—la memoria no es fiable.
"Esto no necesita ADR"	Cada Stage tiene al menos una decisión que vale la pena registrar—aunque sea "elegimos la implementación más simple porque las restricciones actuales no permiten un esquema más complejo".
"Ya está `abandoned`, el resumen de aprendizaje no tiene sentido"	Las lecciones del abandono suelen ser más valiosas que las del éxito. Registrar "por qué se abandonó" es al menos tan importante como registrar "por qué se tuvo éxito".
"Marcar 'No' en la tabla de diferencias es suficiente, no necesita explicación"	Cada fila de la tabla de diferencias es una entrada para decisiones futuras. Las filas marcadas como "No" le dicen a la próxima persona "aquí hay deuda técnica, y se dejó intencionalmente".
"INDEX.md se puede hacer después"	El valor de INDEX.md crece con la cantidad de Stages—en el primer Stage no se nota, pero en el décimo se vuelve indispensable. Mantenerlo desde el principio.

Banderas rojas de advertencia

Se creó STAGE.md pero la MISIÓN está vacía—el valor del esqueleto está en la MISIÓN; un Stage sin objetivo es solo un marcador de posición
Los documentos factuales tienen documentación de API pero no un ADR correspondiente—viola la regla de "al menos un ADR por Stage"
La tabla de diferencias está vacía pero el usuario mencionó desviaciones durante la implementación—las diferencias no se capturaron
El resumen de aprendizaje dice "Ninguno" o "Todo salió bien"—cada Stage tiene lecciones; si no se encuentran, la reflexión no es lo suficientemente profunda
Un Stage abandoned no tiene "motivo de abandono"—se perdió la información más valiosa
Una línea en INDEX.md permanece en estado draft durante mucho tiempo—o se avanza en la implementación, o se marca como abandoned; no dejar que el esqueleto se pudra
La sección de incrementos acumula 3+ entradas pero no se ha considerado dividir en un nuevo Stage—indica que el alcance de este ciclo se juzgó mal; se debe reflexionar en lugar de seguir añadiendo
El campo del tomador de decisiones está vacío—en colaboración múltiple, esto rompe la cadena de trazabilidad de decisiones
Existen archivos en task-contract/ que no están indexados por STAGE.md, o enlaces de índice que apuntan a Contracts inexistentes
El estado, desviación o evidencia de un Contract ha cambiado, pero la tabla del Stage aún conserva el resumen antiguo
Un Contract enlaza inversamente a STAGE.md, causando que la relación de pertenencia se mantenga bidireccionalmente
Todavía hay Contracts con estado DRAFT, READY o BLOCKED_BY_ARCHITECTURE y el Stage se marca como done

Verificación

Después de crear el esqueleto del Stage:

stages/<stage-id>/STAGE.md existe
El tipo de Stage (feat | opt | debug | refactor) está rellenado
El estado es draft
El tomador de decisiones está rellenado
La MISIÓN está rellenada (formato estándar o de debug, según el tipo)
Los enlaces del plan de implementación apuntan a tasks/plan.md y tasks/todo.md
La sección "Task Contracts (Límites de delegación de ejecución)" y la tabla de índices directos vacía están creadas
Se ha añadido la línea correspondiente en stages/INDEX.md

Después de sellar el Stage:

13eholder/zflow

¿Qué es zflow?

Preguntar en tu IA favorita

Documentación