Reconhecimento de fontes
Cada pixel e cada frase de um vídeo são verificados posteriormente em relação ao código, então o código precisa ser o código certo. Na produção de onde essas skills vêm, o checkout principal do frontend estava cerca de dois meses atrasado em relação à produção, enquanto o código atual estava em outra worktree que ninguém olhou por três dias. Três versões de um vídeo foram reconstruídas a partir do código antigo antes que alguém percebesse. Esta skill existe para que isso nunca mais aconteça: fixe as fontes primeiro, prove que elas são de produção, depois mapeie as telas para os arquivos.
Trabalhe somente leitura. Você lê código; nunca edita, faz checkout, fetch ou cria worktrees nos repositórios do usuário. A árvore de trabalho deles pode conter trabalho não consolidado, e um checkout ou fetch altera um estado que eles não pediram para você alterar.
1. Fixar as fontes
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>
Ele lê sources: de product.yaml e, por função:
url:faz um shallow clone do branch emsources/.git-cache/<role>.gite o exporta.path:para um repositório git:git archivedo mais recente entre<branch>eorigin/<branch>. Ele avisa quando o branch local está atrasado ou divergiu, quando as refs de origin foram buscadas há mais de uma semana e quando outra worktree do mesmo repositório é mais nova que a exportação.path:que não é um repositório git: copiado e fixado por um hash de seus arquivos ("pinned": false, então as citações para ele podem ficar desatualizadas sem aviso; prefira uma fonte git).
As exportações vão para sources/<role>/, somente leitura, e sources.lock registra o commit. Uma função fixada que está faltando no disco (um clone recente do repositório do produto) é restaurada no commit fixado, para que as citações continuem apontando para as mesmas linhas. Leia cada linha note: que ele imprime e aja de acordo antes de continuar: cada uma é uma forma de a exportação não ser a de produção.
Citações em todo lugar downstream usam <role>/<path>:<line>@<short sha>, onde o caminho é relativo à raiz do repositório (então sources/<role>/<path> existe) e o sha é o fixado.
2. Provar que é produção
Um nome de branch não é prova. Produção é o que o pipeline de deploy construiu pela última vez. Antes de mapear qualquer tela, estabeleça qual commit está ativo, nesta ordem de força:
- Um registro de release: uma tag de release, um log de deploy, um arquivo "último sha de deploy" em um repositório de deploy.
- A configuração do pipeline de deploy: qual branch ele constrói e seus argumentos de construção (variáveis de ambiente incorporadas na construção podem alterar a identidade visual ou ocultar recursos).
- O branch mais novo que a equipe confirma que está implantado, verificado em relação a
git worktree list, datas de branch emerge-base.
Leia references/freshness.md para os comandos exatos e as armadilhas (refs remotas desatualizadas, feature flags, argumentos de construção que alteram o que é renderizado). Se você não puder confirmar o commit de produção, diga isso no topo do SOURCES.md ("commit de produção não confirmado") e faça ao usuário uma pergunta fechada com uma resposta recomendada, por exemplo: "Exportar origin/develop (mais novo, contém main) como produção? Recomendado: sim, é o que o workflow de deploy constrói."
Quando o usuário confirmar um branch diferente, altere branch: em product.yaml e execute fetch_sources.py <product_dir> --refresh --role <role> (se os vídeos já citarem esta fonte, execute changed_since.py primeiro, seção 6).
3. Mapear cada tela
Pegue as telas e estados do BRIEF.md do vídeo (capítulos) e COVERAGE.md. Inicie um subagente de Exploração somente leitura por tela, ou por pequeno grupo de telas que compartilham componentes, em paralelo. Dê a cada um o prompt em references/recon-prompt.md, apontado para sources/<role>/ (a exportação fixada, nunca o checkout do usuário) para que cada número de linha que ele retornar corresponda ao lock.
Cada subagente retorna, com citações: a rota, os componentes da página e filhos (arquivos de template, lógica, estilo), as chaves i18n e suas strings exatas no idioma do vídeo, o estado que decide o que é renderizado (padrões, flags, portões de recurso, estados vazios, verificações de permissão), os conjuntos de ícones e ativos em uso, e qualquer coisa que pareça não lançada, restrita ou bloqueada por portão.
Em seguida, verifique a cópia em relação à produção você mesmo: verifique duas ou três strings por tela em relação a qualquer referência que você tiver (uma gravação, uma captura recuperada, a documentação). Uma string diferente significa que a exportação não é a de produção ou a tela está atrás de uma flag; resolva isso antes de escrever o SOURCES.md.
4. Escrever SOURCES.md
Um arquivo por vídeo, em videos/<video>/SOURCES.md:
# Fontes: <video>
Fixado: frontend main@1a2b3c4 (2026-01-12), backend main@5d6e7f8 (2026-01-10)
Produção: confirmada por <tag de release v4.2.0 | workflow de deploy constrói main | confirmação da equipe>
| tela | rota | componentes | citação |
|---|---|---|---|
| Board, vazio | /board | BoardPage > TaskList > EmptyState | frontend/src/pages/board/BoardPage.tsx:14@1a2b3c4 |
## Board, vazio
- Strings: `board.empty.title` "Nada planejado ainda" (frontend/src/i18n/en.json:88@1a2b3c4)
- Estado: renderiza quando `tasks.length === 0` (frontend/src/pages/board/TaskList.tsx:41@1a2b3c4)
- Ícones: lucide `calendar-plus` (frontend/src/pages/board/EmptyState.tsx:9@1a2b3c4)
- Flags ou portões: nenhum encontrado
- Não encontrado: <qualquer coisa que o brief precise que o código não tem>
## Referências sem código
<o que existe para cada tela sem código, veja a seção 5>
Uma tela sem citação não vai para o vídeo. Liste-a em "Não encontrado" e avise o usuário; inventar uma tela é o único erro que os revisores não perdoam, porque mostra um produto que não existe.
5. Listar as referências sem código
Para telas que o código não pode mostrar (UI de terceiros, saída em tempo de execução, um backend que não está nos repositórios ou nenhum código frontend), liste o que está disponível, nesta ordem de preferência: gravações de tela analisadas em references/, capturas recuperáveis de transcrições de sessões passadas, uma instância local do aplicativo construída como produção, documentação pública e capturas de tela. Não capture nada você mesmo aqui; isso é ui-reference-capture. Nunca dependa do navegador pessoal do revisor.
6. Quando o código mudar
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/source-recon/scripts/changed_since.py" <product_dir> [--offline]
Ele diffa cada commit fixado em relação à cabeça atual do branch e lista cada vídeo (e arquivo de kit) cujo SOURCES.md, TRUTH.md, especificações ou video/src/ citem um arquivo alterado, marcando citações cujas linhas exatas mudaram. Ele não move nada. Execute-o antes de qualquer --refresh: ele compara o lock com a cabeça, e um refresh os torna iguais, então depois a lista do que mudou se foi (o script então imprime uma dica). Mostre essa lista ao usuário e, se quiserem o novo código, execute fetch_sources.py --refresh, reexecute ui-spec-from-code para as telas afetadas e product-truth para as linhas afetadas. Os vídeos que não citam nada alterado são deixados em paz.
Regras e porquês
- Leia a exportação, cite o lock. Números de linha de um checkout diferente apontam silenciosamente para o código errado após o próximo refresh.
- Nunca imprima segredos que você encontrar no código. Frontends geralmente contêm chaves e tokens. Relate apenas o arquivo e a linha e trate como uma descoberta de segurança para o usuário.
- Recursos não lançados, restritos ou bloqueados por portão também são fatos. Marque-os no SOURCES.md (
gate: <flag>,restricted: <quem vê>). O product-truth decide se o vídeo pode mostrá-los, geralmente com a aprovação do revisor. - Dados reais ficam de fora. Fixtures e arquivos de seed em um repositório podem conter nomes reais de clientes. Cite sua estrutura, nunca seus valores.