Version: 1.0 · Fecha: 2026-04-20
Aplicas este contexto cuando ya existe una HU V1 cruda entregada por consultoría y necesitas llevarla al formato V2 aprobado por QA (identidad visual Nebula v1.4, estructura tabular por alcance, Gherkin, identidad corporativa).
Casos típicos:
HU-CON-013, 014, 016, 018, 019, 020, 021).Si no hay HU V1 previa, usa el Contexto 1.
El Contexto 2 es un pipeline automatizado con una única intervención humana obligatoria en la Fase C (gate de mapeo). Todo lo demás es determinístico o LLM-driven sin intervención.
Entrada: V1.pdf + Anexos
│
▼
Fase A · EXTRACCIÓN (scripts deterministas)
│ pdftotext + pdfimages + parser regex
│ → extracted.yaml (metadata, campos, RN, CA, mockups)
▼
Fase B · WIREFRAMES (LLM-vision)
│ Cada mockup PNG → Claude Sonnet 4.6 (vision)
│ → catalog-interfaces.yaml (INTs con campos, botones, tablas)
▼
Fase C · MAPEO (LLM-texto + gate humano) ⚠ GATE C4
│ Cruza extracted + catalog, asigna cada item a un INT
│ → mapping.yaml con items ambiguos marcados
│ → Arquitecto humano revisa y firma → mapping-approved.yaml
▼
Fase D · SÍNTESIS (templates + python-docx + WeasyPrint)
│ Aplica templates D4/D5 + renderiza wireframes Nebula
│ → HU-<COD>-V2.docx (con PNGs embebidos)
▼
Fase E · VALIDACIÓN (scripts deterministas) ⚠ GATE E5 QA
│ Grafo FN↔RN↔CA↔INT + cobertura V1→V2 + Gherkin
│ → reporte_validacion.md
│ → QA aplica PROMPT_VALIDACION_HU (7 dimensiones)
▼
Salida: HU-<COD>-V2.docx + PDF (export WPS)
Detalle completo en 03_FASES_PIPELINE.
Antes de iniciar el pipeline, verifica:
HU-CON-013 depende de HU-CON-012).cd Documentation/centrica/11_Backlog/04_Historias_Cliente
mkdir -p HU-CON-013
cd HU-CON-013
# Copia manualmente los PDFs a esta carpeta o usa rutas absolutas en los scripts
/ruta/a/scripts/01_extract_hu.sh \
"/ruta/a/HU-CON-013-V1.pdf" \
"/ruta/a/Anexo 1 Flujo.pdf" \
"/ruta/a/Anexo 2 Casos Prueba.pdf" \
./fase_A
Produce:
./fase_A/
hu-v1.txt
anexo1.txt
anexo2.txt
wireframes/*.png ← mockups candidatos
wireframes_anexo1/*.png ← mockups del anexo
sections.tsv
ids_detectados.tsv
extraction.log
Luego:
/ruta/a/scripts/.venv/bin/python3 /ruta/a/scripts/02_parse_hu.py ./fase_A \
--pdf-name "HU-CON-013-V1.pdf"
Produce ./fase_A/extracted.yaml con todo estructurado.
Revisa extracted.yaml y corrige manualmente errores de parsing (típicamente nombres de campo truncados o metadata con ruido).
Opción A — con Claude Code (automatizado):
claude /pipeline-fase-b ./fase_A/wireframes_anexo1/
Esto invoca el subagente wireframe-interpreter (ver 05_CONFIGURACION_CLAUDE) que produce ./fase_B/catalog-interfaces.yaml.
Opción B — manual con Claude API / web:
Por cada mockup PNG, aplica el prompt de Fase B de PROMPT_PIPELINE_HU_V1_V2.md.
Ejemplo de uso directo con Claude Sonnet 4.6:
<prompt de Fase B>
[adjuntar imagen wireframes_anexo1/anx-001.png]
Consolida las salidas en un único catalog-interfaces.yaml.
Aplica el prompt de Fase C sobre extracted.yaml + catalog-interfaces.yaml:
<prompt de Fase C>
extracted.yaml:
...
catalog-interfaces.yaml:
...
Claude produce mapping.yaml con items marcados ambiguo: true.
⚠ GATE C4 obligatorio: tú como arquitecto revisas cada item ambiguo y tomas decisión. Esto no se puede saltar porque es donde se decide a qué INT pertenece cada campo / RN / CA cuando no hay evidencia suficiente.
Al terminar, guardas mapping-approved.yaml con las decisiones firmadas.
Con el mapeo aprobado, genera el YAML completo hu_spec.yaml:
<prompt de Fase D>
mapping-approved.yaml:
...
extracted.yaml:
...
Claude produce hu_spec.yaml con todos los alcances, INTs, layouts, campos, FN, RN, CA.
Luego genera el DOCX:
/ruta/a/scripts/.venv/bin/python3 /ruta/a/scripts/04_generate_docx.py \
./hu_spec.yaml \
./fase_A \
./HU-CON-013-V2.docx
Esto invoca internamente 05_render_wireframe.py por cada INT con layout:, generando los PNGs estandarizados Nebula y embebiéndolos en el DOCX.
/ruta/a/scripts/.venv/bin/python3 /ruta/a/scripts/03_validate_v2.py \
./HU-CON-013-V2.docx \
--v1-yaml ./fase_A/extracted.yaml \
--output ./reporte_validacion.md
Produce reporte con 4 criterios:
⚠ GATE E5: QA aplica adicionalmente PROMPT_VALIDACION_HU.md (7 dimensiones) y firma.
Abre HU-CON-013-V2.docx en WPS Office → Archivo → Exportar → PDF.
Guarda el log de la ejecución en _pipeline_runs/HU-CON-013/YYYY-MM-DD.log con:
Ver formato en 07_VALIDACION_Y_AUDITORIA.
| Fase | Tiempo automatizado | Tiempo humano |
|---|---|---|
| A · Extracción | 30 seg | 5 min (revisar extracted.yaml) |
| B · Wireframes | 2–3 min (LLM-vision) | 5 min (revisión) |
| C · Mapeo | 3 min (LLM-texto) | 15–30 min (GATE C4 obligatorio) |
| D · Síntesis | 15 seg (script) + 3 min (LLM) | 10 min (revisión) |
| E · Validación | 2 seg (script) | 10 min (revisión) + 15 min QA |
| Export PDF | — | 2 clics en WPS |
| Total | ~10 min | ~1 hora humano |
Tiempo calendario total esperado: 1–1.5 días (incluyendo iteraciones si hay ambigüedad).
./fase_A/ # insumos extraídos
hu-v1.txt
anexo1.txt
anexo2.txt
extracted.yaml # ⭐ input para B y C
wireframes/*.png
wireframes_anexo1/*.png
./fase_B/
catalog-interfaces.yaml # ⭐ interfaces detectadas
./fase_C/
mapping.yaml # salida LLM
gate_c4_log.md # log de decisiones humanas
mapping-approved.yaml # ⭐ firmado por arquitecto
./hu_spec.yaml # ⭐ spec completa consolidada
./HU-<COD>-V2.docx # ⭐⭐ ENTREGABLE
./HU-<COD>-V2.pdf # ⭐⭐ ENTREGABLE (export WPS)
./reporte_validacion.md # ⭐ gate E
./_rendered/*.png # wireframes Nebula generados
./pipeline_run.log # auditoría completa
Ver 05_CONFIGURACION_CLAUDE para el detalle. Los skills/subagents Claude Code que aceleran este contexto:
| Comando | Rol |
|---|---|
/reprocesar-hu <CODIGO> |
Ejecuta todo el pipeline A→E de forma orquestada |
/pipeline-fase-a <pdf> |
Solo extracción |
/pipeline-fase-b <mockups_dir> |
Solo interpretación de wireframes |
/pipeline-fase-c <extracted> <catalog> |
Solo mapeo + gate C4 |
/pipeline-fase-d <hu_spec> |
Solo síntesis DOCX |
/pipeline-fase-e <docx> |
Solo validación |
/validar-hu <docx> |
Atajo a gate E5 (7 dimensiones) |
Si los wireframes del V1 son solo descripciones narrativas (sin PNG), la Fase B se bloquea. Opciones:
requiere_validacion_consultor: true en cada INT inferido.La Fase D regenera las CAs en Gherkin estricto a partir de las RN. La CA textual del V1 se mantiene como semilla pero el formato final lo produce el pipeline.
El pipeline despinta las referencias técnicas (ej. MAE_DIFERIDOS → maestro de diferidos) en la salida V2. La Fase C marca estas referencias como ítems a despintar.
La Fase C detecta estados heterogéneos y los normaliza a los canónicos (APPROVED, REJECTED, etc.). Si hay ambigüedad sobre el mapeo, queda para el gate C4.
Fase C marca duplicados con ambiguo: true. En C4, el arquitecto decide cuál es la correcta. La RN descartada queda en el log de auditoría, no se pierde evidencia.
Ejecutar el pipeline dos veces sobre la misma entrada produce exactamente el mismo DOCX (mismo checksum). Esto se garantiza por:
temperature=0.Si el DOCX cambia entre ejecuciones, es un bug del pipeline y se debe reportar en Issues.
| Version | Fecha | Autor | Descripcion |
|---|---|---|---|
| 1.0.0 | 2026-04-20 | Carlos Torres | Contexto 2 inicial |