11 KiB
| name | description |
|---|---|
| react-audit | Audit React/Next.js anti-patterns com ciclo fechado: sweep focado → plano per-fix → implementação com gate completo → um único PR ready SEM auto-merge cuja descrição é o relatório. |
React Audit (ciclo fechado plan→implement)
Skill para rodar sozinha (à noite, sem supervisão): varre o repo por anti-patterns
React/Next.js do catálogo fixo (anti-patterns.md desta pasta), planeja e implementa
cada fix com o gate completo, e entrega um único PR para main — ready,
sem auto-merge, CI green, mergeable, sem conflitos — com um commit por fix e a
descrição do PR como relatório consolidado. Aí PARA: o humano explora os commits
e mescla quando quiser. Feedback humano = comentário no PR → ajusta na MESMA branch.
Complementar ao engineering-audit (qualidade geral); NÃO re-varre o que ele já cobre.
Context7 MCP é aceleração opcional — ver context7-setup.md; sem ele, use as fontes
oficiais embutidas no catálogo. Nunca bloqueie por falta do MCP.
Proibido
- DB de prod /
ALLOW_REMOTE_DB/ repontar envs — local only (teqo_testnos testes). - Mergear qualquer coisa ou armar auto-merge. O PR da run nasce e PERMANECE sem auto-merge.
- Abrir draft e flipar ready no fim (corrida de instant-merge com check já verde).
- Expandir o catálogo de famílias durante a run; fix fora das 9 famílias vira follow-up.
- Fix sem os TRÊS selos (file:line + família + fonte oficial) — "cartilha genérica" não entra.
Closes #Nde Issue alheia no body do PR da run (useRefs #N).- Tocar Issues
in-progressalheias ou claimar na sessão. - Gate commands piped (
| tailengole exit code);knip --fixcego. - Migration/schema Payload em commit noturno — fix que exigir migration vira follow-up.
Checklist
- [ ] 0. Precheck fail-closed (read-only): worktree provisionado, branch ≠ main, GITHUB_TOKEN válido, baseline bare anotada
- [ ] 1. Sweep read-only por família do catálogo (canon primeiro; Tasks ad-hoc por área)
- [ ] 2. Triage per-fix: 3 selos, dedup TECH-DEBT/guardas vivas, dono travado → follow-up, cap ≤ 6
- [ ] 3. Loop por fix: mini-plano → implementar (editar o dono) → gate completo BARE → 1 commit → push da branch (sem PR)
- [ ] 4. Relatório consolidado (body do PR) + follow-ups como Issues + changelog da run
- [ ] 5. Abrir o PR ÚNICO Ready via scripts/github-pr.mjs → DESARMAR auto-merge → verificar auto_merge null
- [ ] 6. Estabilizar até checks green ∧ mergeable ∧ auto_merge null → PARAR sem mergear
Passo 0 — Precheck fail-closed (read-only)
Tudo aqui é leitura. Falhou um item → pare com o remédio nomeado, não improvise às 3h.
- Estar DENTRO do worktree provisionado da run (
pnpm worktree next --issue <N>já claimou e criou envs/DBs/porta dedicadas). Nunca rodar no repo principal nem claimar na sessão. git status --porcelainlimpo (commit/stash pendências alheias antes? Não são suas — PARE e relate).- Branch corrente ≠
main. Se estiver em main/detached, crieagent/<N>-react-audita partir deorigin/main— nunca commitar fix em main. GITHUB_TOKENpresente e validado com chamada barata ANTES do trabalho:node -e "import('./scripts/lib/github-api.mjs').then(m=>m.githubApi.listIssues({limit:1})).then(i=>console.log(i.length>=0))".- Baseline bare dos gates estáticos — vermelhos pré-existentes são BASELINE (política
"dono do PR, dono do CI",
docs/AGENT-OPS.md), anote-os:pnpm exec tsc --noEmit,pnpm lint,pnpm exec knip,pnpm check:cycles. - Pool morto desde OPS65 — nada a pausar.
Passo 1 — Sweep read-only
Zero writes em src/, tests/, scripts/ neste passo.
- Canon primeiro:
.agents/rules/engineering-standards.mdc,.agents/rules/codebase-map.mdc,AGENTS.md,docs/TECH-DEBT.md(dedup). - Carregue
.agents/skills/react-audit/anti-patterns.md— as 9 famílias e suas heurísticas. - Âncora de delta: data da última entrada react-audit em
docs/changelog/(primeira run = repo inteiro). Foque o esforço no churn desde a âncora:git log --since="<âncora>" --name-only --format= | sort -u. - Tasks ad-hoc por família/área (padrão
work-issue: input mínimo + instrução explícita): prompt do subagente carrega a seção da família + a âncora de delta e exige output ≤25 linhas no formatofile:line | família | sintoma observado— "Não escrever código nem planos". - Com Context7 ativo, consulte a doc oficial vigente ANTES de classificar (evita fix contra a versão atual); sem Context7, confie nas URLs do catálogo e confirme na citação.
Passo 2 — Triage per-fix
Para cada candidato do sweep:
- Exija os TRÊS selos:
file:lineconferido por você (abra o arquivo), família do catálogo, fonte oficial. Faltou um → linha "observado sem fix" no relatório; não invente justificativa. - Dedup: já está em
docs/TECH-DEBT.md(classe B14/P4-F aberta)? Guarda viva cobre (ESLint restrictions,tests/unit/codebaseConventions.unit.spec.ts)? Já registrado → pule. - Dono travado (URL pública congelada, Consent/LGPD, migration shipped, collection schema) → follow-up no Passo 4, NUNCA fix noturno.
- Priorize churn × severidade; corte em ≤ 6 fixes por run (cap duro — PR maior derrota a revisão matinal commit a commit). Resto vira follow-up ou "adiado" no relatório.
Passo 3 — Loop de implementação (por fix)
Um fix = mini-plano + gate completo + UM commit + push da branch (sem PR ainda — push de branch isolada não dispara workflow nenhum).
- Task escritor (input: achado com os 3 selos + seção da família + norma citada; "Não escrever código"): devolve mini-plano — receita, blast radius, pins/testes a tocar, critério de feito.
- Implemente você mesmo (agente principal), editar o dono, não twinar: contratos client-safe /
import typeao cruzar fronteira server→client; nada de módulo paralelo ao lado do dono. - Gate completo BARE por fix (na ordem, cada comando sozinho no shell):
pnpm exec tsc --noEmit,pnpm lint,pnpm format:check,pnpm exec knip,pnpm check:cycles,pnpm test,pnpm build. Export órfão previsto? Resolva NO MESMO fix (git grep -w <symbol>antes de remover; nuncaknip --fix). Vermelho pré-existente da baseline do Passo 0 não é seu — documente. - E2E afetado (discricionário, OPS72):
pnpm test:e2e:affectedquando o fix tocar superfície com spec;gate:pushNÃO roda e2e — este passo é quem cobre. - Commit único do fix: mensagem citando família +
file:line(ex.:react-audit(família 3): derived state via effect em MunicipalityFilter.tsx:88). Push:git push -u origin HEAD(branch sem PR ⇒ nenhum safety net dispara). - Volte ao Passo 2 para o próximo elegível.
Passo 4 — Relatório + follow-ups + changelog
- Monte o relatório consolidado (será o BODY do PR) com, nesta ordem: (i) escopo/data/números do sweep (arquivos varridos, candidatos, fixes); (ii) tabela de achados: file:line | família | fonte oficial; (iii) POR FIX: decisão (implementado/rejeitado/adiado/follow-up) e O PORQUÊ (decisão, gate, custo, sobreposição com dono existente) + SHA do commit + resultado do gate; (iv) estado final do PR; (v) follow-ups recomendados com destino.
- Follow-ups que sobrevivem ao PR → Issues reais via caminho canônico
(
scripts/lib/github-api.mjscreateIssue), título prefixado[react-audit], body com file:line + fonte + link do PR. Sem Issue per-fix implementada (geminação). - Changelog da run:
docs/changelog/<data>-react-audit-run.md(uma entrada curta; docs-guards são additions-only — jamais tocar HISTORY/agregado).
Passo 5 — PR único + desarme do auto-merge
O PR nasce UMA vez, já estabilizado localmente, e fica SEM auto-merge.
-
GITHUB_TOKEN=<PAT> node scripts/github-pr.mjs --head <branch> \ --title "react-audit <data>: <N> fixes" --base main --body-file <relatorio.md>— nunca draft;Refs #Napenas; jamaisClosesde Issue alheia. -
Imediatamente após abrir, DESARME O AUTO-MERGE COM VERIFICAÇÃO EM LAÇO — o safety net
agent-pr-ready-automerge.ymlarma ASSINCRONAMENTE depois da abertura (na corrida real capturada no dogfood #905, um desarme único perdeu: o armar aconteceu ENTRE o primeiro GET e o DELETE; e o endpoint RESTDELETE /pulls/N/auto-mergeresponde 404 mesmo armado-via-GraphQL — não serve). Use o helper do dono, que codifica essa lição:// node --input-type=module import { githubApi } from './scripts/lib/github-api.mjs' const pr = await githubApi.getPullRequest(<N>) // confere head.sha = branch await githubApi.ensureAutoMergeDisabled(<N>) // mutation GraphQL disablePullRequestAutoMerge // + re-poll até auto_merge null (lança se não convergir)ensureAutoMergeDisabledresolvetruesó quando um poll lêauto_merge = null; lança erro nomeando o PR se esgotar as tentativas — nesse caso, trate como falha de Done. -
REGRA DURA: todo push pós-abertura (fix de CI vermelho, rebase) é seguido IMEDIATAMENTE de
ensureAutoMergeDisabled(<N>)— cadasynchronizeRE-ARMA o auto-merge silenciosamente.
Passo 6 — Estabilizar até o fim (Done condition)
Loop até a condição de Done — a entrega só termina estável:
- CI: polle o check-run literal
checksdo head SHA (API check-runs ough pr checks) com backoff. Vermelho dentro do blast radius dos fixes → conserte na branch (novo commit próprio, gate completo, push, REDESARME). Infra estrutural → aplique o CAP (abaixo), registre honestamente no relatório e pare com estado declarado. - Conflitos:
getPullRequest().mergeable—null= GitHub computando (backoff, re-poll);false= rebase sobreorigin/main, resolva, push, REDESARME. - Caps anti-loop infinito: máx. 3 ciclos de fix pós-abertura OU 90 min de estabilização — estourou → relatório declara o estado real e a skill termina SEM Done falso.
- Done = checks green ∧
mergeable === true∧auto_merge === null∧ PR open+ready. Então PARAR. Não mergear. Não armar nada. O humano revisa de manhã. - Feedback humano posterior: pedido de mudança no PR → commits novos NA MESMA branch, relatório atualizado (PATCH do body), re-estabilize pelo mesmo loop.
Context7 MCP (aceleração opcional)
Setup manual do dono da máquina, FORA do git: .agents/skills/react-audit/context7-setup.md.
A skill FUNCIONA sem — fallback são as fontes oficiais do catálogo.
Done when
Precheck verde (ou parada fail-closed nomeada); sweep com achados mapeados file:line+família+fonte;
cada fix com mini-plano, gate completo bare e commit próprio; cap ≤6 respeitado; relatório
consolidado É a descrição do PR; follow-ups com destino (Issue/relatório); changelog da run
escrito; PR único open+ready com checks green, mergeable true e auto_merge null — e a skill
PAROU, sem mergear nada.