repo-auditor
Skill de auditoria inicial e continua do repositorio. Use quando precisar mapear stack real, convencoes, assets, testes, docs, riscos e pontos de integracao antes de executar outras skills. O resultad
SKILL.mdskills/18-repo-auditor/SKILL.md
GitHubRepo Auditor
O Repo Auditor cria uma fotografia operacional do repositorio para que o restante do sistema trabalhe com contexto persistido e enxuto.
Harnessability Score (v2.5.0+)
Inspirado em Birgitta Böckeler — "ambient affordances" tornam o codebase mais governável pelo agente. Ver
policies/harness-categories.md+docs/inspiration/harness-engineering.md.
Junto com a auditoria, calcule e reporte o harnessability score do projeto (0-100):
| Sinal | Pontos | Como detectar |
|---|---|---|
| Linguagem com static typing forte (TS strict, Rust, Go, Java) | +20 | tsconfig.json com strict:true, Cargo.toml, go.mod, pom.xml |
| Linter configurado | +15 | .eslintrc*, ruff.toml, clippy.toml, golangci.yml |
| Module boundaries claros | +15 | DDD (domains/), hexagonal (adapters/ + ports/), feature folders, monorepo tooling |
| Testes existentes c/ cobertura > 60% | +15 | tests/, __tests__/, coverage report ou badge ≥60% |
| CI configurado | +10 | .github/workflows/, .gitlab-ci.yml, Jenkinsfile, etc |
AGENTS.md ou CLAUDE.md presente |
+10 | grep no root |
| Repo-audit recente (<30d) | +5 | docs/repo-audit/current.md modtime |
| Constitution definida | +5 | memory/constitution.md existe |
| Dependency scanner | +5 | dependabot config, .snyk, renovate config |
Deduções por Risco:
Além dos sinais positivos acima, certos marcadores de risco SUBTRAEM pontos quando detectados. Este é um modelo conceitual — os pesos abaixo são pontos de partida heurísticos a calibrar por projeto, não números empiricamente validados.
| Sinal de risco | Pontos | Como detectar |
|---|---|---|
| TODO/FIXME mencionando segurança sem issue rastreada | -10 | grep TODO/FIXME + termos de security/auth sem link de issue |
| Funções >100 linhas sem cobertura de teste | -5 (por instância, com cap) | análise de tamanho de função cruzada com coverage report |
| Dependência com CVE conhecido não tratado | -10 | npm audit, pip-audit, dependabot alerts abertos |
| God-file/god-class acima do threshold sem dono/doc | -5 | tamanho de arquivo + ausência de CODEOWNERS/doc de módulo |
Cap por categoria: nenhuma categoria de dedução sozinha pode subtrair mais que -20 pontos do total de 100 — isso evita que um único tipo de risco zere o score sozinho e preserva o sinal das outras categorias.
Score final = max(0, soma dos sinais positivos + soma das deduções, cada categoria capada).
Modelo de dedução-com-cap e seção "Parece problema, mas está correto" — ver ## Fontes no final deste arquivo.
Interpretação:
| Score | Nível | Recomendação |
|---|---|---|
| 0-30 | Baixa harnessability | Considerar skill 23 (migration-refactor) antes de feature work pesado. Modo /swarm autonomous arriscado — preferir /auto ou /loop com supervisão. |
| 31-60 | Média | Kit funcional, alguns gaps. Considerar skills 38 (architecture-deepener) + 06 (security-review) pra fortalecer. |
| 61-85 | Boa | Kit roda com pouca supervisão. Modo /swarm aceitável. |
| 86-100 | Alta | Modo /swarm autonomous totalmente viável. |
Ambient affordances: liste os 3 maiores presentes E os 3 maiores gaps no relatório, com recomendações concretas. Exemplo:
## Ambient Affordances
**Top 3 presentes:**
- TypeScript strict habilitado
- Feature folders em `src/features/` com co-location
- Husky + lint-staged em pre-commit
**Top 3 gaps:**
- Sem dependency scanner (recomendado: dependabot)
- Coverage < 40% (skill 05 sugere meta de 60%)
- ADRs ausentes (`docs/adr/` vazio)
**Score: 65/100 (Boa harnessability)**
Governanca Global
Esta skill segue GLOBAL.md, policies/execution.md, policies/persistence.md, policies/token-efficiency.md, policies/handoffs.md, policies/tool-safety.md, policies/evals.md e policies/deliberate-simplification.md (consumidor do ledger de comentários simplify: — teto cruzado sem revisão vira achado de dívida técnica ativa).
Deteccao de governanca
Durante a auditoria, registrar em docs/repo-audit/current.md na secao "Governanca":
memory/constitution.mdexiste? (Se nao e o projeto e maduro/tem ADRs/PRDs: sugerir/constitutioncomo acao recomendada no relatorio)- ADRs em
docs/adr/? Quantos e status (accepted/proposed/superseded) policies/customizadas no projeto consumidor
Isso permite que as proximas skills saibam se podem ancorar decisoes em principios formais.
Para auditorias mais completas e revisoes incrementais, consultar docs/skill-guides/repo-auditor.md apenas quando necessario.
Quando Usar
- no primeiro contato com um repositorio
- quando a stack real divergir da stack de referencia do kit
- quando houver duvida sobre convencoes, assets, testes, docs ou risco tecnico
- antes de features grandes, migracoes ou automacoes novas
Quando Nao Usar
- para reanalisar tudo a cada task sem mudanca relevante
- para substituir investigacao pontual muito localizada
Entradas Esperadas
- repositorio atual
- estrutura de arquivos e docs existentes
- sinais de stack, tooling, testes, deploy e identidade visual
Saidas Esperadas
- auditoria curta e reutilizavel em markdown
- resumo executivo para o Orchestrator
- gaps, riscos e recomendacoes priorizadas
Responsabilidades
- Detectar stack, framework, ferramentas e convencoes reais do repositorio
- Identificar documentacao, testes, assets, pipeline e sinais de observabilidade
- Registrar identidade visual e contexto de imagens quando houver
- Persistir um resumo operacional reutilizavel para reduzir releitura futura
- Atualizar a auditoria apenas quando houver mudanca relevante no repositorio
- Encaminhar para
Asset Librarianquando o inventario visual precisar de organizacao dedicada - Recomendar automacoes Claude Code apropriadas ao codebase (modo
--recommend-automation)
Modo Recommend-Automation
Quando rodado com flag --recommend-automation (ou usuario pede explicitamente "recomendar automacoes"), apos a auditoria padrao gerar secao ## Automacoes Recomendadas no relatorio com:
Hooks recomendados (analisar o que o codebase pede)
| Detectado no repo | Hook sugerido | Why |
|---|---|---|
| Testes em CI demorando > 5min | PostToolUse rodando subset de tests afetados |
Feedback rapido |
.env* files com secrets |
PreToolUse block em commits que tocam .env* |
Prevent leaks |
| Migrations SQL na raiz | PreToolUse warning ao editar migration ja aplicada |
Safety |
package.json com 50+ deps |
SessionStart mostrando audit/outdated |
Awareness |
| Monorepo (turborepo/nx) | SessionStart listando workspaces ativos |
Context |
Subagents recomendados
| Detectado | Subagent sugerido |
|---|---|
| Codebase grande (> 100 files) | code-reviewer para PRs |
| Codigo de seguranca (auth, payments, crypto) | security-auditor antes de release |
| Suite de testes complexa | test-engineer para gerar/revisar |
| Bug recorrente em log de issues | debugger para diagnostico sistematico |
Skills do kit recomendadas
Apontar quais das 37 skills se aplicam ao projeto:
- Frontend? → skills 02, 04, 22 (a11y), 36 (web-assets)
- Backend? → skills 03, 06 (security), 20 (observability)
- Mobile? → skill 15 (mobile-tauri)
- IA features? → skills 25, 26, 27 + patterns/ai-integration/
MCP servers recomendados
Se o projeto usa serviços externos sem MCP server:
- GitHub heavy → MCP server do GitHub
- Banco frequente → MCP server do Postgres/Mongo
- Design system → Figma MCP
Slash commands relevantes
Sugerir 3-5 commands do kit que se aplicam ao workflow detectado.
Output format do recommend-automation
## Automacoes Recomendadas (skill 18 — modo recommend)
### Alta prioridade
- [ ] Instalar hook `pre-execution-gate.mjs` — detectado: testes em CI demoram 8min
- [ ] Adicionar subagent `security-auditor` — detectado: 23 files em src/auth/
- [ ] `/constitution` — projeto maduro (> 6m, 12 ADRs) sem governanca formal
### Media prioridade
- [ ] Skills 02/22/36 — projeto e frontend-heavy sem cobertura a11y
- [ ] MCP server do GitHub — 230 issues abertas, gh CLI usado em 14 scripts
### Baixa prioridade
- [ ] /consolidate-memory weekly schedule — vault tem 320 logs
Arquivo de Persistencia
Persistir em docs/repo-audit/current.md (indice) e splits dinamicos no mesmo diretorio.
Se o kit estiver instalado em .bot/, persistir em .bot/docs/repo-audit/.
Se houver reauditoria relevante, arquivar snapshots curtos em docs/repo-audit/history/.
Output Split
Ao auditar, gerar arquivos focados por tipo alem do current.md. Decidir quais gerar baseado no que o repo contem — nao gerar arquivos vazios.
Catalogo de Splits
| Arquivo | Gerar quando detectar | Conteudo |
|---|---|---|
current.md |
sempre | Indice enxuto: stack, convencoes, riscos, gaps. Aponta para splits: Ver routes.md para endpoints |
routes.md |
API routes (Express, Fastify, Next API, Django urls, Flask, etc.) | Endpoints por recurso, metodos HTTP, middlewares, auth |
schema.md |
ORM/schema (Prisma, Drizzle, TypeORM, Sequelize, migrations) | Models, campos-chave, relacoes FK, enums |
components.md |
Framework de componentes (React, Vue, Svelte, Angular) | Arvore por feature, props, client/server, lazy |
services.md |
Camada de servicos/usecases (classes com patterns service/usecase) | Servicos, dependencias, metodos publicos |
infra.md |
Docker, CI/CD, Terraform, k8s, serverless | Containers, pipelines, environments, secrets ref |
Regras do Split
- current.md nunca duplica conteudo dos splits — apenas referencia com ponteiro
- Cada split cabe em ~200 linhas — se passar, resumir mais agressivamente
- Notacao compacta — usar
fn nome(args): tipo,[auth,db]pra tags,(c)pra client components - Geracao incremental — so re-gerar split se arquivos relevantes mudaram (verificar via git diff)
- Path dos splits — mesmo diretorio do
current.md(docs/repo-audit/ou.bot/docs/repo-audit/)
Deteccao
Para decidir quais splits gerar, verificar:
routes.md: existencia deapp.get/post/put/delete,router.,@Get/@Post,urlpatterns,api/dir com handlersschema.md: existencia deschema.prisma,*.entity.ts,models.py, diretoriomigrations/components.md: existencia de.tsx/.vue/.svelteemsrc/components/ouapp/services.md: existencia de*Service.ts,*UseCase.ts,services/dir,usecases/dirinfra.md: existencia deDockerfile,.github/workflows/,terraform/,k8s/,docker-compose
Quando Reauditar
- auditoria ausente
- auditoria com sinais claros de desatualizacao
- mudanca relevante de stack, assets, testes, deploy ou observabilidade
- reestruturacao grande do repositorio
Gate de Orientação por Churn (dívida técnica)
Antes de auditar dívida técnica em repo grande, priorizar onde investigar em vez de varrer tudo:
# 20 maiores arquivos por linha
find . -name "*.ts" -o -name "*.tsx" -o -name "*.py" | xargs wc -l | sort -rn | head -20
# 20 arquivos mais modificados nos últimos 6 meses
git log --since="6 months ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -20
A interseção das duas listas — arquivo grande E frequentemente modificado — é onde dívida técnica real se concentra: código que já é difícil de entender e que continua mudando, sinal de que ninguém teve confiança de refatorá-lo. Auditar a interseção primeiro; o resto entra na varredura padrão.
Conteudo Minimo da Auditoria
- stack principal e ferramentas detectadas
- estrutura de codigo e docs relevantes
- padroes de auth, testes, deploy e observabilidade
- assets e identidade visual existentes
- riscos, gaps e areas que exigem cuidado extra
- ultima data de revisao
Estrutura Recomendada do Markdown
Usar templates/audit.md como base e manter secoes curtas, atualizaveis e reutilizaveis.
Checkpoint antes de persistir: para cada afirmação da auditoria ("usa Prisma", "testes com Vitest", "deploy via Docker"), confirmar contra um arquivo real do repo (package.json, docker-compose.yml, config de teste) — não contra memória de repos parecidos. Se uma seção não pôde ser confirmada, marcar explicitamente como não-verificado em vez de preencher por inferência silenciosa; uma auditoria com gap marcado é mais útil que uma completa e errada.
Seção obrigatória: "Parece problema, mas está correto"
Toda auditoria de dívida técnica ou de risco tem viés de over-flagging: é fácil apontar padrão incomum, é difícil confirmar que ele é deliberado e correto no contexto. Antes de fechar o relatório, listar explicitamente 2-3 itens que pareciam dívida técnica à primeira vista mas, ao investigar o contexto (histórico do arquivo, comentário, ADR, constraint externa), se confirmaram como decisão correta.
- Exemplos do que entra aqui: uma duplicação de código que existe porque os dois caminhos vão divergir em breve (feature flag em rollout); uma dependência "desatualizada" que está travada por incompatibilidade documentada; um arquivo grande que é gerado e não deveria ser modularizado.
- Se esta seção vier vazia, tratar como sinal de auditoria rasa — não como "o repo não tem nenhum caso desses". Investigar de novo antes de aceitar zero itens.
- Formato:
Item | Por que parecia problema | Por que está correto | Evidência (arquivo/commit/ADR).
## Parece problema, mas está correto
| Item | Por que parecia dívida | Por que está correto | Evidência |
|---|---|---|---|
| `checkout.ts` duplica validação de `cart.ts` | DRY violation óbvia | Os dois fluxos divergem no rollout do novo checkout (feature flag `NEW_CHECKOUT`) — unificar agora quebraria o rollback | `flags.ts:12`, ADR-014 |
Regras de Economia de Token
- ler primeiro a auditoria existente antes de explorar o repo novamente
- atualizar apenas as secoes afetadas quando a base nao mudou muito
- evitar revarrer arquivos grandes se a auditoria ainda estiver valida
Evidencia de Conclusao
docs/repo-audit/current.mdcriado ou atualizado (indice enxuto)- splits relevantes gerados (
routes.md,schema.md, etc.) conforme deteccao - stack e convencoes reais mapeadas
- riscos e gaps principais registrados
Handoff
Entregar:
- caminho do arquivo de auditoria
- o que foi confirmado
- o que ainda esta incerto
- proxima skill que pode usar a auditoria
Seguir policies/handoffs.md e, quando util, templates/audit.md.
Fontes
- Modelo de dedução-com-cap do Harnessability Score inspirado na abordagem de health-scoring calibrado de repowise-dev/repowise (AGPL-3.0) — só o modelo conceitual foi adaptado, nenhum código ou peso específico de marcador foi copiado (a licença AGPL é o motivo de não herdar código).
- A seção "Parece problema, mas está correto" e o gate de orientação por churn foram inspirados no mecanismo de ksimback/tech-debt-skill (sem licença declarada) — por isso reimplementados integralmente com redação própria, sem copiar texto da fonte.