teqo-backup/docs/plans/ops97-react-audit-skill.md

# Skill /react-audit com ciclo fechado plan→implement de anti-patterns React/Next.js

Status: rascunho
Atualizado em: 2026-08-24
Issue: #901
Priority: P2
Impeccable: A — N/A sem UI
Rascunho UI: N/A — sem UI
Appetite: ~1,5–2 dias eng; um outcome verificável
Responsável: —

## Intenção

Hoje a auditoria de código (engineering-audit) varre o repo inteiro, é read-only no sweep, e as remediações P2/P3 viram apenas ledger/plano — não existe um ciclo fechado que (a) mire especificamente anti-patterns de React/Next.js, (b) aponte as fontes oficiais (react.dev, nextjs.org) como referência e (c) feche o loop: planejar o fix e implementá-lo, sem humano. Em pré-campanha os agentes trabalham em paralelo e queremos que o react-audit rode sozinho (provavelmente de madrugada), encontre anti-patterns, proponha e implemente os fixes, e os agentes que rodam o audit tenham o Context7 MCP à mão para consultar a documentação oficial vigente. A skill **não faz merge sozinha**: ao final entrega **um único PR** com todos os fixes (cada fix num commit separado), **ready mas sem auto-merge**, CI green e mergeable, e a **descrição do PR é o relatório** — o que foi feito e o porquê de cada decisão. O ciclo termina quando esse PR está pronto para o humano explorar e mesclar.

## Persona e fluxo

- **Persona / contexto:** agente autônomo (ou humano dev) rodando a skill à noite, fora do horário de trabalho, sem ninguém assistindo a execução; o humano revisa **na manhã seguinte**, com calma.
- **Job principal:** varrer o repo por anti-patterns de React/Next.js, planejar e implementar os fixes, e entregar **um PR final único** (ready, sem auto-merge, CI green, mergeable) cuja descrição documenta tudo o que foi feito e por quê — para o humano explorar commit a commit e mesclar quando quiser.
- **Fluxo desejado:** (1) a skill abre o sweep focado em anti-patterns React/Next, mapeando cada achado a file:line; (2) para cada fix, um subagente escritor planeja (plano impl + Issue trackeável) com fonte oficial de referência; (3) um subagente implementador aplica o fix com o gate completo do repo; (4) **todos os fixes vão para a mesma branch, cada um num commit separado** (commits atômicos e legíveis para exploração); (5) ao final, a skill abre **um único PR** para `main`, ready e **sem auto-merge**, com CI green e sem conflitos; (6) a **descrição do PR é o relatório consolidado** (o que foi feito + porquês, estado de cada fix, follow-ups); (7) a entrega termina quando esse PR está green/mergeable/sem conflitos — o humano explora e mescla. Rejeição/edição do PR = humano comenta e a skill ajusta na branch; o histórico dos commits preserva o ledger.
- **Anti-goals de produto:** NÃO virar sweep geral de qualidade (é do engineering-audit) nem "cartilha genérica de boas práticas"; NÃO automatizar a config global da máquina (anti-goal OPS92); NÃO tocar convenções travadas (URLs públicas, Consent/LGPD, migrations shipped); NÃO armar auto-merge nem mesclar em `main` sem humano — a revisão humana é parte do fluxo.

## Objetivo e aceite

- Sweep focado e complementar ao engineering-audit (não re-varre qualidade geral), cada achado com file:line, família de anti-pattern e fonte oficial.
- Cada fix implementado com o gate completo do repo (tsc/lint/format/knip/cycles/unit+int/build + e2e da superfície afetada) e o próprio commit.
- **Um único PR final** aberto para `main`, estado **ready**, **sem auto-merge** armado, **sem conflitos** (mergeable) e com **CI green** ao encerrar a skill.
- **Commits separados por fix** (atômicos, com mensagem descritiva) para o humano explorar a mudança de cada anti-pattern isoladamente.
- **A descrição do PR é o relatório de auditoria**: (i) o que foi varrido e quando, (ii) cada achado com file:line e fonte oficial, (iii) por fix: planejado/implementado/rejeitado/adiado e **o porquê** (decisão, gate, custo, sobreposição com dono existente), (iv) estado final do PR e (v) recomendações de follow-up com destino (Issue/ledger).
- Skill funcional mesmo sem o Context7 (fallback a links oficiais), com a declaração global do MCP documentada como passo de setup manual do dono da máquina.
- A entrega **só termina** quando o PR final está green/mergeable/sem conflitos/sem auto-merge — se o CI ainda estiver rodando ou houver conflito, a skill continua até estabilizar.

## Dados (intenção)

- **Vou apresentar dados?** Não — tooling de desenvolvimento, sem dado de negócio.
- **Decisões desbloqueadas:** N/A
- **Forma:** N/A.

## Direção no codebase (hipótese)

- **Áreas prováveis:** `.agents/skills/react-audit/SKILL.md` (novo); catálogo de anti-patterns já codificado em `.agents/rules/engineering-standards.mdc` (client boundary :24-28, caching ladder :34-43), `.agents/rules/codebase-map.mdc:26`, achados de `engineering-audit` (B14/B34, RSC payload, effects doing derived state); subagentes em `.opencode/agent/*.md`; contexto de merge/deploy em `docs/AGENT-OPS.md` e `.github/workflows/agent-pr-ready-automerge.yml` (que NÃO deve ser usado — PR final fica sem auto-merge).
- **Precedente a olhar:** `.agents/skills/engineering-audit/SKILL.md` (audit read-only; o modo autônomo dele usa auto-merge — aqui divergimos: PR único ready sem auto-merge); `agent-work-issue/SKILL.md` (plan→execute→simplify→PR sem pausa); `work-issue/SKILL.md` (uso de Task com subagentes); `docs/plans/react-19-form-reset-campanha.md` (C140 — fatia de fix React 19 já entregue).
- **Risco de acoplamento:** médio — a skill não muda produto, mas o PR final de fix que ela gera atravessa o gate CI completo e pode esbarrar em áreas com donos existentes; fixes seguem "editar o dono, não twinar". O relatório (descrição do PR) é o fio de auditoria — sem ele o audit roda e "some" de madrugada.

## Dependências

- Nenhuma.

## Fora de escopo

- Sweep geral de qualidade (permanece no engineering-audit).
- Mudança no gate/deploy (CI/auto-merge vigentes ficam como estão).
- Automação da config global (declaração do Context7 é passo manual documentado).
- Revisão/correção das convenções travadas (URLs públicas, Consent/LGPD, migrations shipped).

## Rabbit holes de produto

- **Sweep virar "cartilha genérica".** Se alguém "só completar" a skill com boas práticas descoladas do repo, ela perde o valor de auditoria. **Corte neste item:** cada anti-pattern precisa de file:line do repo + fonte oficial; sem mapeamento, não vira fix.
- **Escopo inflar para qualidade geral.** Se o escritor "só completar" com temas fora de React/Next, vira um segundo engineering-audit. **Corte neste item:** enumeração fixa de famílias (client boundary, RSC payload, estado/efeitos, forms/state, caching, server actions, streaming, next/image/fonts, a11y de componentes) e PRs só para esses achados.
- **Depender do Context7.** Se o MCP não estiver disponível, a skill não pode parar. **Corte neste item:** fallback a links oficiais e doc de setup manual; o MCP é aceleração, não requisito.
- **Relatório morar só na branch, longe do PR.** Se o relatório for um arquivo que o PR não carrega na descrição, o humano não vê o "porquê" sem abrir o diff. **Corte neste item:** a descrição do PR É o relatório; os commits separados dão a navegação por fix; o relatório também pode viver como arquivo em `docs/` dentro do próprio PR quando fizer sentido, mas nunca no lugar da descrição.
- **Fixes que tocam donos travados.** **Corte neste item:** precheck read-only (como engineering-audit) + gate do repo; achado que esbarra em dono travado vira follow-up no relatório, não muda o PR.

## Questões em aberto (produto)

- Escopo do sweep: focado em anti-patterns React/Next (recomendado — complementar ao engineering-audit). Posicionado.
- Context7: declarar globalmente na máquina do dono, fora do git (precedente OPS89/OPS92); NÃO no repo Teqo (custo de contexto vs. outcome OPS92). Executor valida o mecanismo vigente (shape do bloco mcp remote) e documenta o passo manual. Posicionado.
- Autonomia: execução autônoma da skill, mas **entrega = PR final único ready sem auto-merge** (nada mergeia em `main` sem humano); a skill estabiliza o PR até CI green + mergeable + sem conflitos e termina. Divergência deliberada do modo autônomo do engineering-audit (que usa auto-merge): aqui o humano quer revisar antes de mesclar. Posicionado.
- Fontes: react.dev/learn, react.dev/reference, nextjs.org/docs e nextjs.org/learn como contexto da skill; versões reais (package.json) conferidas na implementação. Posicionado.
- Relatório: **a descrição do PR é o relatório** (o que foi feito + porquês, estado de cada fix, follow-ups), escrito ao final do ciclo antes de abrir o PR, e atualizado se o humano pedir mudanças. Posicionado.

## Referências

- GitHub Issue #901
- `.agents/skills/engineering-audit/SKILL.md`; `.agents/skills/agent-work-issue/SKILL.md`; `.agents/skills/work-issue/SKILL.md`
- `.agents/rules/engineering-standards.mdc`; `.agents/rules/codebase-map.mdc`
- `docs/AGENT-OPS.md`; `.github/workflows/agent-pr-ready-automerge.yml`
- `docs/plans/react-19-form-reset-campanha.md`