| name | first-plan-pattern-extraction |
| description | Skill que define como extrair padrões do código com confidence scoring. Use durante Discovery quando precisar identificar convenções, anti-padrões ou padrões idiomáticos do projeto. Cada padrão extraído deve vir com exemplo concreto do código (path:line). |
| version | 0.1.0 |
Pattern Extraction
Como transformar observações do código em "padrões" registráveis em .first-plan/02-conventions/, 06-rationale/do.md, 06-rationale/dont.md.
Princípio
Sem exemplo do código, sem padrão. Toda regra extraída precisa de pelo menos 1 exemplo concreto (path:line). Sem exemplo, vira pergunta em 08-meta/questions.md ou é descartada.
Algoritmo de extração
1. Amostragem
Para cada categoria (errors, naming, testing, etc), amostre arquivos representativos:
- Top 10 arquivos por linhas de código (não-teste)
- Top 5 arquivos modificados nos últimos 30 dias
- 3 arquivos de teste de cada pasta principal
Limite: máx 50 arquivos lidos por categoria. Se ficar muito ruidoso, abortar com confidence baixa.
2. Identificação de padrão candidato
Em cada arquivo amostrado, busque:
- Repetição estrutural (5+ ocorrências da mesma forma)
- Imports comuns (mesmo símbolo importado em N+ arquivos)
- Receitas (e.g., "todo handler começa com
func Handle...(ctx Context, req Request) (Response, error)")
- Comentários proibitivos (
// don't use X, // use Y instead)
- Código deletado em commits recentes (sinal de anti-padrão)
3. Confidence scoring
Cada padrão candidato ganha confidence baseado em sinais convergentes:
| Sinal | Peso |
|---|
| 5+ ocorrências consistentes | +0.3 |
| 10+ ocorrências consistentes | +0.5 |
| Mesmo padrão em testes e código de produção | +0.2 |
| Comentário no codebase explicitamente preferindo o padrão | +0.2 |
| Documentado em README/CLAUDE.md/docs/ | +0.2 |
| Ocorre em código recente (últimos 90 dias) | +0.1 |
| Não tem variantes inconsistentes | +0.2 |
| Tem variantes inconsistentes (alguns fazem A, outros B) | -0.3 |
| Apenas 1-2 ocorrências | -0.4 |
| Apenas em código antigo (>1 ano sem update) | -0.2 |
| Conflita com outro padrão extraído | -0.3 |
Soma final clamped em [0.0, 1.0]. Threshold default 0.7.
4. Anti-padrões (o que o projeto evita)
Detectar via:
- Ausência consistente de algo comum em outros projetos similares (e.g., zero
any em projeto TS estrito = sinal forte de "evitar any")
- Comentários
// don't, // avoid, // nao usar, // removed because
- Commits/PRs com mensagens "remove", "deprecate", "migrate away from"
- Padrão substituído por outro (e.g., todos os
console.log foram trocados por logger.info em commits recentes)
Confidence para anti-padrão tem regra extra: requerer pelo menos 2 sinais distintos para considerar válido.
5. Exemplificação obrigatória
Cada padrão extraído gera entrada no formato:
### Padrão: <nome>
- **Resumo:** <1 linha>
- **Por que existe (inferido):** <opcional, se houver evidência>
- **Exemplo:**
```<lang>
<trecho real do código>
Visto em: <path>:<line>
- Quando aplicar:
- Confidence:
Sem o exemplo, **descartar o padrão ou rebaixar a pergunta**.
## Categorias e onde escrever
| Categoria | Arquivo de saída |
|-----------|------------------|
| Naming | `02-conventions/naming.md` |
| Errors | `02-conventions/errors.md` |
| Testing | `02-conventions/testing.md` |
| Logging | `02-conventions/logging.md` |
| DI | `02-conventions/di.md` |
| Security | `02-conventions/security.md` |
| Padrões positivos cross-cutting | `06-rationale/do.md` |
| Anti-padrões | `06-rationale/dont.md` |
| Decisões inferidas | `06-rationale/why.md` |
## Quando virar pergunta em vez de padrão
Se confidence < 0.7 mas o tópico é importante (e.g., naming convention é crítico):
1. Não escrever o padrão como verdade
2. Adicionar entrada em `08-meta/questions.md` com hipóteses A/B/C
3. Anotar em `02-conventions/<category>.md` que "convenção indeterminada - ver questions.md"
## Cuidados
- **Não inventar regras genéricas.** Se o projeto não tem padrão claro, o output é "indeterminado", não "use snake_case porque é a convenção da linguagem".
- **Não impor best practices externas.** Se o projeto usa `var` em vez de `let` em todo lugar, o padrão extraído é "use `var`", não "deveria usar `let`".
- **Variantes inconsistentes** são sinal de migração em curso ou de equipes desalinhadas. Reportar ambas, com nota de "variante minoritária possivelmente em migração".
