Version: 1.0 · Fecha: 2026-04-20
Aplicas este contexto cuando NO existe una HU V1 previa sobre la funcionalidad que necesitas documentar. Casos típicos:
Si ya hay una HU V1 en PDF, no uses este contexto — usa el Contexto 2.
El template obliga a definir primero el wireframe de cada pantalla. A partir del wireframe se derivan:
No puedes escribir ninguna RN que no se apoye en un elemento del wireframe. Si lo haces, la validación Fase E lo detecta como huérfano.
TEMPLATE_HU_V2_BLANK.yamlEl template vive en Documentation/centrica/11_Backlog/02_Templates/TEMPLATE_HU_WIREFRAME_FIRST.yaml.
Se copia, renombra y rellena. Tiene 5 secciones obligatorias:
metadata:
codigo: "HU-CON-023" # HU-<MOD>-<NNN>
titulo: "Anulación de Diferidos"
modulo: "Contabilidad"
submodulo: "Operaciones Específicas"
version: "1"
fecha: "25/04/2026"
responsable: "Pérez Rodríguez"
complejidad: "Alta"
prioridad: "2 de 5"
descripcion:
como: "Contador que gestiona diferidos contables"
quiero: "Anular un diferido registrado y revertir su efecto en saldos"
para: "Corregir errores de causación sin impacto en cierres contables"
Por cada alcance (pantalla principal + sus modales/secciones):
alcances:
- numero: 1
detalle_titulo: "DETALLE FUNCIONAL DEL SUB-MÓDULO O INTERFAZ Listado de Diferidos"
fns:
- id: FN-ALC1-01
texto: "Mostrar el listado de diferidos del mes con filtros..."
ints:
- id: INT-ALC1-01
nombre: "Listado de Diferidos"
layout: # EL WIREFRAME — obligatorio
type: list_view # list_view | form | modal | detail | wizard
header:
search: true
search_value: "Buscar diferido..."
date_range: true
date_from: "01/04/2026"
date_to: "30/04/2026"
table:
columns: [...]
rows:
- cells: [...]
actions_per_row: [view, edit, delete]
floating_action: "Nuevo Diferido"
pagination: { total: 45 }
campos: # derivados del wireframe
- nombre: "..."
tipo: "..."
obligatorio: "..."
formato: "..."
validacion: "..."
comportamiento: "..."
rns:
- id: RN-ALC1-01
texto: "FN-ALC1-01 <descripción>"
cas:
- id: CA-ALC1-01
texto: "Dado ... Cuando ... Entonces ... Y aplica RN-ALC1-01 Y aplica INT-ALC1-01"
anexos:
- id: ANX-01
descripcion: "Diagrama de flujo del proceso de anulación"
Cada INT declara su layout.type. Elige según la pantalla:
| Tipo | Para qué | Cuándo usarlo |
|---|---|---|
list_view |
Pantallas de listado con tabla | Todas las pantallas principales de consulta (ej. "Listado de Documentos Causados") |
form |
Formularios agrupados en tarjetas + tabla opcional | Creación/edición con múltiples secciones y/o tabla de detalle (ej. "Nueva Causación") |
modal |
Ventanas emergentes con campos + tabla opcional | Modales de búsqueda, edición puntual, configuración (ej. "Formato Contable", "Diferido") |
detail |
Vista de solo lectura en grid | Pantalla de consulta con valores pre-cargados |
wizard |
Multi-paso con indicador de progreso | Procesos lineales de 3–5 pasos |
Ejemplos reales (ver piloto HU-CON-012):
INT-ALC1-01 Listado de Causaciones → list_viewINT-ALC2-01 Datos de la Factura → form + tabla de artículosINT-ALC2-02 Causación Contable → form + tabla de asientoINT-ALC2-03 Formato Contable → modal con 8 camposINT-ALC2-05 Diferido → modal con 8 campos + tabla de centros de costoAntes de pasar el YAML a la Fase D del pipeline, verifica:
Como / Quiero / Para.layout: completo.layout: tiene su bloque campos: con al menos los mismos elementos del wireframe.Dado ... Cuando ... Entonces ... Y aplica RN-... Y aplica INT-....VARCHAR, CHAR, NUMERIC) — solo tipos funcionales (Texto, Fecha, Numérico, Lista, Alfanumérico).APPROVED, REJECTED, PENDING, CANCELLED, ACTIVE, INACTIVE).Sí / No).DD/MM/YYYY.cp Documentation/centrica/11_Backlog/02_Templates/TEMPLATE_HU_WIREFRAME_FIRST.yaml \
Documentation/centrica/11_Backlog/04_Historias_Cliente/HU-<COD>/hu_spec.yaml
Para cada pantalla del proceso, en este orden:
type (list_view / form / modal / detail / wizard).cd Documentation/centrica/11_Backlog/03_Prompts/scripts
.venv/bin/python3 05_render_wireframe.py ./layouts/INT-ALC1-01.yaml ./_rendered/INT-ALC1-01.png
Por cada INT, rellena el bloque campos: con los elementos visibles. Usa esta tabla de formato por tipo:
| Tipo campo | formato típico | validacion típica |
|---|---|---|
| Texto / Alfanumérico | "Máximo N caracteres" | "Sí, ''" o "No" |
| Numérico | "Máx 15, 2 decimales" | "Mayor a cero" |
| Fecha | "DD/MM/YYYY" | "No puede ser mayor a hoy" |
| Lista / Dropdown | "Valor1 / Valor2 / Valor3" | "Sí, 'Debe seleccionar una opción'" |
Regla mnemotécnica:
Plantilla Gherkin estándar:
Dado que <precondición>,
Y <condición adicional opcional>,
Cuando <acción del usuario>,
Entonces <resultado esperado observable>,
Y aplica RN-ALCn-## [, Y aplica INT-ALCn-##].
Tu YAML es la entrada directa del Contexto 2 a partir de la Fase D:
cd Documentation/centrica/11_Backlog/03_Prompts/scripts
.venv/bin/python3 04_generate_docx.py \
../../04_Historias_Cliente/HU-<COD>/hu_spec.yaml \
../../04_Historias_Cliente/HU-<COD>/ \
../../04_Historias_Cliente/HU-<COD>/HU-<COD>-V2.docx
.venv/bin/python3 03_validate_v2.py \
../../04_Historias_Cliente/HU-<COD>/HU-<COD>-V2.docx \
--output ../../04_Historias_Cliente/HU-<COD>/reporte_validacion.md
Abre HU-<COD>-V2.docx en WPS Office y usa Archivo → Exportar → PDF.
QA aplica el gate final con PROMPT_VALIDACION_HU.md (7 dimensiones). Si PROCESABLE, se cierra la HU y pasa a downstream.
Ver un YAML válido completo con 1 alcance y 1 INT (list_view) en TEMPLATE_HU_WIREFRAME_FIRST.yaml.
| Error | Síntoma | Solución |
|---|---|---|
| FN sin RN | Validador E1 marca FN huérfana | Escribir ≥1 RN que cite la FN en su texto |
| RN sin CA | Validador E1 marca RN huérfana | Escribir ≥1 CA con Y aplica RN-ALCn-## |
| Campo en tabla no aparece en layout | Validador E2 detecta campo sin origen | Agregar el campo al wireframe o quitarlo de la tabla |
| Gherkin malformado | Validador E4 falla (falta Dado/Cuando/Entonces) | Usar la plantilla Gherkin del Paso 4 |
Layout modal con muchos campos se corta |
Imagen PNG resulta incompleta | Usar form en lugar de modal si hay > 8 campos |
| Nombres SQL en descripción | QA 7-dimensiones rechaza | Reemplazar por descripciones funcionales |
Si tienes acceso a Claude, puedes acelerar la redacción:
/crear-hu-cero (ver 05_CONFIGURACION_CLAUDE): te pide la pantalla descripción y genera un borrador de hu_spec.yaml con layouts y campos inferidos.renderer-hu: te renderiza cada wireframe en el DOCX de salida según el YAML.Sin Claude, el proceso es manual pero funciona igual.
| Version | Fecha | Autor | Descripcion |
|---|---|---|---|
| 1.0.0 | 2026-04-20 | Carlos Torres | Contexto 1 inicial |