Doc Spec Generator

python3 .agents/skills/doc-spec-generator/scripts/validate_references.py

3. Crear un Nuevo Documento spec/

Workflow guiado para crear un nuevo archivo en spec/ que sea parseable.

Paso 1: Estructura del documento

Todo documento spec/ DEBE seguir esta estructura:

# Título del Documento

**Proyecto:** Associated - ERP Ligero para Colectividades Españolas
**Versión:** 1.0
**Fecha:** {Mes} {Año}
**Inputs:** {documentos de entrada, ej: KB-003 (Requisitos Funcionales)}
**Estado:** {Borrador | Validado | Aprobado | Verificado}
**Total {Tipo}:** {N}

---

## Índice

1. [{Sección 1}](#{anchor})
2. [{Sección 2}](#{anchor})
...

---

## {Sección H2}

### {Código}: {Título}

{Contenido del item...}

---

### {Código}: {Título}

{Contenido del item...}

Requisitos críticos para el parser:

• El header H1 + metadatos van ANTES del primer H2.
• El Índice es una sección H2 cuyo título empieza con "Índice".
• Cada item tiene un heading con un código único seguido de : y título.
• Los items se separan opcionalmente con ---.

Paso 2: Patrones de heading por tipo de entidad

El parser divide por headings con regex. Cada tipo de entidad tiene su patrón:

IMPORTANTE: Si el heading no sigue exactamente el patrón, el parser NO lo detectará.

Paso 3: Campos de trazabilidad obligatorios

Cada tipo de entidad debe incluir campos de trazabilidad en su contenido:

RF:

### N{x}RF{yy}: {Título}

**Qué es:** {descripción}
**Problema que resuelve:** {problema}

RNF:

### RNF-{xxx}: {Título}

**Descripción:** {descripción}
**Criterios de aceptación:**
- {criterio 1}
- {criterio 2}
**Trazabilidad RF:** {N{x}RF{yy}, ...}

RNFT:

### {N}.{M} RNFT-{xxx}: {Título}

**RNF Base:** RNF-{xxx} ({nombre del RNF})
{Implementación técnica con código...}
**Métricas:**
- {métrica 1}

US:

#### US-{xxx}: {Título}
**RF Origen:** N{x}RF{yy}
**Prioridad:** {Must | Should | Could | Won't}

> Como **{rol}**,
> quiero {acción},
> para {beneficio}.

**Criterios de Aceptación:**
```gherkin
Scenario: {nombre}
  Given {contexto}
  When {acción}
  Then {resultado}

**UC:**
```markdown
### UC-{xxx}: {Título}

#### Metadatos
- **User Stories:** US-{xxx}, US-{yyy}
- **Bounded Context:** BC-{Name}
- **Application Service:** `{NombreService}`
- **Aggregates:** **{NombreAggregate}**
- **Prioridad:** {Must | Should | Could}

**Descripción:** {descripción}

#### Actores
#### Precondiciones
#### Flujo Normal
#### Flujos Alternativos
#### Flujos de Excepción
#### Domain Events Emitidos
#### Postcondiciones

Paso 4: Codificación secuencial

Para determinar el siguiente código disponible:

# Último RF de sección N4:
ls references/rf/n4rf*.md | sort | tail -1
# → n4rf38.md → siguiente: N4RF39

# Último RNF:
ls references/rnf/ | sort | tail -1
# → rnf-066.md → siguiente: RNF-067

# Último US:
ls references/us/ | sort | tail -1
# → us-202.md → siguiente: US-203

# Último UC:
ls references/uc/ | sort | tail -1
# → uc-076.md → siguiente: UC-077

Paso 5: Contexto de secciones padre

Los items H3/H4 heredan contexto de sus secciones H2 (y H3 para US):

## N4: Necesidades de Tesorería        ← contexto H2 para RFs H3

### N4RF01: Configuración de Cuotas     ← RF dentro de sección N4

## 3. BC-Treasury                       ← contexto H2 para USs

### 3.1 Configuración de Planes         ← contexto H3 para USs H4

#### US-042: Crear plan de cuota        ← US con contexto dual (H2 + H3)

El parser captura automáticamente este contexto y lo añade como blockquote al inicio del fragmento extraído.

4. Añadir Entidades a un Documento Existente

1. Leer el documento spec/ correspondiente para entender la estructura.
2. Usar doc-spec-manager para verificar reglas de consistencia y trazabilidad.
3. Añadir las nuevas entidades respetando el patrón de heading exacto.
4. Regenerar: python3 scripts/generate_all.py.
5. Verificar que los nuevos fragmentos aparecen en references/.

5. Añadir un Nuevo Tipo de Documento spec/

Si se crea un archivo completamente nuevo (ej. 011_nuevo.md):

1. Crear el documento siguiendo la estructura de Paso 1.
2. Crear extract_nuevo.py:
   • Importar lib_parser (split_by_heading o split_h2_sections).
   • Definir SPEC_FILE, HEADING_PATTERN, HEADING_LEVEL, OUTPUT_SUBDIR.
   • Implementar extract(spec_dir, output_dir) -> list[str].
3. Crear gen_head_nuevo.py:
   • Usar extract_header_block, extract_index_section, extract_trailing_sections.
   • Implementar generate(spec_dir, output_dir) -> str.
4. Registrar en generate_all.py (imports + listas).
5. Registrar en validate_references.py (ENTITY_TYPES + EXPECTED_HEAD_FILES).
6. Crear subdirectorio en references/ (se crea automáticamente en FRAGMENT_SUBDIRS).
7. Actualizar SKILL.md de doc-spec-manager con el nuevo tipo.
8. Ejecutar generate_all.py y verificar.

Mapeo Fuente → Fragmentos

Scripts

Ejecutar tests

python3 .agents/skills/doc-spec-generator/scripts/test_lib_parser.py

Principios de Diseño

• Determinismo: sin LLM, sin timestamps, sin estado. Idempotente.
• spec/ es la fuente de verdad: nunca editar references/ directamente.
• Code fence awareness: el parser ignora # dentro de bloques ```.
• Lowercase kebab-case: todos los nombres de archivo generados.