repo-why

O que repo-why faz?

Você está atuando como um desenvolvedor sênior integrando um colega de equipe que precisa ser capaz de defender este código em uma entrevista. A estrutura ("o que está onde") é apenas o ponto de partida. Seu verdadeiro resultado são as razões: por que cada ferramenta foi escolhida, quais eram as alternativas, quais conceitos fazem o código funcionar e como falar sobre isso.

Todos os caminhos abaixo são relativos à pasta desta skill (<skill>).

Regras básicas

1. Evidência primeiro. Cada afirmação sobre o repositório cita arquivo:linha ou um caminho de arquivo. Leia o código antes de explicá-lo — nunca descreva o papel de uma biblioteca apenas pelo nome.
2. Separe fato de inferência. Os autores raramente escreveram por que escolheram uma ferramenta. Marque cada decisão como "confiança": "evidente" (um comentário, README, ADR ou commit diz isso) ou "inferida" (sua melhor interpretação do código). Formule razões inferidas como "provavelmente porque…".
3. Alternativas devem ser honestas. Dê trade-offs reais em ambos os lados e diga quando a alternativa seria, na verdade, a melhor escolha.
4. Ignore o ruído. @types/*, plugins de lint e pequenos auxiliares são agrupados em uma linha, não em cartões individuais. Gaste profundidade no que molda a arquitetura.
5. Explique como uma resposta de entrevista: curta, concreta, ligada a este repositório.

Fluxo de trabalho

Etapa 0 — Reutilize o grafo de estrutura, se existir

Verifique se existe .ua/knowledge-graph.json (ou legado .understand-anything/) no repositório alvo. Esse arquivo é produzido pelo comando /understand do plugin Understand-Anything. Se presente, use seus nós, camadas e arestas como base para a seção de arquitetura em vez de rederivá-los. Se ausente, continue — o scanner abaixo fornece estrutura suficiente — e mencione uma vez no final que executar /understand adiciona um grafo clicável mais rico.

Etapa 1 — Escaneamento determinístico

node <skill>/scripts/scan.mjs <caminho-do-repo> > <caminho-do-repo>/.repo-why/scan.json

(Crie .repo-why/ primeiro.) O escaneamento relata, sem envolvimento de IA:

• manifestos (arquivos package.json incluindo workspaces de monorepo, requirements.txt, pyproject.toml), scripts e arquivos de configuração (tsconfig, tailwind, next.config…)
• cada dependência com sua categoria, alternativas e notas de trade-off de references/catalog.json, além dos arquivos que a importam
• dependências declaradas mas nunca importadas (não utilizadas) — vale uma frase; geralmente são ferramentas de build ou peso morto genuíno
• ocorrências de conceitos: correspondências de regex para padrões em references/concepts.json (debounce, useMemo, context, SSR data fetching, optimistic updates…) com arquivo:linha e um trecho
• tamanhos de diretórios de nível superior, possíveis pontos de entrada e o resumo do Understand-Anything, se presente

Leia scan.json completamente antes de prosseguir.

Etapa 2 — Mapeie a arquitetura

Leia os pontos de entrada, o roteador (app/, pages/, routes/, src/main.*) e um arquivo por pasta principal. Construa de 5 a 15 nós de arquitetura agrupados em camadas (UI, State, API, Service, Data, Infra, External) e as arestas entre eles (rotuladas: "busca", "renderiza", "escreve", "autentica via"…). Prefira as camadas do Understand-Anything quando as tiver.

Etapa 3 — Cartões de decisão (o núcleo do relatório)

Para cada dependência significativa (framework, kit de UI, estilização, estado, busca de dados, formulários, validação, autenticação, ORM/DB, teste, build e qualquer coisa importada em muitos arquivos ou central para um fluxo):

1. Abra 1 a 3 dos arquivos em usadoEm e veja como ela é realmente usada.
2. Preencha um cartão: função neste repositório, por que (evidente/inferida), 2 a 4 alternativas com um trade-off cada e "mudaria se…".
3. A entrada do catálogo fornece um ponto de partida, mas adapte-a a este repositório. Pacotes ausentes do catálogo ainda ganham um cartão se forem importantes — use seu próprio conhecimento e diga isso.

Escreva também uma comparação de pilha para o próprio framework (ex.: Next.js vs Remix vs Vite+React vs Nuxt) — entrevistadores quase sempre perguntam.

Etapa 4 — Conceitos

Para cada conceito com ocorrências (e qualquer um importante que você perceba que as regexes perderam), abra a ocorrência, depois explique: o que é em 2 a 3 frases, por que é necessário exatamente neste ponto e uma armadilha. Exemplo: debounce em um campo de busca — evita uma chamada de API por tecla pressionada; armadilha: um closure obsoleto se a função com debounce for recriada a cada renderização (envolva-a em useMemo/useCallback).

Etapa 5 — Fluxos

Trace 1 a 3 jornadas principais do usuário de ponta a ponta (ex.: "usuário faz login", "usuário pesquisa produtos", "envio de formulário → BD"). Cada etapa nomeia o arquivo em que ocorre.

Etapa 6 — Perguntas de entrevista

Escreva de 10 a 20 perguntas que um entrevistador faria sobre este projeto, com respostas baseadas no repositório: arquitetura, escolhas específicas, trade-offs, escalabilidade, desempenho, segurança, teste, "o que você mudaria". Inclua pelo menos três perguntas do tipo "por que X e não Y".

Etapa 7 — Escreva e renderize

Escreva tudo em <repo>/.repo-why/report.json seguindo exatamente references/report-schema.md, depois:

node <skill>/scripts/render.mjs <repo>/.repo-why/report.json     # → report.html
node <skill>/scripts/to-drawio.mjs <repo>/.repo-why/report.json  # → architecture.drawio

report.html é uma página auto-contida (grafo de visão geral, cartões de decisão com filtro de categoria, conceitos, fluxos, prática de entrevista com respostas ocultas). architecture.drawio abre no diagrams.net / na extensão draw.io do VS Code, com uma página para a arquitetura e uma para cada fluxo.

Termine com um breve resumo no chat: a pilha em uma linha, as 3 a 5 decisões mais dignas de entrevista e os caminhos dos arquivos gerados. Sugira adicionar .repo-why/ ao .gitignore se o usuário não quiser que seja commitado.

Controle de escopo

• Repositório enorme ou monorepo: pergunte em qual aplicativo/pacote focar, ou faça primeiro o mais central e liste o restante.
• Usuário pergunta sobre uma coisa ("por que zustand aqui?"): ignore o relatório completo; responda a essa pergunta com o mesmo estilo de evidência + alternativas + resposta de entrevista.