spec.md Unificado (SPEC-630)

SPEC-630 introdujo el formato unificado de spec.md, eliminando el archivo technical.md separado que Planu requería anteriormente. Esta página explica la motivación, la nueva estructura y cómo migrar specs existentes.

Contexto — Por qué Fusionamos technical.md

Antes de SPEC-630, cada spec vivía en dos archivos:

planu/specs/SPEC-NNN-my-feature/
  spec.md        ← criterios de aceptación + enunciado del problema
  technical.md   ← detalle de implementación, tipos, listas de archivos

Esto causaba tres problemas recurrentes:

1. Drift. Los criterios en spec.md evolucionaban pero technical.md no se actualizaba al mismo ritmo.
2. Desperdicio de contexto. Cargar ambos archivos consumía ~50–100 K tokens por solicitud, incluso para consultas simples.
3. Contaminación de placeholders. technical.md era a menudo un stub con separadores de doble guion (--) que las herramientas no podían distinguir del contenido real.

Después de SPEC-630: un único spec.md con una sección ## Technical al final.

La Sección ## Technical

La sección ## Technical sigue al último criterio de aceptación. Usa sub-encabezados consistentes que las herramientas de Planu saben buscar:

## Technical

### Files to create

- `src/feature/my-module.ts` — descripción breve
- `src/feature/my-module.test.ts` — tests unitarios

### Files to modify

- `src/index.ts` — exportar el nuevo módulo

### Implementation order

1. Crear tipos/interfaces
2. Implementar lógica principal
3. Agregar tests
4. Conectar exportaciones

### Key types / interfaces

​```ts
interface MyFeatureOptions {
  enabled: boolean
  timeout: number
}
​```

### Test stubs

​```ts
describe('myFeature', () => {
  it('should do X given Y', async () => {
    // TODO: implement
  })
})
​```

Las sub-secciones son opcionales

Incluye solo las sub-secciones que apliquen. Una spec tipo docs puede necesitar solo ### Files to create. Una spec de refactor puede necesitar ### Files to modify y ### Key types / interfaces.

Diff Antes / Después

 planu/specs/SPEC-NNN-my-feature/
-  spec.md          ← solo criterios
-  technical.md     ← archivo de implementación separado
+  spec.md          ← criterios + sección ## Technical unificados

Dentro del archivo, la diferencia se ve así:

 ## Acceptance Criteria
 
 **Scenario 1: ...**
 - GIVEN ...
 - WHEN ...
 - THEN ...
+
+## Technical
+
+### Files to create
+
+- `src/my-feature.ts` — implementación principal

Migrando Specs Existentes

Si tu proyecto tiene specs con un technical.md separado, usa la herramienta heal_spec_docs para migrarlas automáticamente:

# Migrar una spec individual
heal_spec_docs("SPEC-NNN")

# Migrar todas las specs del proyecto
heal_spec_docs("*")

Qué Hace heal_spec_docs

heal_spec_docs aplica las siguientes heurísticas:

1. Detección de placeholder. Si technical.md contiene solo separadores de doble guion (--) o está vacío, la herramienta lo considera un stub y lo elimina.
2. Fusión. Si technical.md tiene contenido real, la herramienta agrega una sección ## Technical a spec.md con ese contenido y luego elimina technical.md.
3. Validación. Después de la fusión, la herramienta ejecuta check_readiness para verificar que el archivo unificado sea coherente.

Revisión manual tras la migración

Siempre revisa la sección ## Technical fusionada después de ejecutar heal_spec_docs. Las fusiones automáticas preservan el contenido pero pueden reordenar sub-secciones.

---

Ver también

• Formato Lean de Spec — los campos de frontmatter que viven en la parte superior del mismo archivo
• Transiciones de Estado Automáticas — la cascada validate que comprueba los criterios unificados