Verdad del producto
Un video de producto que muestra algo que el producto no puede hacer es peor que ningún video. En la producción de la que provienen estas habilidades, los momentos más costosos fueron todos fallos de verdad: una insignia hecha a mano con el tamaño incorrecto y el nombre de producto incorrecto, un flujo de trabajo narrado como "esperando el resultado de la llamada" cuando el producto solo devuelve resultados a través de un disparador separado, una llamada de prueba reetiquetada como una reserva confirmada que nadie había verificado de principio a fin, y un documento de empresa cuyo titular contradecía el posicionamiento que el equipo había acordado. Cada uno se detectó tarde, por un revisor, y costó una versión.
Esta habilidad hace que la verificación sea explícita y mecánica: cada línea y cada pantalla obtienen una fila en
TRUTH.md con una fuente, y truth_check.py rechaza un video donde falte alguna fila, esté desactualizada o no tenga respaldo.
Entradas
videos/<video>/audio/lines.tsv(la narración, una oración por id de línea)videos/<video>/SOURCES.md(de source-recon: las pantallas y su código)videos/<video>/BRIEF.md,COVERAGE.md,CLAIMS.md(lo que el video debe explicar, el posicionamiento, frases a evitar, afirmaciones que necesitan aprobación)product.yaml:positioning,never_say,names(nombre canónico a cadenas heredadas),banned_termssources/<role>/ysources.lock(fijados por source-recon; si faltan, ejecuta source-recon primero, porque las citas deben apuntar al commit bloqueado)
1. Lista las afirmaciones
Divide cada línea de lines.tsv en las afirmaciones que hace. "Acme Tasks lee tu calendario y mueve las tareas vencidas a mañana" son dos afirmaciones: lee el calendario y mueve las tareas vencidas. Añade una afirmación por pantalla y por acción en pantalla de SOURCES.md y los capítulos ("Hacer clic en Planificar mi día abre el planificador con tres sugerencias").
Escribe las preguntas que esas afirmaciones plantean, formuladas para que el código pueda responderlas: qué desencadena esto, qué se almacena, qué opciones existen, qué ve el usuario y dónde, qué ocurre solo en el servidor.
2. Respóndelas desde el código y la documentación
Lanza subagentes de solo lectura en paralelo, uno por área de producto (comportamiento del frontend, cada backend,
documentación), con el prompt en references/product-facts-prompt.md. Apúntalos a sources/<role>/,
nunca al checkout del usuario, para que sus números de línea coincidan con el bloqueo. Responden solo desde el código
o la documentación, citan cada hecho y dicen "no encontrado" en lugar de adivinar.
3. Clasifica cada afirmación
| visibilidad | significa | el video puede |
|---|---|---|
ui | Renderizado por el frontend; cita la plantilla o la línea de i18n | mostrarlo y narrarlo |
backend | Verdadero en el servidor, nada en pantalla lo muestra | narrarlo, nunca dibujar una UI para ello |
docs | Solo la documentación lo dice | narrarlo con la URL de la documentación; verifica que el código esté de acuerdo cuando pueda |
mock | Una pieza diseñada, no UI del producto (una pantalla de llamada telefónica, una tarjeta final, texto generado) | mostrarlo, marcado como diseñado en el BRIEF |
| veredicto | significa |
|---|---|
backed | la fuente dice exactamente esto |
approved | necesitaba aprobación (restringido, no publicado, una afirmación que CLAIMS.md lista) y el revisor la dio en CLAIMS.md |
needs-approval | verdadero, pero restringido, con puerta, no publicado o listado en CLAIMS.md; esperando al revisor |
rewrite | parcialmente cierto; propones redacción respaldada en las notas |
cut | no es cierto, o no se encontró fuente |
unbacked | aún no verificado |
mock | solo con visibilidad mock |
Solo backed y approved pasan para las líneas narradas. Una función restringida (visible solo para algunos roles,
planes o equipos internos), una función detrás de una bandera o una en una rama no fusionada es
needs-approval hasta que el revisor diga que sí en CLAIMS.md, y el BRIEF señala que está
restringida. Eso ocurrió en la producción fuente: una función que solo el personal interno podía ver se
mostró a petición del revisor y se marcó.
4. Arregla lo que no se sostiene
- Reescribe una oración parcialmente cierta en la versión más sólida que la fuente admita. Mantén el significado que el escritor quería; cambia los mecanismos por los reales.
- Corta lo que no tiene fuente. No lo suavices en algo vago; las afirmaciones vagas siguen siendo afirmaciones.
- Nunca dejes que una etiqueta se desvíe. Una pieza diseñada marcada como "ilustrativa" no debe perder esa etiqueta por estética más tarde sin volver a verificar la afirmación que hace la versión sin etiqueta.
- El posicionamiento gana sobre los documentos. Si una presentación o PRD dice algo que
never_sayo CLAIMS.md prohíbe, la regla gana y la oración cambia. - Solo nombres actuales. Usa los nombres canónicos en
product.yaml names, incluso cuando la UI en vivo o el código todavía muestran una cadena heredada. Busca en lines.tsv, especificaciones y plantillas cada cadena heredada y cada entrada debanned_terms(competidores, proveedores externos que el equipo mantiene fuera de pantalla, clientes reales) y arregla cada coincidencia.
5. Cuando una solicitud entra en conflicto con el producto
Cuando el brief o el revisor pide algo que el código no admite, no construyas un falso y no lo elimines en silencio. Haz una pregunta cerrada con opciones y un valor recomendado por defecto, y mantén como máximo tres preguntas de este tipo por ronda, porque las listas abiertas de vetos quedan sin respuesta y el silencio se convierte en una decisión que nadie tomó. El patrón "solo lo real":
El brief muestra a Acme Tasks reservando la sala de reuniones por sí mismo. El código solo crea la tarea y enlaza el calendario de la sala (frontend/src/rooms/LinkRoom.tsx:22@1a2b3c4); la reserva ocurre en la aplicación de calendario. ¿Cuál opción?
- Solo lo real (recomendado): muestra el paso de enlace y di "enlaza el calendario de la sala".
- Muestra la pantalla de reserva de la aplicación de calendario como una pieza diseñada, etiquetada, y nárrala como el paso del calendario.
- Elimina el segmento.
Registra la respuesta en CLAIMS.md y establece el veredicto a partir de ella.
6. Escribe TRUTH.md
# Verdad: <video>
Bloqueado: frontend main@1a2b3c4, backend main@5d6e7f8. Verificado: 2026-01-12.
| id | oración | fuente | visibilidad | veredicto | notas |
|---|---|---|---|---|---|
| N1 | Acme Tasks planifica tu día desde tu calendario. | frontend/src/planner/plan.ts:31@1a2b3c4; https://docs.example.com/planner | ui | backed | |
| N2 | Las tareas vencidas se mueven a mañana a medianoche. | backend/jobs/rollover.py:12-30@5d6e7f8 | backend | backed | no se muestra en pantalla |
| screen:board | Tablero con tres tareas, una vencida | frontend/src/pages/board/BoardPage.tsx:14@1a2b3c4 | ui | backed | |
| screen:call | Llamada telefónica con el cliente | (diseñado) | mock | mock | marcado en BRIEF |
## Preguntas abiertas
1. <pregunta cerrada con una respuesta recomendada>
Una fila por id de línea de lines.tsv, con la oración copiada exactamente (la comparación las verifica, así que
editar una línea después de la pasada de verdad falla hasta que la vuelvas a verificar). Una fila por pantalla, con id
screen:<nombre> coincidiendo con SOURCES.md. Varias citas van en una celda, separadas por ;.
7. Verifícalo
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/product-truth/scripts/truth_check.py" <video_dir>
Falla en una línea sin fila, una oración cambiada, un veredicto distinto de backed o approved en una línea narrada, una cita cuyo rol no está bloqueado, cuyo sha no es el bloqueado (el código se movió; vuelve a verificar), cuyo archivo no está en la exportación, o cuya línea está más allá del final del archivo. Arregla cada fallo; no edites la verificación.
Informa al usuario: cuántas líneas y pantallas están respaldadas, qué reescribiste y cortaste (con el motivo), qué espera aprobación y las preguntas abiertas.