Reconstrucción de fuentes
Cada píxel y cada frase de un video se verifican contra el código más tarde, por lo que el código debe ser el código correcto. En la producción de donde provienen estas habilidades, el checkout principal del frontend estaba unos dos meses atrasado respecto a producción mientras que el código actual estaba en otro worktree que nadie miró durante tres días. Se reconstruyeron tres versiones de un video a partir del código antiguo antes de que nadie se diera cuenta. Esta habilidad existe para que eso nunca vuelva a suceder: fija las fuentes primero, demuestra que están en producción, luego mapea las pantallas a los archivos.
Trabaja en modo solo lectura. Lees código; nunca editas, haces checkout, fetch ni creas worktrees en los repositorios del usuario. Su árbol de trabajo puede contener trabajo no confirmado, y un checkout o un fetch cambian un estado que no te pidieron que cambiaras.
1. Fijar las fuentes
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/source-recon/scripts/fetch_sources.py" <product_dir>
Lee sources: de product.yaml y, por rol:
url:clona superficialmente la rama ensources/.git-cache/<role>.gity la exporta.path:a un repositorio git:git archivedel más reciente entre<branch>yorigin/<branch>. Advierte cuando la rama local está detrás o ha divergido, cuando las referencias de origen se obtuvieron hace más de una semana, y cuando otro worktree del mismo repositorio es más reciente que la exportación.path:que no es un repositorio git: copiado y fijado por un hash de sus archivos ("pinned": false, por lo que las citas pueden quedar obsoletas sin previo aviso; prefiere una fuente git).
Las exportaciones se colocan en sources/<role>/, en modo solo lectura, y sources.lock registra el commit. Un rol
bloqueado que falta en el disco (una clonación reciente del repositorio del producto) se restaura en su commit
bloqueado, para que las citas sigan apuntando a las mismas líneas. Lee cada línea note: que imprime y actúa
en consecuencia antes de continuar: cada una es una forma en que la exportación podría no ser producción.
Las citas en todos los flujos descendentes usan <role>/<path>:<line>@<short sha>, donde la ruta es
relativa a la raíz del repositorio (por lo que sources/<role>/<path> existe) y el sha es el bloqueado.
2. Demostrar que es producción
Un nombre de rama no es una prueba. Producción es lo que el pipeline de despliegue construyó por última vez. Antes de mapear cualquier pantalla, establece qué commit está en vivo, en este orden de fuerza:
- Un registro de lanzamiento: una etiqueta de lanzamiento, un registro de despliegue, un archivo "último sha desplegado" en un repositorio de despliegue.
- La configuración del pipeline de despliegue: qué rama construye y sus argumentos de construcción (las variables de entorno incluidas en la construcción pueden cambiar la marca o ocultar características).
- La rama más nueva que el equipo confirma que está desplegada, verificada con
git worktree list, fechas de las ramas ymerge-base.
Lee references/freshness.md para los comandos exactos y las trampas (referencias remotas obsoletas, flags
de características, argumentos de construcción que cambian lo que se renderiza). Si no puedes confirmar el commit de producción,
menciónalo al principio de SOURCES.md ("commit de producción no confirmado") y haz al usuario una pregunta
cerrada con una respuesta recomendada, por ejemplo: "¿Exportar origin/develop (la más nueva, contiene
main) como producción? Recomendado: sí, es lo que construye el workflow de despliegue."
Cuando el usuario confirme una rama diferente, cambia branch: en product.yaml y ejecuta
fetch_sources.py <product_dir> --refresh --role <role> (si los videos ya citan esta fuente, ejecuta primero
changed_since.py, sección 6).
3. Mapear cada pantalla
Toma las pantallas y estados del BRIEF.md (capítulos) y COVERAGE.md del video. Lanza un
subagente de exploración de solo lectura por pantalla, o por pequeño grupo de pantallas que compartan componentes, en
paralelo. Dale a cada uno el mensaje en references/recon-prompt.md, apuntando a sources/<role>/
(la exportación fijada, nunca el checkout del usuario) para que cada número de línea que devuelva coincida con el bloqueo.
Cada subagente devuelve, con citas: la ruta, los componentes de página e hijos (plantilla, lógica, archivos de estilo), las claves i18n y sus cadenas exactas en el idioma del video, el estado que decide qué se renderiza (valores predeterminados, flags, barreras de características, estados vacíos, comprobaciones de permisos), los conjuntos de iconos y activos en uso, y cualquier cosa que parezca no lanzada, restringida o limitada.
Luego verifica la copia contra la producción tú mismo: verifica al azar dos o tres cadenas por pantalla contra cualquier referencia que tengas (una grabación, una captura recuperada, los documentos). Una cadena que difiere significa que la exportación no es producción o la pantalla está detrás de un flag; resuélvelo antes de escribir SOURCES.md.
4. Escribir SOURCES.md
Un archivo por video, en videos/<video>/SOURCES.md:
# Fuentes: <video>
Bloqueado: frontend main@1a2b3c4 (2026-01-12), backend main@5d6e7f8 (2026-01-10)
Producción: confirmado por <etiqueta de lanzamiento v4.2.0 | workflow de despliegue construye main | confirmación del equipo>
| pantalla | ruta | componentes | cita |
|---|---|---|---|
| Tablero, vacío | /board | BoardPage > TaskList > EmptyState | frontend/src/pages/board/BoardPage.tsx:14@1a2b3c4 |
## Tablero, vacío
- Cadenas: `board.empty.title` "Nada planeado aún" (frontend/src/i18n/en.json:88@1a2b3c4)
- Estado: se renderiza cuando `tasks.length === 0` (frontend/src/pages/board/TaskList.tsx:41@1a2b3c4)
- Iconos: lucide `calendar-plus` (frontend/src/pages/board/EmptyState.tsx:9@1a2b3c4)
- Banderas o barreras: ninguna encontrada
- No encontrado: <cualquier cosa que el brief necesite que el código no tenga>
## Referencias sin código
<lo que existe para cada pantalla sin código, ver sección 5>
Una pantalla sin cita no va en el video. Enumérala bajo "No encontrado" e informa al usuario; inventar una pantalla es el único error que los revisores no perdonan, porque muestra un producto que no existe.
5. Listar las referencias sin código
Para las pantallas que el código no puede mostrar (UI de terceros, salida en tiempo de ejecución, un backend que no está en los repositorios,
o ningún código de frontend), enumera lo que está disponible, en este orden de preferencia: grabaciones de pantalla
analizadas en references/, capturas recuperables de transcripciones de sesiones anteriores, una instancia
local de la aplicación construida como producción, documentos públicos y capturas de pantalla. No captures nada
tú mismo aquí; eso es ui-reference-capture. Nunca planifiques basándote en el navegador personal del revisor.
6. Cuando el código cambie
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/source-recon/scripts/changed_since.py" <product_dir> [--offline]
Compara cada commit bloqueado con la cabeza de la rama actual y lista cada video (y archivo kit)
cuyo SOURCES.md, TRUTH.md, especificaciones o video/src/ citen un archivo cambiado, marcando citas cuyas
líneas exactas cambiaron. No mueve nada. Ejecútalo antes de cualquier --refresh: compara el bloqueo con
la cabeza, y un refresco los iguala, por lo que después la lista de lo que cambió desaparece (el script
entonces imprime una pista en su lugar). Muestra esa lista al usuario, luego, si quieren el código nuevo,
ejecuta fetch_sources.py --refresh, vuelve a ejecutar ui-spec-from-code para las pantallas afectadas y
product-truth para las líneas afectadas. Los videos que no citen nada cambiado se dejan intactos.
Reglas y por qué
- Lee la exportación, cita el bloqueo. Los números de línea de un checkout diferente apuntan silenciosamente al código incorrecto después del siguiente refresco.
- Nunca imprimas secretos que encuentres en el código. Los frontends a menudo contienen claves y tokens. Reporta el archivo y la línea solamente, y trátalo como un hallazgo de seguridad para el usuario.
- Las características no lanzadas, restringidas o limitadas también son hechos. Márcalas en SOURCES.md
(
gate: <flag>,restricted: <quién lo ve>). product-truth decide si el video puede mostrarlas, normalmente con la aprobación del revisor. - Los datos reales se quedan fuera. Los fixtures y archivos de semillas en un repositorio pueden contener nombres reales de clientes. Cita su estructura, nunca sus valores.