Specification Traceability

Trazabilidad de especificación funcional externa → código

Para qué existe. Cuando la especificación funcional no la escribimos nosotros —la entrega el cliente o la consultora, versionada, con identificadores propios— el trabajo no es diseñar: es demostrar, criterio a criterio, qué está cumplido y qué no, y de quién es lo que falta. Esta guía define los dos artefactos que sostienen esa demostración y las reglas que impiden que cada auditoría cueste lo mismo que la primera.

Cuándo aplica. Hay un documento funcional externo con identificadores (RF-, CA-, RNF-) y alguien va a preguntar «¿esto ya está?». Si la spec la escribimos nosotros, el camino es el contrario y manda arch-doc-spec.md y adr.md.

Guías compañeras: spec-funcional.md (anatomía del documento funcional) · testing.md (cómo se prueba un criterio) · adr.md (cuando el hueco es una decisión).

1. La cadena

1
Funcional externo (vNN)  →  Especificación técnica  →  Código  →  Matriz de cobertura
2
   RF-XX-01                   RF → componente           clase       CA-XX-01 ✅ + evidencia
3
   CA-XX-01                                             test

Cuatro eslabones, y cada uno cruza por identificador. Si el identificador no cruza, la cadena está rota aunque las cuatro piezas existan.

Deriva real medida: la especificación técnica de abonos escribe CA-AB-001 (tres dígitos) y el funcional escribe CA-AB-01 (dos). Ninguna verificación automática cruza esa frontera, y la trazabilidad parece completa cuando no lo es.

Regla: el identificador se escribe exactamente como lo escribe el funcional vigente. En la técnica, en el código, en los tests y en los commits. Sin ceros de relleno, sin variantes.

2. Regla de vigencia — qué documento mide

Manda un solo documento, y se nombra. El resto es historia del porqué, no medida de cumplimiento.

Sin esta regla, cada auditoría vuelve a discutir si el código incumple la técnica o si la técnica quedó atrás. Es discusión sin final: la técnica siempre queda atrás.

3. Artefacto A — matriz de cobertura criterio por criterio

Fichero: cobertura-criterio-por-criterio-<vNN>.md, junto a la spec.

Cabecera obligatoria

Módulo · fecha de corte · número de revisión · resultado del build verificado en ese corte (./mvnw verify exit 0, con el commit). Un corte sin build verificado no es un corte.

Y un bloque «qué cambió respecto del corte anterior», y sólo eso. Es lo que hace que la revisión número nueve se lea en dos minutos.

Secciones

Veredictos

⚠️ es el veredicto que más trabajo ahorra: distingue “está programado” de “funciona”. Sin él, un catálogo creado y vacío pasa por verde.

Una fila

1
| `CA-AB-01` | ✅ | `RecibirNotificacionUseCase`, `V2`, `NotificacionAbonoControllerIT` |

Evidencia = ficheros que existen. Nada más.

Medir una cosa por casilla

La fila de trazabilidad mide una sola cosa: que el identificador aparezca citado en src/. No mezclar con “tiene escenario” ni con “está probado”. Un corte anterior de abonos decía HU-AB 8/8 mezclando dos medidas, y dos medidas en una casilla no se pueden auditar.

4. Las seis reglas de auditoría

Se copian dentro del documento, no se enlazan. Existen porque una auditoría sin línea base ni criterio de parada vuelve a resolver todos los criterios cada vez y produce hallazgos que no lo son.

1. Sólo se audita el funcional vigente.
2. Se compara contra la matriz anterior, no se re-deriva. Un criterio que nadie tocó no se vuelve a resolver. Se reporta lo que cambió respecto del corte previo.
3. Una ausencia no se afirma sin verificarla dos veces. Que un identificador no aparezca en el código es información, no veredicto: se confirma leyendo la implementación, no el grep.
4. Un veredicto nombra su evidencia. Una fila ✅ sin fichero que la sostenga es una opinión.
5. Lo que depende de un tercero se queda en rojo con su identificador al lado. No se marca verde lo que no ejecutamos, aunque la puerta exista y funcione en el pom.xml.
6. Cuando cambia la versión del funcional: primero el delta, después la matriz. Rebasear sin delta es volver a resolverlo todo — justo lo que la regla 2 prohíbe.

El corolario de la regla 6

Un identificador puede cambiar de significado entre versiones sin cambiar de nombre. En abonos, S-05 era el contrato de respuesta en v19 y es la ventana de retención del duplicado en v20. Al rebasear se comprueban también los identificadores que no aparecen en la lista de cambios.

5. Los huecos, con dueño

La sección de mayor valor operativo, y la entrada natural de /tasking.

1
| Hueco | Bloqueo | Dueño |
2
|:--|:--|:--|
3
| `CA-XX-27a` | Qué forma tiene el asiento cuando el payload no trae cliente ni monto. Ni el funcional ni Ledger_v1 §2.2 lo dicen. El transporte está construido | Producto + Ledger |
4
| ~~`CA-XX-16`~~ | **Cerrado el 2026-09-08** | — |

Tres reglas:

• Un hueco cerrado no se borra: se tacha con su fecha. Borrarlo hace que la siguiente revisión lo vuelva a investigar.
• El dueño es un equipo, no una persona, y va siempre. Un hueco sin dueño es un hueco sin destinatario.
• Distinguir “falta código” de “falta contrato”. Si lo que falta es que un tercero defina algo, construirlo es adjudicar en nombre de otro. Se queda en rojo y se manda.

Marca los huecos nuevos del corte (🆕) para que el lector no los busque.

6. Artefacto B — delta entre versiones del funcional

Fichero: delta-funcional-<vN>-a-<vM>.md. Se escribe antes de rebasear la matriz.

Cabecera: módulo · corte · las dos fuentes con sus fechas · build verificado.

Se recorre bloque por bloque y cada cambio cae en uno de cinco cubos:

Cierra con dos secciones: efecto sobre la matriz de cobertura (qué veredictos se mueven y por qué) y orden propuesto (en qué secuencia atacar lo que abrió).

El resumen va arriba, en una tabla de cuentas: 60 bloques cambiados, 3 identificadores nuevos, ninguno retirado. Es lo que permite decidir si el delta es asumible antes de leerlo entero.

7. Disparadores

Se rehace la matriz cuando: cambia el funcional · se toca el código de un requisito · hay auditoría externa. Nada más. Una matriz que se rehace “por si acaso” deja de tener línea base.

8. Registro de identificadores

El funcional define sus prefijos en su propia tabla (ver spec-funcional.md). Lo que nosotros añadimos encima necesita su propio registro, y es donde aparece la deriva:

Todo prefijo que usemos se define en una tabla del documento donde aparece. En la técnica de abonos conviven P-01…P-08 y B-02…B-07 en una sola tabla titulada «Pendientes Críticos», y ninguno de los dos está definido en la guía de identificadores. El lector no puede saber si son lo mismo.

B- y D- no son intercambiables: B- bloquea el diseño (no sabemos qué construir), D- bloquea la ejecución (sabemos qué construir, falta que alguien lo encienda).

9. Anti-patrones

10. Checklist antes de publicar un corte

• El funcional vigente está nombrado y es el único que mide
• ./mvnw verify verificado en este corte, con el commit anotado
• Cabecera «qué cambió respecto del corte anterior», y sólo eso
• Cada ✅ nombra evidencia, y cada fichero citado existe
• Lo inerte está en ⚠️, no en ✅
• Cada hueco tiene dueño; los cerrados están tachados con fecha
• Si cambió la versión del funcional, el delta está escrito y se comprobaron los identificadores que no aparecen en su lista de cambios
• Las seis reglas están copiadas dentro del documento
• Los prefijos usados están definidos en una tabla del propio documento