PARE. LEIA ESTE SKILL.MD COMPLETO ANTES DE CHAMAR QUALQUER ENDPOINT.
O que assess faz?
Recue e reavalie criticamente o estado do projeto. Fornece orientação interativa (humano-no-loop) e análise programática (pipelines automatizados). Especializado em poda de documentação e alinhamento doc-código.
Uso via CLI
# Avaliação JSON estruturada para pipelines
.pi/skills/assess/assess.py run . --output assessment.json
# Gerar todas as figuras a partir da avaliação
create-figure from-assess --input assessment.json --output-dir ./figures/
Fluxo de Avaliação
1. Escopo da Avaliação
Escopo claro ("avaliar o módulo auth") → prossiga diretamente. Escopo aberto ("recuar") → pergunte: preocupações? qualidade do código vs docs? problemas conhecidos a pular? Poda de documentação ("podar documentação") → pergunte: funcionalidades obsoletas? docs faltando? alinhamento?
2. Encontrar Raiz do Projeto e Detectar Ecossistema
Detecte via arquivos de marcador (pyproject.toml, package.json, Cargo.toml, go.mod). Leia metadados específicos do ecossistema, depois docs universais (README.md, CONTEXT.md, AGENTS.md).
3. Carregar Manifesto de Habilidades (Gate de Rota)
Carregue .pi/skills-manifest.json para avaliações que podem levar a recomendações do tipo "deveríamos construir X". Pule para verificações de status e revisões apenas de documentação.
cat .pi/skills-manifest.json | python3 -c "
import json, sys
data = json.load(sys.stdin)
print(f'Skills: {data[\"skill_count\"]} (generated: {data[\"generated\"]})')
"
Aviso se o manifesto estiver desatualizado há mais de 7 dias. Fallback: ls .pi/skills/ | wc -l.
4. Varredura Rápida → Verificação → Mergulho Profundo
- Leia metadados do projeto, README, glob para estrutura
- Observe 2-3 observações iniciais, verifique com o usuário
- Mergulho profundo baseado na orientação do usuário — para cada descoberta: bloqueante? conhecido? complexidade da correção?
5. Relatório Colaborativo
Apresente as descobertas e pergunte quais corrigir. Ofereça /create-figure para visualização.
Categorias de Avaliação
1. Alinhamento Doc-Código
- Afirmações do README vs implementação
- Validação de referência cruzada (links internos, exemplos de código)
- Marcadores de placeholder e informações desatualizadas
- Deprecação: docs para recursos removidos
2. Aspiracional vs Implementado
- Stubs (
pass,raise NotImplementedError), notas de placeholder - Recursos na estrutura do código mas sem lógica, dependências não utilizadas
3. Código Frágil
- Valores hardcoded, tratamento de erro ausente, regex/parsing frágil
4. Código Não Funcionante
- Caminhos de código morto, engolimento silencioso de exceções, integrações quebradas
5. Código Superengenhado
- Abstrações com implementação única, configuração para flexibilidade hipotética
6. Cobertura de Testes (Inegociável)
Verifique cada funcionalidade/módulo por arquivos de teste, testes passando, casos de borda.
Sinalize pytest.mark.skip sem motivo, "0 tests collected", testes que não afirmam nada.
Auditoria de arquivos de tarefa: Verifique se cada tarefa possui Definição de Pronto com teste/asserção específica. Bloqueie execução se tarefas de implementação não possuírem Definição de Pronto.
7. Funcionando Bem
Reconheça código sólido para calibrar a avaliação.
Formato de Saída
# Avaliação: <nome-do-projeto>
## Resumo
<2-3 frases: saúde geral, principais descobertas>
## Descobertas
### Alinhamento Doc-Código
| Afirmação | Realidade | Ação? |
### Problemas Encontrados
1. **arquivo.py:123** - [Problema] — Severidade: A/M/B — Correção sugerida: [breve]
### Cobertura de Testes
| Funcionalidade | Status do Teste | Ação Necessária |
### Funcionando Bem
- [Código sólido a reconhecer]
## Próximos Passos Recomendados
1-4 ações priorizadas. Pergunte qual iniciar.
Políticas
- Somente leitura por padrão — nunca escreva arquivos sem consentimento explícito
- Imprima primeiro, escreva com consentimento — mostre o conteúdo proposto, depois ofereça para escrever
- Colabore — avaliação é diálogo, não monólogo
- Pergunte antes de executar — obtenha permissão antes de testes, builds, serviços pagos
- Escale sabiamente — sugira
/review-codepara problemas complexos/críticos - Seja específico — caminhos de arquivo e números de linha
- Seja acionável — cada descoberta sugere próximos passos
- Cobertura de testes é inegociável — sinalize testes ausentes como bloqueadores
Pesquisas Externas
Disponíveis quando necessário (pergunte antes de serviços pagos):
/context7— documentação de bibliotecas (gratuito)/brave-search— web geral (gratuito)/perplexity— pesquisa profunda (pago)
Erros Comuns
# ERRADO: Tratar todas as descobertas da avaliação como bloqueios
# → Agente adiciona docstrings a 12 helpers privados automaticamente. Inchação desnecessária.
# CERTO: Revisar descobertas com o usuário. Escalar problemas complexos para /review-code.
# ERRADO: Pular /assess após mudanças importantes
# → Exemplos do README usam assinatura antiga de função. Usuários encontram erros.
# CERTO: Executar assess --focus "doc-code-alignment" após editar APIs principais
# ERRADO: Executar /assess e agir com resultados desatualizados
# → Avaliação de 3 dias atrás. Codebase mudou desde então.
# CERTO: Sempre re-executar assess; nunca armazenar em cache entre sessões