SDD Documentation Gates

Policies that govern documentation handling during the SDD workflow.

Documentation Policy

Clasificación por tipo de cambio:

Change type	Business docs	Technical docs	docs/ obligatorio
Nueva feature funcional	business-requirements skill	technical-backend-documentation o technical-frontend-documentation	✅ Sí
Cambio de domain logic (reglas de negocio, flujos, validaciones)	Actualizar doc existente	Actualizar si cambia arquitectura	✅ Sí
Cambio estructural (nueva capa, patrón, refactor significativo)	Omitir	technical-backend-documentation o technical-frontend-documentation	✅ Sí
Fix que cambia comportamiento documentado	Actualizar doc existente	Actualizar si cambia arquitectura	✅ Sí si doc existe
Fix interno sin impacto en contratos, UI ni reglas	Omitir	Omitir	❌ No
Fix simple (typo en string, tipo mal escrito, ajuste menor)	Omitir	Omitir	❌ No

Criterio rápido para docs/ obligatorio:

• ¿Cambia lógica de dominio (cálculos, validaciones, flujos de negocio)? → documentar en docs/features/
• ¿Cambia estructura técnica (patrones, capas, contratos de API)? → documentar en docs/backend/ o docs/frontend/
• ¿Es solo un fix puntual sin impacto semántico? → no documentar

Regla: si el usuario no sabe si documentar, preguntar: "¿Este cambio altera domain logic, estructura técnica o contratos visibles? Si sí → documentar en docs/."

---

Post-Spec Documentation Review Gate (sdd:spec → sdd:design / sdd:tasks)

Después de cerrar sdd-spec y ANTES de avanzar con sdd-design o sdd-tasks, el orchestrador DEBE revisar la documentación correspondiente en docs/ y decidir explícitamente qué hacer con ella.

Objetivo: evitar que el spec avance aislado de la documentación funcional/técnica ya existente, y dejar trazabilidad temprana sobre qué docs se crean, cuáles se actualizan, cuáles se eliminan y cuáles no requieren cambios.

Paso 1: Descubrimiento obligatorio

Buscar SIEMPRE documentación relacionada en este orden:

1. docs/features/{modulo}/ — procesos, recursos, vistas y documentación de negocio
2. docs/backend/ — contratos, patrones, integraciones, decisiones técnicas backend
3. docs/frontend/ — arquitectura frontend, flujos, formularios, componentes
4. docs/architecture/ — ADRs, decisiones estructurales, diagramas y patrones globales

Paso 2: Clasificación obligatoria por documento

Por cada documento relevante encontrado, clasificar exactamente una acción:

• keep — el doc sigue siendo correcto y no requiere cambios
• update — el doc existe pero debe alinearse con el nuevo spec
• create — el spec introduce comportamiento/estructura que aún no está documentado
• delete — el doc existente quedó obsoleto y debe eliminarse o reemplazarse

delete aplica solo cuando el spec reemplaza por completo una doc anterior o cuando el contenido documenta comportamiento que deja de existir. No usar delete para "quizás sobra"; en duda usar update y explicar.

Paso 3: Registro obligatorio en el artifact de spec

El artifact de sdd-spec DEBE incluir una sección ## Docs Impact con este formato mínimo:

## Docs Impact

### Reviewed docs
- `docs/features/...` — keep | reason
- `docs/backend/...` — update | reason

### Planned doc actions
- `create` → `docs/features/...` | reason
- `update` → `docs/frontend/...` | reason
- `delete` → `docs/features/...` | reason

### Decision summary
- docs impact: none | update | create | delete | mixed
- rationale: 1-3 bullets explicando por qué

Paso 4: Regla de avance

• Si Docs Impact contiene update, create o delete, el resto del workflow DEBE arrastrar esa decisión hasta los gates de documentación posteriores.
• Si el impacto es none, el spec igual debe dejar evidencia explícita de que la revisión se hizo.
• No avanzar desde sdd-spec con una respuesta implícita tipo "después vemos docs".

Paso 5: Relación con los otros gates

• Este gate NO reemplaza el Pre-Apply Documentation Gate; lo alimenta con una decisión temprana.
• Este gate NO reemplaza el Post-Apply Documentation Gate; verify sigue siendo la última palabra sobre lo que realmente quedó implementado.
• Si hay divergencia entre Docs Impact y la implementación final, manda verify-report.md y se corrige en el gate post-apply.

---

Pre-Apply Documentation Gate (sdd:tasks → sdd:apply)

Después de que sdd-tasks complete y ANTES de lanzar sdd-apply, el orchestrador DEBE evaluar si el cambio requiere documentación business:

Evaluación (basada en proposal.md):

IF proposal indica:

• Nueva funcionalidad del sistema (nueva feature)
• Modificación de comportamiento de funcionalidad existente

THEN:

1. Lanzar business-requirements-documenter sub-agent con:
   • Skill: business-requirements
   • Contexto: proposal.md + specs/ + design.md del cambio + existing_docs de la exploración
   • Output: docs/features/{module}/{name}-{type}.md
2. Mostrar al usuario el documento generado y pedir confirmación
3. Solo después de confirmación → proceder a sdd-apply

IF proposal indica:

• Fix interno sin cambio de domain logic
• Refactor sin cambio de contratos
• Fix simple (typo, ajuste menor)

THEN: Skip — proceder directamente a sdd-apply.

Ventaja vs. Post-Propose: El spec ya tiene scenarios Given/When/Then concretos y el design define la arquitectura → la documentación business es más precisa y completa.

---

Post-Apply Documentation Gate (sdd:verify → sdd:archive)

Después de que sdd-verify complete y ANTES de lanzar sdd-archive, el orchestrador DEBE ejecutar dos evaluaciones:

1. Corrección de Business Docs (si aplica)

IF verify-report.md reporta divergencias (SPEC_DIVERGENCE, PARTIAL, DEVIATIONS):

THEN:

1. Identificar qué business docs fueron generadas en el Pre-Apply Gate
2. Lanzar business-requirements-updater sub-agent con:
   • Skill: business-requirements + implemented-code-documentation
   • Contexto: verify-report.md (secciones de divergencia) + business docs existentes + código implementado
   • Objetivo: actualizar las business docs para reflejar lo que realmente se implementó
   • Output: actualizar docs/features/{module}/{name}-{type}.md existente
3. Mostrar diff al usuario y pedir confirmación

IF verify pasa limpio (todo COMPLIANT, sin divergencias): Skip corrección.

2. Documentación Técnica (solo core features o diagramas)

Evaluar contra la Documentation Policy table. Solo generar docs técnicas si el cambio:

• Introduce una core feature nueva (nuevo módulo, nuevo patrón arquitectónico, nueva capa)
• Requiere diagramas de arquitectura (sequence, ERD, flowchart, C4)
• Cambia estructura técnica significativa (patrones, contratos de API, schemas de BD)

IF aplica:

1. Lanzar technical-documenter sub-agent con:
   • Skill: technical-backend-documentation o technical-frontend-documentation (según repo afectado)
   • Skill adicional: mermaid-diagrams (si se necesitan diagramas)
   • Contexto: design.md + verify-report.md + código implementado + CLAUDE.md del repo
   • Output: docs/backend/technical/{module}/ o docs/frontend/technical/{module}/
2. Mostrar al usuario y pedir confirmación

IF el cambio es:

• Fix interno sin impacto en contratos, UI ni reglas → Skip
• Fix simple (typo, ajuste menor) → Skip
• Cambio que no introduce core features ni patrones nuevos → Skip

NO lanzar sdd-archive hasta confirmar que ambas evaluaciones se completaron.