Adquirir Conhecimento da Base de Código

Produz sete documentos preenchidos em docs/codebase/ cobrindo tudo o que é necessário para trabalhar efetivamente no projeto. Documente apenas o que é verificável a partir de arquivos ou saída do terminal — nunca infira ou assuma.

Contrato de Saída (Obrigatório)

Antes de finalizar, tudo o que segue deve ser verdadeiro:

1. Exatamente estes arquivos existem em docs/codebase/: STACK.md, STRUCTURE.md, ARCHITECTURE.md, CONVENTIONS.md, INTEGRATIONS.md, TESTING.md, CONCERNS.md.
2. Cada afirmação é rastreável a arquivos de origem, configuração ou saída do terminal.
3. Desconhecidos são marcados como [TODO]; decisões dependentes de intenção são marcadas [ASK USER].
4. Cada documento inclui uma curta lista de "evidências" com caminhos de arquivo concretos.
5. A resposta final inclui perguntas numeradas [ASK USER] e divergências entre intenção e realidade.

Fluxo de Trabalho

Copie e acompanhe esta lista de verificação:

- [ ] Phase 1: Run scan, read intent documents
- [ ] Phase 2: Investigate each documentation area
- [ ] Phase 3: Populate all seven docs in docs/codebase/
- [ ] Phase 4: Validate docs, present findings, resolve all [ASK USER] items

Modo de Área de Foco

Se o usuário fornecer uma área de foco (por exemplo: "apenas arquitetura" ou "testes e preocupações"):

1. Execute sempre a Fase 1 por completo.
2. Conclua totalmente os documentos da área de foco primeiro.
3. Para documentos não focados ainda não analisados, mantenha as seções necessárias presentes e marque desconhecidos como [TODO].
4. Ainda execute o loop de validação da Fase 4 em todos os sete documentos antes da saída final.

Fase 1: Escanear e Ler Intenção

1. Execute o script de escaneamento a partir da raiz do projeto alvo:

   python3 "$SKILL_ROOT/scripts/scan.py" --output docs/codebase/.codebase-scan.txt
   

   Onde $SKILL_ROOT é o caminho absoluto para a pasta da skill. Funciona em Windows, macOS e Linux.

   Início rápido: Se você tiver o caminho em linha:

   python3 /absolute/path/to/skills/acquire-codebase-knowledge/scripts/scan.py --output docs/codebase/.codebase-scan.txt
   

2. Procure por arquivos PRD, TRD, README, ROADMAP, SPEC, DESIGN e leia-os.

3. Resuma a intenção declarada do projeto antes de ler qualquer código-fonte.

Fase 2: Investigar

Use a saída do escaneamento para responder a perguntas para cada um dos sete modelos. Carregue references/inquiry-checkpoints.md para a lista completa de perguntas por modelo.

Se a pilha for ambígua (múltiplos arquivos de manifesto, tipos de arquivo desconhecidos, sem package.json), carregue references/stack-detection.md.

Fase 3: Preencher Modelos

Copie cada modelo de assets/templates/ para docs/codebase/. Preencha nesta ordem:

1. STACK.md — linguagem, runtime, frameworks, todas as dependências
2. STRUCTURE.md — layout do diretório, pontos de entrada, arquivos chave
3. ARCHITECTURE.md — camadas, padrões, fluxo de dados
4. CONVENTIONS.md — nomenclatura, formatação, tratamento de erros, imports
5. INTEGRATIONS.md — APIs externas, bancos de dados, autenticação, monitoramento
6. TESTING.md — frameworks, organização de arquivos, estratégia de mock
7. CONCERNS.md — débito técnico, bugs, riscos de segurança, gargalos de performance

Use [TODO] para qualquer coisa que não possa ser determinada pelo código. Use [ASK USER] onde a resposta correta requer a intenção da equipe.

Fase 4: Validar, Reparar, Verificar

Execute este loop de validação obrigatório antes de finalizar:

1. Valide cada documento contra references/inquiry-checkpoints.md.
2. Para cada afirmação não trivial, confirme se existe pelo menos uma referência de evidência.
3. Se alguma seção obrigatória estiver faltando ou não suportada:

• Corrija o documento.
• Reexecute a validação.

4. Repita até que todos os sete documentos passem.

Em seguida, apresente um resumo de todos os sete documentos, liste cada item [ASK USER] como uma pergunta numerada e destaque quaisquer divergências entre Intenção vs. Realidade da Fase 1.

Critérios de aprovação da validação:

• Nenhuma afirmação não suportada.
• Nenhuma seção obrigatória vazia.
• Desconhecidos usam [TODO] em vez de suposições.
• Lacunas de intenção da equipe são explicitamente marcadas [ASK USER].

Armadilhas

Monorepos: A raiz package.json pode não ter código-fonte — verifique por diretórios workspaces, packages/ ou apps/. Cada workspace pode ter dependências e convenções independentes. Mapeie cada subpacote separadamente.

…