From 1c1a37989728c2670bf6e9482e637d68e8ef3244 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Francisco=20Ign=C3=A1cio=20Fontoura=20Solla?= Date: Thu, 30 Jul 2026 12:22:05 -0300 Subject: [PATCH] feat: plan-issue skill --- .cursor/skills/close-delivery/SKILL.md | 92 ----- .cursor/skills/compile-roadmap/SKILL.md | 333 ------------------ .../skills/implement-roadmap-item/SKILL.md | 316 ----------------- .cursor/skills/plan-issue/SKILL.md | 89 +++++ .../data-presentation.md | 6 +- .../decision-quality.md | 2 +- .../plan-template.md | 14 +- .cursor/skills/roadmap-item/SKILL.md | 177 ---------- .cursor/skills/roadmap-items/SKILL.md | 119 ------- .cursor/skills/ship-to-main/SKILL.md | 201 ----------- .../suggest-next-roadmap-items/SKILL.md | 224 ------------ scripts/agent-register.mjs | 12 +- 12 files changed, 110 insertions(+), 1475 deletions(-) delete mode 100644 .cursor/skills/close-delivery/SKILL.md delete mode 100644 .cursor/skills/compile-roadmap/SKILL.md delete mode 100644 .cursor/skills/implement-roadmap-item/SKILL.md create mode 100644 .cursor/skills/plan-issue/SKILL.md rename .cursor/skills/{roadmap-item => plan-issue}/data-presentation.md (92%) rename .cursor/skills/{roadmap-item => plan-issue}/decision-quality.md (97%) rename .cursor/skills/{roadmap-item => plan-issue}/plan-template.md (92%) delete mode 100644 .cursor/skills/roadmap-item/SKILL.md delete mode 100644 .cursor/skills/roadmap-items/SKILL.md delete mode 100644 .cursor/skills/ship-to-main/SKILL.md delete mode 100644 .cursor/skills/suggest-next-roadmap-items/SKILL.md diff --git a/.cursor/skills/close-delivery/SKILL.md b/.cursor/skills/close-delivery/SKILL.md deleted file mode 100644 index 61c80db0..00000000 --- a/.cursor/skills/close-delivery/SKILL.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -name: close-delivery -description: >- - Runs the full post-simplify delivery closeout in one flow: rebase-on-main, - capture-review-debts (auto-confirm triage recommendations), then ship-to-main - (commit, push, merge to main, delete session worktree). Use after /simplify - and /impeccable when the user says "close delivery", "fecha a entrega", - "rebase + debts + ship", "fecha o ciclo", or wants the three closeout steps - without pausing for debt-triage confirmation. ---- - -# Close delivery - -Orquestra o fechamento da entrega em worktree numa única invocação: - -1. **`rebase-on-main`** — sync com `origin/main` + conflitos -2. **`capture-review-debts`** — triage de débitos **com auto-confirmação** da recomendação -3. **`ship-to-main`** — commit all → push → merge main → apagar worktree - -**Announce at start:** "Using close-delivery: rebase → capture debts (auto-confirm) → ship." - -**REQUIRED SUB-SKILLS:** Leia e execute integralmente, nesta ordem: - -- `.cursor/skills/rebase-on-main/SKILL.md` -- `.cursor/skills/capture-review-debts/SKILL.md` (com override abaixo) -- `.cursor/skills/ship-to-main/SKILL.md` - -Não reimplemente a lógica delas aqui — só orquestre + aplique o override de confirmação. - -## Checklist - -``` -- [ ] 0. Gate de modelo (skill model-selection: pool model; pare se metered premium — mesmo critério do Passo 0 de ship-to-main) -- [ ] 1. rebase-on-main (completo; pare se abortar/perguntar) -- [ ] 2. capture-review-debts com auto-confirm (override do Passo 5) -- [ ] 3. ship-to-main (completo) -- [ ] 4. Resumo unificado do ciclo -``` - -## Override: auto-confirm em `capture-review-debts` - -A skill filha exige **Pare e confirme** no Passo 5 antes de editar docs. **Neste fluxo, esse gate está dispensado.** - -Comportamento: - -1. Execute Passos 1–4 de `capture-review-debts` normalmente (colher, deduplicar, pontuar, mesclar). -2. Mostre a tabela de triage no resumo (transparência). -3. **Trate a recomendação da tabela como aprovada** e avance ao Passo 6 sem esperar o usuário. -4. Se não houver candidatos / só `já_resolvido`+`descartar`+`defer` sem registro: no-op de docs; siga para `ship-to-main`. -5. `defer` continua sem criar ID; anote gatilho no plano-pai se a skill filha mandar. - -**Ainda pare e pergunte** (não auto-confirm) se: - -- A triage ficar ambígua entre dois destinos sem regra clara na skill filha -- Um candidato `expensive_lock` (access/LGPD/schema/unicidade) não tiver destino seguro sem decisão de produto -- `roadmap-item` falharia por falta de dado que só o usuário pode dar - -Nesses casos: reporte o bloqueio, **não** rode `ship-to-main` ainda (working tree pode ter só o rebase). - -## Regras de orquestração - -| Situação | Ação | -| ---------------------------------------- | ------------------------------------------------------------------------- | -| Gate de modelo (Passo 0) sem confirmação | **Pare** — aguarde troca de modelo ou aceite explícito do custo | -| Rebase no-op (já sync) | Siga para debts | -| Rebase com conflitos resolvidos | Siga para debts | -| Rebase abortado / precisa decisão | **Pare** — não debts, não ship | -| Debts auto-confirm OK (ou no-op) | Siga para ship | -| Debts bloqueado (lock / ambiguidade) | **Pare** — não ship | -| Ship: feature atrás de main | Não deve ocorrer se Passo 1 OK; se ocorrer, re-rode rebase antes de merge | -| Ship: branch é `main` | Pare (guard da filha) | - -Commit das mudanças de roadmap/planos feitas no Passo 2 entra no **mesmo** `ship-to-main` (Passo 2 da filha — commit all). - -## Resumo unificado (final) - -Um bloco só, curto: - -1. **Rebase:** no-op / N commits / conflitos (paths) / abort -2. **Debts:** contagem (colhidos / registrados / absorvidos / defer / descartados) + IDs/slugs se houver + nota “auto-confirm” -3. **Ship:** SHA de main, branch/worktree removidos, aviso Cursor se path morto -4. **Próximo:** `suggest-next-roadmap-items` - -## Posição no fluxo - -``` -suggest-next → implement-roadmap-item → /simplify+/impeccable - → close-delivery - (= rebase-on-main → capture-review-debts[auto] → ship-to-main) -``` - -As três skills filhas continuam invocáveis à parte quando o usuário quiser pausar entre etapas. diff --git a/.cursor/skills/compile-roadmap/SKILL.md b/.cursor/skills/compile-roadmap/SKILL.md deleted file mode 100644 index ab5323fb..00000000 --- a/.cursor/skills/compile-roadmap/SKILL.md +++ /dev/null @@ -1,333 +0,0 @@ ---- -name: compile-roadmap -description: >- - Lê docs/roadmap.md e fontes relacionadas, classifica o que já foi entregue, - comprime o histórico em um resumo curto e reescreve o roadmap focando nos - próximos passos (janelas, grafo, fill-ins, bloqueadores). Usar quando o - usuário pedir para "compilar o roadmap", "limpar o roadmap", "atualizar - roadmap para próximos passos", "consolidar entregas no roadmap", "enxugar - docs/roadmap.md", ou quando o arquivo estiver inchado com ciclos já - mesclados em main. ---- - -# Compilar e limpar o roadmap - -Esta skill **reescreve** `docs/roadmap.md` para voltar a ser um documento de **próximos passos**, não um diário de entregas. O histórico detalhado permanece nos planos (`docs/plans/`) e no notebook do projeto — o roadmap só aponta o que ainda importa operar. - -**Não implementa código.** Não cria itens novos (isso é `roadmap-item`). Não escolhe o próximo a implementar (isso é `suggest-next-roadmap-items`). - -**Divisão com as skills irmãs:** - -| Skill | Papel | -| ---------------------------- | ----------------------------------------------------- | -| `compile-roadmap` | **Enxugar** o roadmap: resumir feito, destacar aberto | -| `suggest-next-roadmap-items` | Escolher candidatos entre o que o roadmap já lista | -| `roadmap-item` | Registrar ideia nova / criar plano | -| `implement-roadmap-item` | Auditar plano + implementar o ID escolhido | -| `rebase-on-main` | Após simplify: fetch + rebase em main + conflitos | -| `capture-review-debts` | Triagear débitos de `/simplify` / critique | -| `ship-to-main` | Commit + push + merge main + apagar worktree | -| `close-delivery` | Orquestra rebase + debts (auto-confirm) + ship | - -**Escopo padrão:** só `docs/roadmap.md`. Planos em `docs/plans/` **não** são movidos nem apagados. Só atualize/arquive planos se o usuário pedir explicitamente. - -**Qualidade de decisão (não é tour):** ao comprimir, aplique o filtro de [decision-quality.md](../roadmap-item/decision-quality.md) em escala de documento — enxuga **prosa**, não apaga locks caros nem gatilhos de defer. Inspired-product: Próximos em **problema/resultado**, não feature factory; compile **não** roda discovery nem reescreve o roadmap como OKRs. - -Compile **não** reordena estratégia nem inventa datas de ship para IDs abertos. Âncoras TSE ficam (restrição externa real). - -## Checklist - -``` -- [ ] 1. Ler fontes canônicas (roadmap + notebook + gaps) -- [ ] 2. Inventariar entregues vs abertos (com evidência + tipo de decisão) -- [ ] 3. Mostrar inventário + proposta de corte ao usuário e pedir confirmação -- [ ] 4. Reescrever docs/roadmap.md no template limpo (outcome em Próximos; gatilhos intactos) -- [ ] 5. Verificar links, mermaid, IDs, locks/gatilhos e self-score (≥4/5) -- [ ] 6. Entregar diff resumido + o que foi cortado -``` - -## Passo 1 — Ler as fontes canônicas - -Leia **nesta ordem** (não edite antes de inventariar): - -1. **`docs/roadmap.md` inteiro** — linha "Atualizado em", Onda 0, seções Ciclo/Trilha, grafo mermaid, tabelas por janela, Fill-ins, Cortes, Bloqueadores, Site, Admin, Fora de escopo, Fontes. -2. **`.cursor/rules/projects/nucleos-eleitorais.mdc`** (ou notebook do projeto ativo) — status operacional que pode estar à frente do roadmap. -3. **`AGENTS.md`** — só as seções Known Gaps / Recently resolved / checklist de campanha (para alinhar bloqueadores e não contradizer decisões travadas). -4. **Data de hoje** (contexto da sessão) vs âncoras do calendário — define a janela vigente no cabeçalho limpo. -5. **Planos** — só sob demanda: abra `docs/plans/.md` se o status no roadmap estiver ambíguo (ex.: "implementado" vs "registrado" vs "em branch") **ou** se precisar do **Appetite** / **Adiado com gatilho** / outcome do item aberto. Não leia todos os planos de uma vez. - -Fontes **fora do repo** (`plano-arquitetura-campanha-2026.md`, Cowork) só se o inventário precisar resolver um conflito; cite e não invente. - -## Passo 2 — Inventariar entregues vs abertos - -Monte duas listas. Sinais de **entregue** (qualquer um basta): - -- `✓` no nó mermaid -- "(entregue …)" / "implementado e mesclado" / "engenharia pronta e mesclada" / "MVP entregue" -- Notebook ou AGENTS "Recently resolved" alinhado ao mesmo ID - -Sinais de **ainda aberto** (manter em destaque): - -- Sem marca de entrega -- "registrado" / "proposto" / "futuro" / "validar com produto" -- Engenharia em `main` mas **produção bloqueada** (ex.: C2 dados reais ↔ Onda 0) — trate como **bloqueio operacional**, não como feature a implementar de novo -- Débitos `escala-dry-pos-*` / `*+` sem ✓ -- Fill-ins sem ✓ -- Itens do site/admin/white-label ainda listados como próximos - -Para cada ID, uma linha (coluna **Tipo** obrigatória — guia keep/compress/drop): - -| ID | Estado | Tipo | Evidência (1 frase) | Plano linkado | Ação no compile | -| --- | ------------------------------ | -------------- | ------------------- | -------------- | ------------------------ | -| A4 | entregue | — | mesclado 2026-07-18 | baseline-… | comprimir em Já entregue | -| E4 | aberto | delivery_open | janela 3 | mapa-proj… | manter em Próximos | -| C2 | entregue eng. / bloqueio prod. | expensive_lock | Onda 0 Consent | cadastro-… | 1 linha em Já + Onda 0 | -| C8 | aberto | defer_trigger | gatilho: 3º bulk | escala-dry-… | manter + **gatilho** | -| C5 | proposto | assumption | validar c/ produto | (ou sem plano) | Próximos + **A validar** | - -**Tipos** (alinhados a `capture-review-debts` / `decision-quality.md`): - -| Tipo | Significado | No compile | -| ------------------ | -------------------------------------------------------------------- | ---------------------------------------------------- | -| **expensive_lock** | Consent, access, unicidade, path crítico eleitoral, hold de produção | Nunca “cortar por densidade”; Onda 0 / não cortáveis | -| **delivery_open** | Feature/débito pronto para entrega engenharia | Próximos com meia frase de **problema/resultado** | -| **defer_trigger** | Adiado com evidência de revisitação (DRY prematuro, etc.) | Manter gatilho visível; não virar “depois” vago | -| **assumption** | _(proposto — validar)_, sem plano, sem evidence de discovery | Faixa **A validar**; não inventar data de ship | - -**Não invente status.** Se roadmap e notebook divergirem, prefira o notebook + grep rápido no código só para desempate; reporte a divergência ao usuário. - -**Checagem feature-factory (Inspired, 30s):** se a maioria dos abertos for só nome de feature sem problema/resultado, e vários forem `assumption`, anote no Passo 3 — o rewrite deve corrigir a prosa dos bullets, **não** expandir o escopo nem rodar discovery. - -## Passo 3 — Confirmar antes de escrever - -Mostre ao usuário (conciso): - -1. Contagem: N entregues a comprimir / M abertos a manter / K bloqueios operacionais / A assumptions / D defers com gatilho. -2. O que **sai** do corpo detalhado (seções Ciclo 1/2/2+ verbosas, linhas de janela já ✓, design-refs só de itens feitos, prosa de migration IDs já aplicados, solution-spec de itens ✓). -3. O que **fica** (calendário, princípios/**locks caros**, Onda 0 pendente, grafo dos abertos, janelas só com pendentes, fill-ins abertos, cortes reescritos por tipo, bloqueadores, fora de escopo, faixa A validar se houver). -4. Anti-corte explícito: nenhum `expensive_lock` será movido para Cortes seguros só para enxugar. -5. Pergunta: "Posso reescrever `docs/roadmap.md` assim?" - -**Pare aqui até confirmação**, salvo se o usuário já tiver dito explicitamente "compila/limpa agora" neste turno. - -Opcional (só se pedido): marcar `Status: Done` no topo de planos entregues, ou mover para `docs/plans/archive/` — nunca como default desta skill. - -## Passo 4 — Reescrever no template limpo - -Substitua o arquivo inteiro (não faça um diff cirúrgico em 40 lugares — o risco de inconsistência é maior que um rewrite controlado). Preserve: - -- IDs estáveis (`A5`, `C10`, `E4`, `O0+`, …) -- Links para planos ainda relevantes -- Datas de âncora do calendário TSE (restrição externa — **não** inventar datas de ship para IDs abertos) -- Decisões travadas **caras** e Fora de escopo (podem enxugar prosa, não o sentido) -- Gatilhos de `defer_trigger` / “Adiado com gatilho” dos planos abertos -- Tabela de bloqueadores atualizada - -Use **este esqueleto** (adicione/remova subseções só se o inventário exigir): - -```markdown -# Roadmap — Teqo - -Atualizado em: YYYY-MM-DD (janela N vigente; foco: …; último compile) - -Registro canônico dos **próximos** planos e débitos. Histórico de entregas: -resumo abaixo + planos em [`docs/plans/`](plans/) + notebook -[`.cursor/rules/projects/nucleos-eleitorais.mdc`](../.cursor/rules/projects/nucleos-eleitorais.mdc). - -## Âncoras do calendário eleitoral 2026 (Res. TSE 23.760/2026) - -[tabela de datas — manter; enxugar coluna Consequência se redundante] - -## Princípios e decisões travadas - -[bullets curtos = locks caros de reverter + políticas vigentes; -sem repetir AGENTS inteiro; sem prosa de implementação] - -## Onda 0 — caminho crítico para dados reais - -[só o que AINDA falta: lote jurídico, smoke, onboarding, holds. -Não recontar migrations/features já em main — 1 frase "engenharia de -núcleos/C2/C3/… já em produção de código". -expensive_lock: nunca omitir hold de Consent / LGPD ainda aberto.] - -## Já entregue (resumo) - -Agrupar por trilha/ciclo em **1–3 linhas por grupo**, não por parágrafo de -implementation notes. Exemplo de densidade alvo: - -- **Núcleos MVP + Ciclo 2** — auth/`campaignUser`, território A1/A2, baseline - A3/A4, overview B1, share C1, PWA D1, geometrias B2. -- **Operação** — C2 (eng. pronta; prod. ↔ Onda 0), C3 agenda, C6–C9 escala. -- **Trilha E (parcial)** — E1+E3 metas/estratégia; E2 série/tendência; faltam E4… -- **Fill-ins** — visitados, reset senha/perfil, … (só os ✓) - -Linkar o plano **só** se ainda for referência útil; não listar migration IDs -nem fases `/simplify` no resumo. Já entregue = output comprimido (ok). - -## Próximos — Campanha (`/campanha`) - -### Por trilha (só abertos) - -- **A** — … -- **B** — … -- **C** — … -- **D** — … -- **E** — … -- **Débitos / fill-ins abertos** — … - -Cada bullet: `ID — nome` + **meia frase de problema/resultado** (Inspired: -outcome > output) + link do plano. Sem changelog, sem solution-spec. -Se `defer_trigger`: incluir `· gatilho: `. -Se `assumption`: marcar _(validar)_ — não inventar data. - -### A validar (assumptions) - -[Opcional — só se o inventário tiver `assumption`. Lista curta: ID + o que -falta validar. Impede que `suggest-next` trate como delivery pronto. -Não rodar discovery aqui — só surfacing.] - -### Referências de design (só itens abertos com ref) - -[tabela Item | Design | Plano — remover linhas de itens já entregues] - -### Grafo de dependências (abertos + predecessores mínimos) - -Mermaid: incluir nós **abertos** e só os entregues que ainda são -dependência dura/suave citada. Marcar entregues com `✓` no label se -precisarem aparecer. Remover subgraphs inteiros se todos os nós estão ✓ -e nenhum aberto depende deles. - -### Sequência por janela (só pendentes) - -Tabelas Janela 1–4: **apagar linhas já entregues**. Renumerar "Ordem" -como sequência contínua dos pendentes (ou manter números históricos só -se o usuário pedir continuidade — default = renumerar limpo). - -Colunas: Ordem | Item | Plano | Depende de | Paralelizável com. - -Não adicionar coluna de “deadline de feature” inventada — só âncoras TSE -no cabeçalho/calendário. - -### Fill-ins abertos - -Só itens sem ✓. Uma linha cada + link. Preferir problema/resultado. -`defer_trigger`: gatilho na mesma linha. - -### Cortes seguros / não cortáveis - -Reescrever a lista para citar **apenas IDs ainda abertos**. Remover -conselhos sobre fases já mescladas (ex.: "preferir C6 fases 1–2" se C6 ✓). - -- **Não cortáveis** = `expensive_lock` + path crítico eleitoral / Onda 0 / - base nominal / agenda se forem política vigente. Enxugar **nunca** move - lock caro para Cortes seguros. -- **Cortes seguros** = `delivery_open` barato / polish / assumption sem - evidence — com racional de uma linha. Não cortar o caro “para caber”. - -## Bloqueadores atuais - -[tabela atualizada; remover resolvidos; holds operacionais explícitos] - -## Site público / Admin / White-label / Fora de escopo / Fontes - -[manter seções; Site: separar Já entregue (1 linha) vs Próximos] -``` - -**Regras de corte (obrigatórias):** - -| Cortar do roadmap compilado | Manter | -| -------------------------------------------------------------------------- | -------------------------------------- | -| Seções "Ciclo 1/2/2+" com notas de implementação | Resumo "Já entregue" | -| Linha "Atualizado em" enciclopédica | 1 linha: data + janela + foco | -| Migration IDs / nomes de fases `/simplify` no corpo | Links para planos abertos | -| Design-refs de itens ✓ | Design-refs de abertos | -| Solution-spec / prosa de feature nos Próximos | Meia frase problema/resultado | -| Gatilho perdido (“depois”, “backlog”) | `gatilho: ` intacto | -| "Itens consolidados/removidos" antigo (salvo se ainda explicar um ID vivo) | Fora de escopo atual | -| Prosa duplicada AGENTS/notebook | Ponteiros para AGENTS/notebook | -| Janelas cheias de "(entregue …)" | Só pendentes na janela vigente+futuras | -| Locks caros “para enxugar” | Onda 0 / não cortáveis / princípios | - -**Densidade alvo:** o arquivo compilado deve caber com folga na leitura de uma sessão de priorização — tipicamente **bem menor** que a versão diário. Se após o rewrite ainda parecer um changelog, corte mais o "Já entregue" — **não** corte Onda 0 nem gatilhos. - -**Smell Inspired (corrigir na prosa, não no escopo):** - -| Se… | Então… | -| ------------------------------------------- | ------------------------------------------- | -| Próximos = só nomes de feature | Reescrever bullets como problema/resultado | -| Vários `assumption` misturados com delivery | Separar faixa **A validar** | -| Linguagem de compromisso com data inventada | Remover data; manter só âncora TSE / janela | - -## Passo 5 — Verificar - -Antes de declarar pronto: - -- [ ] Todo ID **aberto** do inventário aparece em Próximos **ou** Bloqueadores **ou** Fill-ins **ou** A validar -- [ ] Nenhum ID entregue reaparece como tarefa a fazer (exceto bloqueio operacional explícito, ex. "C2 dados reais") -- [ ] Links `plans/…` dos itens abertos resolvem (grep / existência do arquivo) -- [ ] Mermaid parseia (sem nós órfãos óbvios; setas só entre IDs que existem no diagrama) -- [ ] Âncoras de calendário e "não cortáveis" ainda cobrem Onda 0 / base nominal / agenda se forem política vigente -- [ ] Nenhum `expensive_lock` foi movido para Cortes seguros ou omitido da Onda 0 por densidade -- [ ] Nenhum `defer_trigger` perdeu o **gatilho** (não virou “depois” vago) -- [ ] Bullets de Próximos legíveis como problema/resultado (não solution-spec) -- [ ] Skills irmãs continuam válidas: `suggest-next-roadmap-items` e `roadmap-item` devem conseguir operar no arquivo limpo - -**Self-score (0–5, ≥4 para declarar pronto)** — 1 ponto cada: - -1. Ainda é documento de **próximos**, não diário de entregas? -2. Locks caros (Onda 0 / não cortáveis / princípios) intactos? -3. Gatilhos de defer preservados? -4. Próximos em outcome/problema (não feature factory)? -5. Assumptions separados ou marcados _(validar)_? - -Se <4 → corrigir o arquivo antes do Passo 6. Se achar item **aberto sem plano**, não invente o plano — liste no resumo final e ofereça `roadmap-item`. - -## Passo 6 — Entregar - -Resposta ao usuário: - -```markdown -## Roadmap compilado - -- Arquivo: `docs/roadmap.md` -- Comprimidos: N itens → seção Já entregue -- Em foco: M abertos (janela vigente: …) -- Bloqueios operacionais: … -- Assumptions / a validar: … -- Defers com gatilho preservados: … -- Qualidade de compile: N/5 - -## Principais cortes - -- … - -## Próximo passo sugerido - -Rodar `suggest-next-roadmap-items` na versão limpa? -``` - -**Proibido neste fluxo:** - -- Implementar código, abrir PR, ou marcar entregas que não estavam evidenciadas -- Apagar ou mover `docs/plans/*` sem pedido explícito -- Inventar IDs / reabrir itens "Fora de escopo" -- Expandir o roadmap com ideias novas (use `roadmap-item`) -- Deixar a linha "Atualizado em" como parágrafo de changelog de novo -- Cortar `expensive_lock` / Onda 0 holds “para caber” -- Apagar gatilhos de defer ou inventar deadlines de feature -- Rodar discovery / opportunity assessment / reescrever o roadmap como OKRs (Inspired fica na **prosa** dos Próximos e na faixa A validar) - -## Exemplo de compressão - -**Antes (ruim no roadmap compilado):** - -> **C6 Escala e DRY pós-C2 — implementado e mesclado em `main` (2026-07-19)** — import bulk drizzle, token HMAC + `supporterImportBatch`, KPI aggregate, shells… Duas passagens `/simplify`; débitos maiores → C8. - -**Depois (resumo Já entregue):** - -> **Operação / escala** — C2–C3 + C6–C9 em `main` (C2 prod. ↔ Onda 0). Débitos abertos: C10, C11. - -**Próximos (forma boa vs feature factory):** - -- Ruim: `C10 — shared drizzleBulk helper` -- Bom: `C10 — um só caminho bulk para imports sem N+1 · gatilho: 3º call site · [plano](…)` diff --git a/.cursor/skills/implement-roadmap-item/SKILL.md b/.cursor/skills/implement-roadmap-item/SKILL.md deleted file mode 100644 index e9ebabcc..00000000 --- a/.cursor/skills/implement-roadmap-item/SKILL.md +++ /dev/null @@ -1,316 +0,0 @@ ---- -name: implement-roadmap-item -description: Recebe o código (ex. A4, C2, D2) ou a descrição de um item do docs/roadmap.md do Teqo, revisa o estado do item no roadmap, analisa-o criticamente contra o estado atual do repositório, revisa o plano detalhado linkado em docs/plans/, produz um plano de implementação acionável (sempre com última fase de documentação da sessão) e — quando o usuário pede para implementar — executa o desenvolvimento com /impeccable nas superfícies de UI e atualiza notebook/plano/roadmap no fim. Usar quando o usuário pedir para implementar, planejar ou revisar um item do roadmap — "vamos fazer o A4", "planeja a implementação de", "revisa o plano do item X", "o que falta para o C2", "implementa o C5" — ou fornecer um ID de trilha do roadmap. ---- - -# Revisar item do roadmap e criar plano de implementação - -Esta skill transforma um item do `docs/roadmap.md` em um plano de implementação confiável e, quando autorizado, em entrega. O ponto central: **o plano em `docs/plans/` foi escrito no passado e o repositório andou desde então** — a skill existe para auditar o plano contra o código real antes de qualquer implementação, não para reescrevê-lo cegamente nem para segui-lo cegamente. - -Superfícies de UI deste item passam pelo fluxo **`/impeccable`** (skill anexada ou em `~/.claude/skills/impeccable`): **shape → craft → critique → polish** (obrigatório em B/C/D), alinhado a `PRODUCT.md` / `DESIGN.md` e aos design-refs do roadmap. **`harden` e `optimize` não entram no pipeline fixo** — só sob gatilho (Passo 8). Itens só de schema/server/utilitário **não** inventam UI via Impeccable — veja Passo 8. - -**Modelo × effort:** antes de executar (Passo 10) ou despachar subagentes, aplique a skill `model-selection` — a classe do item (feature delivery, /simplify, migration, docs) define o modelo recomendado e o effort; subagentes já saem no slug certo via parâmetro `model` da tool Task. - -**Qualidade de decisão:** ao auditar e fatiar, aplique [decision-quality.md](../roadmap-item/decision-quality.md) — caro vs barato, Opções+Recomendação+rejeitadas, appetite do plano, rabbit holes, depth/classitis, tracer bullet cedo. Sem jornada de `design-code-architecture`. - -**Dados → decisão → apresentação:** ao auditar o plano e antes de craft de UI com métricas/mapas/listas analíticas, aplique [data-presentation.md](../roadmap-item/data-presentation.md). Se o plano omite a seção e o item claramente apresenta dados → marque **defasado** e complete no Passo 7. A forma escolhida (número / tabela / mapa / chart) é input do Impeccable — não trocar no polish sem reabrir a decisão. - -**Wireframe em texto (UI):** no plano de implementação (Passo 6), quando houver superfície B/C/D com layout a decidir ou a encaixar, inclua um **wireframe ASCII** da composição planejada — só posicionamento relativo dos blocos, para inspeção rápida antes do craft. Ver bloco no Passo 6. - -## Checklist do fluxo - -``` -- [ ] 1. Localizar o item no roadmap e capturar seu estado completo -- [ ] 2. Verificar o estado real das dependências (roadmap E código) -- [ ] 3. Ler o plano detalhado linkado + fontes satélites -- [ ] 4. Auditar o plano contra o repositório, afirmação por afirmação (incl. Dados → decisão → apresentação) -- [ ] 5. Fechar as questões em aberto com evidência ou recomendação -- [ ] 6. Escrever o plano de implementação em fases verificáveis (incl. fases Impeccable se houver UI; wireframe ASCII se B/C/D com layout; última fase = documentação da sessão) -- [ ] 7. Atualizar docs/plans/ e roadmap se a auditoria achou divergência -- [ ] 8. Classificar superfície UI e preparar gate Impeccable -- [ ] 9. Parar e obter confirmação do plano (a menos que o usuário já tenha pedido implementação explícita) -- [ ] 10. Executar fases: schema/server → UI via /impeccable → verificação AGENTS.md + Aikido → documentação da sessão -``` - -**Escopo por pedido do usuário:** - -| Pedido típico | Até onde ir | -| ---------------------------------- | --------------------------------------------- | -| "revisa / planeja o item X" | Passos 1–8 + resumo; **não** implementa | -| "vamos fazer / implementa o X" | Passos 1–10 (confirmação compacta no Passo 9) | -| "continua / segue a implementação" | Retoma no Passo 10 a partir da fase pendente | - -## Passo 1 — Localizar o item e capturar seu estado - -Leia `docs/roadmap.md` **inteiro** (nunca só a linha do item). Resolva o input do usuário: - -- **ID de trilha** (`A4`, `C2`...): procure na subgraph do grafo mermaid e nas tabelas de janela. -- **Descrição solta**: faça a correspondência por termos nas trilhas, Fill-ins, Bloqueadores, Site público e Admin Payload. Se houver mais de um candidato plausível, pergunte antes de prosseguir; item errado = plano inteiro errado. - -Capture do roadmap, explicitamente: - -| Dado | Onde está | -| --------------------------- | --------------------------------------------------------------------------------- | -| Trilha, janela e ordem | Tabelas "Sequência de execução por janela" | -| Dependências duras e suaves | Grafo mermaid (cheias `-->` vs tracejadas `-.->`) + coluna "Depende de" | -| Já entregue? | Marca `✓` no grafo e nota "(entregue YYYY-MM-DD)" na tabela | -| Cortável ou não cortável | Parágrafo "Cortes seguros" | -| Bloqueio externo | Onda 0 (lote jurídico/Consent) e tabela "Bloqueadores atuais" | -| Design | Tabela "Referências de design" → par `.png`/`.html` em `docs/design-refs/latest/` | -| Link do plano | Coluna "Plano" da tabela de janela | - -**Curto-circuitos:** item marcado `✓` entregue → reporte isso e pare (a menos que o usuário esteja pedindo revisão do que foi entregue). Item na seção "Fora de escopo" ou "Itens consolidados/removidos" → aponte onde foi absorvido/vetado e o racional; não crie plano. - -## Passo 2 — Verificar o estado real das dependências - -Não confie só na marca `✓` do roadmap — confirme no código: - -- Dependência entregue por migration → o arquivo existe em `src/migrations/` e está no `index.ts`. -- Dependência entregue por collection/campo → existe em `src/collections/` e em `src/payload-types.ts`. -- Dependência entregue por utility/componente → existe em `src/utilities/` / `src/components/campaign/` com a assinatura que o plano assume. - -Desfechos: - -- **Dependência dura não entregue** → implementar agora está fora de ordem. Reporte e proponha: (a) implementar a dependência primeiro (aponte o plano dela), ou (b) corte de escopo explícito que remova a dependência — nunca ignore silenciosamente. -- **Dependência suave não entregue** → siga, mas registre no plano de implementação o que degrada e quando revisitar. -- **Bloqueio jurídico (Onda 0)** → a engenharia NÃO espera o jurídico (padrão do projeto: o app falha fechado sem a chave de `Consent`); só a ativação em produção espera. Deixe isso explícito no plano. - -## Passo 3 — Ler o plano detalhado e as fontes satélites - -Leia, nesta ordem: - -1. **`docs/plans/.md`** linkado no item — inteiro. Anote a data de "Atualizado em" e o "Status": a distância entre essa data e o presente calibra o quanto desconfiar no Passo 4. -2. **`.cursor/rules/projects/nucleos-eleitorais.mdc`** (ou o notebook do projeto correspondente) — decisões e status posteriores ao plano costumam estar aqui. -3. **Design ref** (se a tabela do roadmap apontar uma): o `.html`/`.png` em `docs/design-refs/latest/`. A estrutura/UX vale; a paleta NÃO — usar tokens do tema `data-theme='campaign'` (`src/app/(frontend)/styles.css`) e componentes shadcn de `src/components/ui`. -4. **`PRODUCT.md` + `DESIGN.md`** (raiz do repo) — registro (`product`/`brand`), princípios e tokens já commitados. São âncoras do `/impeccable`; leia-os antes de qualquer fase de UI. -5. **AGENTS.md** — seções relevantes ao domínio do item (Campaign auth, Posts & Tags, migrations, convenções de naming). -6. **Planos vizinhos** citados nas seções "Dependências" e "Não escopo" — para saber onde o escopo deste item termina e o dos outros começa. -7. **Seção Dados → decisão → apresentação** do plano (ou ausência dela) — se o item toca KPI/mapa/série/ranking, e a seção falta ou está `N/A` indevido, trate como defasagem no Passo 4. Se preenche, use como contrato da fase de UI (forma + decisão + anti-goals). Inteligência territorial: cruzar com `docs/research/` quando o plano citar padrões dado→decisão. - -Item sem plano detalhado (ex.: só design, como C5; ou fill-in "sem plano detalhado ainda"): primeiro crie o plano seguindo a skill `roadmap-item` (template em `.cursor/skills/roadmap-item/plan-template.md` — inclui classificação Impeccable A–D, brief compacto se B/C/D, e seção Dados), depois continue esta skill a partir do Passo 4. Se o plano já trouxer classe + brief, reutilize no Passo 8 em vez de reclassificar do zero; só reabra se o código/roadmap mostrar que a classe mudou. - -## Passo 4 — Auditar o plano contra o repositório - -Este é o passo que separa uma revisão competente de um "li o plano, parece bom". Para **cada afirmação verificável** do plano, cheque o código: - -- **Caminhos de arquivo citados** existem? (Glob/Read). Arquivo renomeado/movido é a defasagem mais comum. -- **Utilities e componentes "a reusar"** ainda têm a assinatura/comportamento que o plano assume? Leia a assinatura real, não o nome. -- **Premissas de schema** batem com `src/payload-types.ts` e com as migrations em `src/migrations/`? (Ex.: plano escrito quando `cities` era escalar, hoje é array.) -- **Decisões travadas** foram supersedidas? Confronte com a seção "Itens consolidados/removidos" do roadmap, a nota do "Atualizado em" (linha 3 do roadmap) e o notebook do projeto. Precedente real: A2 foi redesenhado de auto-preenchimento forçado para chips opt-in — um plano antigo descreveria o comportamento errado. -- **Já existe implementação parcial?** Grep pelos identificadores que o plano propõe (nomes de collection, componente, action, rota). Se parte já existe, o plano de implementação parte dela, não do zero. -- **Não escopo / rabbit holes ainda válidos?** Itens delegados a outros planos podem já ter sido entregues; rabbit holes omitidos ou estourando appetite contam como defasagem de desenho. - -Classifique cada achado e reporte-os ao usuário: - -1. **Confirmado** — plano bate com o código; segue como está. -2. **Defasado** — fato objetivo mudou (caminho, assinatura, schema); corrija no plano (Passo 7) e ajuste a abordagem. -3. **Conflitante** — decisão de produto/arquitetura diverge (plano diz X, roadmap/notebook posterior diz Y). Adote a fonte mais recente, registre a substituição, e sinalize ao usuário se a divergência for material. -4. **Awaiting-evidence** — afirmação não verificável ainda (ex. métrica de prod, texto jurídico ausente); não invente — registre e prossiga com default explícito. - -**Auditoria de desenho** (além de path/schema) — marque como _defasado_ ou _conflitante_ de design se o plano: - -- inventa **cerimônia de boundary** (layers/adapters) sem volatilidade real; -- propõe **classitis** (pass-through raso) em vez de reusar módulo profundo existente; -- omite **Appetite** / **Rabbit holes** ou estoura o appetite sem corte; -- trata como cortável algo **caro de reverter** (access, Consent, unicidade); -- **apresenta dados** (KPI, mapa, série, ranking) mas omite [data-presentation.md](../roadmap-item/data-presentation.md) / seção no plano, ou escolhe chart/mapa sem decisão nomeável, ou viola anti-goals (`PRODUCT.md` §5: % estadual absoluto, vanity count, gauge SaaS). - -## Passo 5 — Fechar as questões em aberto - -Para cada item de "Questões em aberto" do plano: - -- **Resolvível por evidência** (o código, o roadmap ou o notebook já responderam) → resolva e registre a resposta com fonte. -- **Decisão de produto pendente** → force o formato **Opções | Recomendação | Alternativas rejeitadas** ([decision-quality.md](../roadmap-item/decision-quality.md)); carregue a Recomendação como default no plano de implementação, marcada _(assumido — validar com produto)_. Nunca deixe pergunta sem posição, e nunca bloqueie o plano inteiro numa pergunta que tem default razoável. - -## Passo 6 — Escrever o plano de implementação - -O deliverable é um plano de execução em **fases pequenas e verificáveis**, em ordem de dependência (schema → server → UI → polish → **documentação da sessão**). Respeite o **Appetite** do plano em `docs/plans/` (ou declare um se estiver ausente): a soma das fases de engenharia deve caber; se não couber, corte rabbit holes — não estique. A fase final de documentação é obrigatória e **não** compete com o appetite de engenharia (quota típica 15–30 min à parte). - -Para cada fase: - -- **O que muda**: arquivos concretos (caminho real, criar vs editar), com uma linha do porquê. -- **Quota do appetite**: quanto desta fase consome (ex. `~0,5 dia` / `só server`). -- **Migration** (se houver mudança de schema): nome proposto para `pnpm migrate:create `, o que adiciona, se tem backfill. Seguir a skill `payload-migrations`; `push` é `false` sempre. -- **Como verificar a fase**: teste, tela, ou query específica — fase sem critério de verificação não é fase. -- **Fase de UI**: marque explicitamente `Impeccable: shape|craft|critique|polish` e, se o Passo 8 acionar, `+ harden` / `+ optimize` (ver Passo 8). Não misture schema e layout na mesma fase. Se a seção **Dados → decisão → apresentação** do plano ≠ N/A, a fase de UI **cita a forma escolhida** (número / tabela / mapa / chart) e verifica que a tela responde à decisão nomeada — não “adicionar um gráfico” no polish. -- **Wireframe em texto** (quando fizer sentido — ver abaixo): um desenho ASCII da superfície planejada, colocado **antes** das fases de UI (ou junto da primeira fase de UI), para o usuário inspecionar posicionamento sem abrir Figma. - -### Wireframe em texto (inspeção rápida de layout) - -Inclua no plano de implementação um **wireframe ASCII** quando a resposta for sim a pelo menos um: - -| Incluir se… | Pular se… | -| ----------- | --------- | -| Impeccable **B/C/D** e o item **posiciona** blocos (card novo, coluna, painel, popover, wizard step, empty state com CTAs, strip + lista, etc.) | Classe **A** (sem UI) | -| Layout **novo ou rearranjado** — “onde fica X relativo a Y” ainda não é óbvio no código/design-ref | Só copy, badge, filtro URL, ou um controle isolado sem composição nova | -| Design-ref existe mas o plano **mapeia** só um recorte / adapta a um shell existente (o wireframe rotula o recorte) | Design-ref já é o contrato de layout **e** o plano diz “seguir o ref à risca” sem adaptação — wireframe opcional | - -**O que é (e o que não é):** - -- **É** caixas + rótulos em pt-BR (papéis dos blocos / copy planejada curta), hierarquia top→bottom / left→right, anotações mínimas (`sticky`, `sr-only`, `sheet`, `overflow`). -- **Não é** mock visual (cores, tipografia, ícones), pixel-perfect, nem substituto do design-ref ou do `/impeccable shape`. -- **Não** inventa UI: o desenho reflete o que as fases de UI vão entregar; se o layout ainda tem Opções+Recomendação aberta, desenhe a **Recomendação** e diga isso numa linha. - -**Formato:** um (ou dois) blocos fenced com linguagem `text` — viewport principal; segundo só se mobile vs desktop **divergirem de forma material** (não duplicar o mesmo stack). Largura ~40–72 chars. Uma legenda de 1 linha: superfície + o que está fora do frame. - -Exemplo (ilustrativo — adaptar ao item): - -```text -┌─ /campanha/municipios/[slug] · Overview ─────────────┐ -│ [Voltar] Nome do município [⋯] │ -│ badges: prioridade · tendência · classe │ -├──────────────────────────────────────────────────────┤ -│ Conta da cadeira (card) │ -│ meta · comprometido · déficit │ -├──────────────────────┬───────────────────────────────┤ -│ Sugestões (fila) │ Elegibilidade visita │ -│ · padrão P1 │ ✓ volume — headroom … │ -│ [Aceitar][Adiar] │ │ -└──────────────────────┴───────────────────────────────┘ - Fora do frame: tabs Detalhe / Dossiê; sidebar do (app). -``` - -Se houver **mais de uma superfície** no item (lista + detalhe, ou wizard com passos distintos), um wireframe por superfície primária — não um mural de todo o `/campanha`. - -**Tracer bullet:** se o item for grande, a primeira fatia vertical real (schema mínimo → uma action → uma superfície UI) vem cedo — prova o wiring antes de polish paralelo ou fases cosméticas. - -**Depth:** novas utilities/componentes só se esconderem complexidade; preferir estender `campaign*` / shells existentes a criar wrappers rasos. Para dados: preferir `CampaignMetricStrip` / lista / `BahiaMap` / tabela ao chart novo ([data-presentation.md](../roadmap-item/data-presentation.md)). - -Guardrails que TODO plano de implementação deste repo inclui (cheque um a um contra o item): - -- Pessoa = join com `Contact`; nunca cadastro paralelo. -- Opt-in/PII → `Consent` por chave estável, falhando fechado; texto novo entra no lote jurídico da Onda 0, nunca em rodada separada. -- Local API com `user` → `overrideAccess: false`; escrita multi-collection → transação com `req: { transactionID }`; hooks propagam `req`. -- Collection nova → `admin.group` consistente + hook de revalidação se backing de página pública. -- Identificadores em inglês; strings visíveis em pt-BR; valores de slug/enum em português são dados, não se traduzem. -- Superfície com métricas/mapa/série: três perguntas de [data-presentation.md](../roadmap-item/data-presentation.md) respondidas; anti-goals `PRODUCT.md` §5; sem chart por default. -- Verificação final = checklist do AGENTS.md: `pnpm generate:types`, `generate:importmap` (se componentes), `tsc --noEmit`, `lint`, `test`, `test:e2e`, `build` contra o banco local, scan Aikido dos arquivos editados. -- **Última fase obrigatória — Documentação da sessão:** todo plano gerado termina com uma fase explícita de atualizar a documentação do projeto com o que a sessão fez (não opcional; não misturar com schema/UI). Ver bloco abaixo. - -### Fase final obrigatória — Documentação da sessão - -Sempre inclua como **última fase** do plano (após verificação AGENTS.md + Aikido). Quota típica: `~15–30 min` / fora do appetite de engenharia se o appetite já estiver cheio — a fase existe mesmo assim. - -**O que muda** (só o que a sessão realmente tocou; não reescreva histórico): - -| Superfície | Quando atualizar | O quê | -| --------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | -| `.cursor/rules/projects/.mdc` (ex. `nucleos-eleitorais.mdc`) | Sempre que houve implementação ou decisão material | Bullet de **Status** no topo: o que entrou, data, link do plano, débitos/follow-ups com gatilho; **Decisões** só se algo novo foi travado | -| `docs/plans/.md` | Sempre | "Atualizado em", Status (ex. entregue / parcial), linha de revisão (o quê + por quê + data); rabbit holes adiados se surgiram | -| `docs/roadmap.md` | Item passou a entregue (ou mudou janela/deps) | Marca `✓` + "(entregue YYYY-MM-DD)" no grafo e na tabela; "Atualizado em"; consistência tripla tabela = grafo = Dependências do plano | -| `AGENTS.md` | Mudança de convenção/modelo que outros agents precisam | Seção "Recently resolved" ou domínio afetado — só se o as-built diverge do que AGENTS descreve | - -**Como verificar a fase:** diff das docs cita o ID do item, a data de hoje, e o que ficou de fora / próximo gatilho; notebook e plano não contradizem o roadmap. - -**Pedidos só de planejamento (Passos 1–8):** a fase entra no plano gerado como item futuro; **não** execute a documentação de entrega até haver trabalho real na sessão (exceto correções do Passo 7 por divergência de auditoria). - -Termine o plano com: dependências assumidas (e o que foi verificado no Passo 2), decisões assumidas _(validar com produto)_ no formato Opções+Recomendação+rejeitadas, classificação Impeccable do Passo 8, `Dados: N/A | ` ([data-presentation.md](../roadmap-item/data-presentation.md)), **wireframe ASCII se B/C/D com layout** (ou `Wireframe: N/A — `), rabbit holes / adiados com gatilho, self-score ≥4/5, o que fica explicitamente de fora (com o plano/item para onde vai), e a **fase final de documentação da sessão** (checklist das superfícies acima). - -Se o Passo 7 atualizar `docs/plans/.md` por divergência de UI/layout, **pode** colar o mesmo wireframe sob **Design (Impeccable)** (subseção “Wireframe (texto)”) — opcional; o obrigatório é no plano de implementação mostrado ao usuário. - -## Passo 7 — Atualizar a documentação se houve divergência - -Se o Passo 4 achou itens **defasados** ou **conflitantes** (correção **durante o planejamento**, distinta da fase final pós-implementação no Passo 10d): - -- Atualize `docs/plans/.md`: corrija as seções afetadas, atualize "Atualizado em" e registre a revisão em uma linha (o quê + por quê + data), no padrão das revisões existentes. -- Se a divergência tocar dependências/janela/escopo do item, atualize também o `docs/roadmap.md` nos pontos de consistência (grafo, tabela de janela, "Atualizado em") — a consistência tripla tabela = grafo = seção "Dependências" do plano é obrigatória (ver Passo 6–7 da skill `roadmap-item`). -- Divergência pequena e puramente factual (caminho renomeado): corrija direto. Divergência de decisão de produto: corrija adotando a fonte mais recente e destaque a mudança no resumo ao usuário. - -## Passo 8 — Classificar superfície UI e gate Impeccable - -Antes de implementar (e já no plano do Passo 6), classifique o item: - -| Classe | Critério | Impeccable? | -| ---------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | -| **A — Só backend** | Migration, seed, utility, access, aggregate SQL; zero rota/componente UI | Não — pule Passo 10b | -| **B — UI encaixada** | Edita tela/componente existente sob o tema `campaign` / site público | Sim — craft compacto + critique/polish no alvo | -| **C — UI nova / ambígua** | Rota nova, fluxo multi-tela, ou sem design-ref claro | Sim — shape obrigatório, depois craft | -| **D — Design-ref já existe** | Par em `docs/design-refs/latest/` (tabela do roadmap) | Sim — shape **compacto** (estrutura do ref + tokens `campaign`); não redesenhar a paleta do HTML/PNG | - -**Pipeline Impeccable (B/C/D) — obrigatório vs gatilho:** - -| Passo | Obrigatório? | Quando | -| --------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `shape` → `craft` → `critique` → **`polish`** | Sim (shape conforme classe) | Toda superfície UI deste item | -| `/impeccable harden ` | **Só sob gatilho** | Form/action nova; empty state novo; critique com P0/P1 de resiliência (overflow, erro, rede, permissão). Em `/campanha` **não** abrir rabbit hole de i18n/RTL — o produto é pt-BR; reusar shells/`mapCampaignFormActionError`/feedback existente | -| `/impeccable optimize ` | **Só sob gatilho** | Mapa/lista pesada, bundle client novo, appetite do item é perf, ou critique/`/simplify` com sinal de lentidão. **Medir antes** (o próprio comando exige); sem evidência → não rodar. Perf estrutural vira item de escala (não engorde este delivery) | - -Ordem quando os gatilhos disparam: `critique` → (`harden` se gatilho) → (`optimize` se gatilho) → **`polish` por último**. Nunca rode `harden`/`optimize` no pipeline fixo “por completude”. - -**Regras Teqo (não negociáveis no fluxo Impeccable):** - -1. Carregue a skill `/impeccable` (Setup: `context.mjs` com `--target` na rota/componente concreto; register `product` → `reference/product.md` para `/campanha` e ferramentas; `reference/brand.md` só se o item for superfície de marketing do site público). -2. **Paleta:** tokens `data-theme='campaign'` / site existente. A paleta do UX Pilot (vermelho escuro / navy / dourado) é **anti-referência de cor** — só UX/estrutura do `.html`/`.png`. -3. **Componentes:** reusar `src/components/ui` (shadcn) e `src/components/campaign/*`; não introduzir segundo design system. -4. **Dados na UI:** se Dados ≠ N/A, craft/critique validam a forma contratada no plano (escada de pobreza + decisão nomeável). Critique P0 se a tela mostrar métrica sem “vs quê” / sem próximo passo possível, ou se violar anti-goals (% estadual absoluto, gauge SaaS). Não “melhorar” trocando tabela por chart no polish sem reabrir Opções+Recomendação. -5. **Gates do craft:** se shape for obrigatório (classe C, ou B/D sem brief confirmado), apresente o brief e **pare** até o usuário confirmar — não comprima shape → código numa única resposta. -6. **Pós-UI:** após a fase de UI funcional, rode `/impeccable critique ` (path sob `src/app/(campaign)/...` ou frontend). Trate P0/P1 como bloqueadores de merge; aplique `harden`/`optimize` só se a tabela de gatilhos acima bater; feche com `/impeccable polish ` no mesmo escopo. Snapshot em `.impeccable/critique/` é artefato útil — não substitua o checklist AGENTS.md. -7. **Itens classe A:** declare no resumo "Impeccable: N/A (sem superfície UI)" e siga só engenharia + Aikido. Se a classe A só entrega aggregate para UI futura, ainda assim a seção Dados do plano deve dizer quem consome e qual forma esperada (ou Adiado com gatilho). Wireframe: N/A. -8. **Wireframe vs shape:** o ASCII do Passo 6 é contrato de **posicionamento** para confirmação rápida; o `/impeccable shape` continua dono do brief visual. Se o craft divergir do wireframe, atualize o wireframe na confirmação ou trate como mudança de escopo — não ignore em silêncio. - -No plano de implementação, cada fase de UI deve citar o comando Impeccable e o **alvo** (path ou rota), e declarar explicitamente se harden/optimize estão **in** ou **out** (com o gatilho, se in), por exemplo: - -```text -Fase 3 — UI lista GOTV - Impeccable: shape (compacto; ref Dia-D-GOTV) → craft → critique → harden (form/CSV novo) → polish - optimize: out (sem sinal de perf) - Alvo: src/app/(campaign)/campanha/(app)/apoiadores/... -``` - -## Passo 9 — Confirmação antes de implementar - -Se o pedido foi só planejamento/revisão → entregue o resumo final (abaixo) e **pare**. - -Se o pedido foi implementar ("vamos fazer", "implementa", "entrega o X"): - -- Apresente o plano em fases + classificação Impeccable (A/B/C/D) em forma compacta. -- Se houver wireframe ASCII, **mostre-o nesta confirmação** (é o artefato mais barato para o usuário corrigir “isso fica embaixo, não do lado” antes do craft). -- Peça confirmação **uma vez** (ou "segue" implícito se o usuário já listou as fases a executar). Não reabra o Passo 5 inteiro. -- Só então avance ao Passo 10. - -## Passo 10 — Executar a implementação - -Ordem fixa. Não pule a verificação final. - -### 10a — Schema e server (sem Impeccable) - -Execute as fases de migration, collections, utilities, server actions e testes de domínio. Siga `payload-migrations` quando houver schema. Commits só se o usuário pedir. - -### 10b — UI via `/impeccable` (classes B/C/D) - -1. **Setup Impeccable** (obrigatório no início da primeira fase de UI desta sessão): rode o `context.mjs` da skill impeccable com `--target `; leia `PRODUCT.md` / `DESIGN.md` se o script os imprimir; leia o register reference (`product` ou `brand`). -2. **Shape** (obrigatório em C; compacto em D; em B só se a direção visual ainda for ambígua): siga `reference/shape.md`. Design-ref do roadmap + princípios do PRODUCT.md respondem a maior parte — não repita entrevista longa. Pare para confirmação do brief. -3. **Craft**: siga `reference/craft.md` — implementar no código real do Next.js/Payload, não num sandbox paralelo. Respeite o pipeline do repo (`pnpm` scripts). Anuncie se o harness não tem geração nativa de imagem e siga com o brief + design-ref. -4. **Critique** no alvo entregue: `reference/critique.md`. Persista snapshot; feche P0/P1 antes de declarar a fase de UI pronta. -5. **Harden** (só se o Passo 8 acionou o gatilho): `reference/harden.md` — empty/erro/overflow/permissão no alvo; em `/campanha` não abrir i18n/RTL; preferir shells e padrões de feedback já no repo. -6. **Optimize** (só se o Passo 8 acionou o gatilho): `reference/optimize.md` — medir bottleneck neste alvo, corrigir o que importa, medir de novo; sem evidência, pule. Débito de escala maior que o appetite → `capture-review-debts`, não estique a fase. -7. **Polish** (sempre, por último entre os passos Impeccable): `reference/polish.md` alinhado ao design system existente (`DESIGN.md`, tokens `campaign`, padrões de lista/detalhe/form já no `/campanha`). - -Se o item misturar backend + UI, intercale: complete o mínimo de server necessário para a tela funcionar, craft a UI, volte a server se o critique revelar gap de dados — não adie o Impeccable para "no final depois de tudo". - -### 10c — Verificação de engenharia - -Checklist AGENTS.md completo contra banco **local**; scan Aikido nos arquivos first-party editados (skills `xometry-aikido-scan` / `aikido-scan`). - -### 10d — Documentação da sessão (sempre por último) - -Execute a **última fase** do plano (bloco "Fase final obrigatória — Documentação da sessão" do Passo 6). Ordem: notebook do projeto → `docs/plans/.md` → `docs/roadmap.md` (se entregue ou deps/janela mudaram) → `AGENTS.md` só se a convenção/as-built mudou. - -Regras: - -- Documente o que **esta sessão** fez (código, decisões, débitos com gatilho) — não invente status de deploy ou merge sem evidência. -- Se o pedido era entregar o item end-to-end e a verificação passou, marque o item como entregue no plano + roadmap + notebook na mesma passada. -- Se a sessão ficou parcial (só algumas fases), registre Status parcial + o que falta; não marque `✓` no roadmap. -- Commits das docs só se o usuário pedir commit (mesmo critério do resto). - -Não declare a implementação completa sem 10d. - -## Resumo final ao usuário - -**Após planejamento (Passos 1–8):** (1) item e estado no roadmap (janela, appetite, dependências, bloqueios); (2) veredito da auditoria — confirmado / defasado / conflitante / awaiting-evidence, incl. achados de desenho e de **Dados → decisão → apresentação**; (3) o plano de implementação em fases (quota de appetite + tracer bullet), com fases Impeccable marcadas (`polish` obrigatório; `harden`/`optimize` in|out com gatilho), **wireframe ASCII se couber** (ou N/A), e **última fase = documentação da sessão**; (4) classificação A/B/C/D, `Dados: N/A | `, `Qualidade de decisão: N/5`, e decisões assumidas que merecem validação de produto. - -**Após implementação (Passo 10):** o que entrou em cada fase, resultado do critique/polish (score/P0–P1 se houver), se harden/optimize rodaram (gatilho + resultado) ou por que ficaram out, checklist AGENTS.md + Aikido, superfícies de doc atualizadas no 10d, e o que ficou de fora. - -Se `/simplify` ou `/impeccable critique` deixaram follow-ups **maiores que o cleanup da sessão**, ofereça a skill `capture-review-debts` (triage → confirmação → `roadmap-item`) em vez de registrar débitos ad hoc ou abandoná-los no chat. - -**Fluxo de fechamento em worktree:** após simplify/impeccable → `rebase-on-main` → `capture-review-debts` → `ship-to-main` (atalho único: `close-delivery`). diff --git a/.cursor/skills/plan-issue/SKILL.md b/.cursor/skills/plan-issue/SKILL.md new file mode 100644 index 00000000..9fd1b859 --- /dev/null +++ b/.cursor/skills/plan-issue/SKILL.md @@ -0,0 +1,89 @@ +--- +name: plan-issue +description: Registra uma ou VÁRIAS ideias/features/débitos do Teqo como GitHub Issues rastreáveis — classifica, explora o código, produz plano completo em docs/plans/.md por item, sugere modelo × effort (model-selection) e passa por um GATE de confirmação (overview + wireframes ASCII) antes de criar qualquer Issue via `pnpm agent:register`. Usar quando o usuário pedir para adicionar/registrar algo ("adiciona ao roadmap", "registra essa ideia", "cria um plano para", "planeja a issue", "registra tudo isso"), em lote ou avulso. +--- + +# Planejar e registrar Issues (1..N ideias) + +Esta skill transforma ideias soltas em: (1) um **plano completo** em `docs/plans/.md` por item, e (2) uma **GitHub Issue rastreável** por item (`pnpm agent:register`, frontmatter `id/depends/serializes/priority/model`). **GitHub Issues são a fonte canônica** de spec/status/deps/prio/modelo — `docs/roadmap.md` é legado congelado e **nunca** é editado aqui. + +**Gate de confirmação (obrigatório):** nenhuma Issue é criada no GitHub antes do usuário aprovar o overview do lote (Passo 5). Planos locais podem ser rascunhados antes; Issues, não. + +**Divisão com `work-issue`:** aqui se classifica a superfície UI (A–D), semeia âncoras de design e escreve o plano. **Não** se implementa código nem se roda Impeccable craft/critique/polish — isso pertence a `work-issue`. + +**Qualidade de decisão (não é tour):** aplique [decision-quality.md](decision-quality.md) em silêncio — filtro caro vs barato, Opções+Recomendação+rejeitadas, appetite, rabbit holes, depth check, self-score ≥4 antes de gravar. + +**Dados → decisão → apresentação:** se o item produz, agrega ou exibe números/séries/mapas/KPIs, aplique [data-presentation.md](data-presentation.md) em silêncio antes de travar a Abordagem. Se não há superfície de dados, `Dados: N/A` no plano. + +## Checklist do fluxo + +``` +- [ ] 1. Parse do lote + dedup (intra-lote, Issues existentes, docs/plans, roadmap legacy) +- [ ] 2. Reserva de IDs de uma vez por trilha (roadmap legacy + issuesById()) +- [ ] 3. Por item (ordem topológica): classificar → explorar código → Impeccable A–D → dados → posicionamento → plano completo +- [ ] 4. Sugestão de modelo × effort via model-selection (uma linha por item) +- [ ] 5. GATE: overview do lote + wireframes ASCII das superfícies B/C/D → confirmar/iterar +- [ ] 6. Registro: pnpm agent:register (com --model) por item + commit dos planos +``` + +## Passo 1 — Parse do lote e dedup + +1. **Separe os itens.** A entrada pode vir como 1 ideia ou N (lista, parágrafo, notas). Se a separação for ambígua, assuma a leitura mais provável e liste como você entendeu — a confirmação vai junto do gate. +2. **Deduplique dentro do lote.** Desfechos: **mesclar** (um item, plano único), **absorver** (vira fase de plano existente, sem ID novo), ou **manter separados** com dependência explícita. +3. **Deduplique contra o que já existe:** `gh issue list --state all` (frontmatter `id` via `issuesById()` em `scripts/lib/agent-github.mjs`), grep em `docs/plans/*.md` e em `docs/roadmap.md` (legado). Três desfechos por item: **já coberto** → aponte a Issue/plano existente e não crie nada; **é fase de plano existente** → adicione ao plano existente; **realmente novo** → siga. + +## Passo 2 — Reserva de IDs + +Levante o último ID usado por trilha (A/B/C/D/E) olhando o roadmap legacy + `issuesById()` e distribua sequencialmente para os itens do lote **antes de escrever qualquer plano** (ex.: trilha B em `B78` → os dois itens de B viram `B79`, `B80`). IDs fora de trilha (chore/ops) seguem o prefixo do seu domínio conforme precedentes (`O0+`, `FD+`, `RS+`) ou a trilha temática mais próxima. + +## Passo 3 — Por item: do tipo ao plano completo + +Ordem topológica intra-lote (o plano do dependente cita o ID do dependido, que já existe). Por item: + +1. **Classificar o tipo:** + +| Tipo | Destino | +| ---- | ------- | +| Feature de `/campanha` ou site público com escopo próprio | Issue `kind:feature` com plano | +| Tarefa pequena / chore / débito de engenharia | Issue `kind:chore` + plano curto (ou body direto se trivial) | +| Défice comportamental do fluxo de agentes | `pnpm agent:file-miss` (`kind:agent-miss`), não aqui | +| Bloqueio externo (jurídico/LGPD) | Issue `blocked` + label `needs:consent`/`needs:migration`; texto novo entra no lote jurídico existente, nunca rodada separada | +| Decisão de NÃO fazer | Comentário/doc, não Issue | + +2. **Explorar o código** (depth check): onde a feature se pluga, o que reusar de `src/utilities/*`, `src/components/campaign/*`, `src/lib/*`; schema novo → migration (caro de reverter → Decisão travada com rejeitadas); pessoa → join com `Contact`; opt-in/PII → `Consent` por chave estável falhando fechado. Precedente análogo em `docs/plans/` dita o nível de detalhe. +3. **Classificar superfície UI (A–D)** e semear âncoras: `PRODUCT.md`/`DESIGN.md`, design-ref em `docs/design-refs/latest/` se houver, shells existentes. Classe C exige **brief compacto** (persona, job, estratégia de cor, anti-goals) no plano. Proibido: rodar craft/critique/polish aqui. +4. **Dados → decisão → apresentação** ([data-presentation.md](data-presentation.md)) ou `Dados: N/A`. +5. **Posicionamento:** prioridade `P0..P3` (jurídico/caminho crítico > base de dados > operação de campo > inteligência > plataforma), `depends` (IDs duros), appetite, janela do calendário eleitoral quando relevante, `serializes` quando toca recurso compartilhado (ex.: migrations). +6. **Plano completo** em `docs/plans/.md` seguindo [plan-template.md](plan-template.md) à risca — cabeçalho com `Issue:`/`Priority:`/`Model:`/Appetite, fases verificáveis com quota, tracer bullet, guardrails, rabbit holes, adiados, seção Dados, e **wireframe ASCII** se B/C/D com layout. Self-score ≥4/5 antes de gravar. + +## Passo 4 — Sugestão de modelo × effort + +Aplique a skill `model-selection` (tabela canônica) por item e registre a sugestão no cabeçalho do plano (`Model:`) e no resumo do gate. Referência rápida: `kimi-k3-low` para migration/RBAC/escala-dry; `composer-2.5` para feature UI; `cursor-grok-4.5-high` para docs/chore. O valor vai ao frontmatter `model:` da Issue — é **propriedade da Issue**, verificada (não recalculada) na execução por `work-issue`. + +## Passo 5 — GATE de confirmação (obrigatório) + +Apresente no chat, **antes de criar qualquer Issue**: + +- **Overview do lote** — uma linha por plano: ID, título, prio, depends, appetite, modelo sugerido, link do plano local. +- **Wireframes ASCII** das superfícies B/C/D (copiados dos planos). +- Perguntas acumuladas (se houver) em uma única rodada `AskQuestion`, recomendação primeiro. + +O usuário confirma ou pede modificações; itere até confirmar. **Só depois** avance ao Passo 6. Planos em `docs/plans/` podem ser rascunhados antes do gate (arquivos locais isolados); ajuste-os conforme a resposta. + +## Passo 6 — Registro + +Por item confirmado: + +```bash +pnpm agent:register -- --id --title "" --prio \ + --depends --kind --plan docs/plans/.md \ + --model [--blocked] [--labels extra] +``` + +A Issue nasce `ready` (ou `blocked`) com frontmatter `id/depends/serializes/priority/model` + spec + link do plano. Atualize o cabeçalho do plano (`Issue: #N`). Commit dos planos (commits lógicos por item ou por lote). + +**NÃO faz:** editar `docs/roadmap.md` (legado congelado), implementar código, claim (`pnpm agent:claim` é de `work-issue`). + +## Resumo final + +Tabela do lote (ID, título, prio, depends, appetite, modelo, Issue #N, plano) + em prosa: mesclados/absorvidos/descartados por duplicidade, decisões assumidas _(validar com produto)_, e o que o gate decidiu. diff --git a/.cursor/skills/roadmap-item/data-presentation.md b/.cursor/skills/plan-issue/data-presentation.md similarity index 92% rename from .cursor/skills/roadmap-item/data-presentation.md rename to .cursor/skills/plan-issue/data-presentation.md index d8b95b98..e75c66a6 100644 --- a/.cursor/skills/roadmap-item/data-presentation.md +++ b/.cursor/skills/plan-issue/data-presentation.md @@ -2,7 +2,7 @@ Filtro obrigatório quando um item do roadmap **produz, agrega ou exibe** números, séries, rankings, mapas ou KPIs. Inspirado em `visualization-choice-reporting` (pergunta → tipo de chart → narrativa acionável) e no kernel Teqo (`PRODUCT.md` §5 + `docs/research/`). **Não** é um tour de dashboard design — são três perguntas com resposta registrada no plano. Decisão silenciosa (“só coloca um gráfico”) é defeito. -Aplique em silêncio em `roadmap-item` (ao semear o plano) e em `implement-roadmap-item` (ao auditar e fatiar UI). Se o item **não** apresenta dados (ex.: migration de Consent, invite WhatsApp, form CRUD sem métrica), escreva `Dados: N/A` no plano e pule o resto. +Aplique em silêncio em `plan-issue` (ao semear o plano) e em `work-issue` (ao auditar e fatiar UI). Se o item **não** apresenta dados (ex.: migration de Consent, invite WhatsApp, form CRUD sem métrica), escreva `Dados: N/A` no plano e pule o resto. ## As três perguntas (ordem fixa) @@ -107,6 +107,6 @@ Antes de gravar o plano ou declarar a fase de UI pronta — 1 ponto cada; **< ## Onde registrar -- **`roadmap-item`:** seção **Dados → decisão → apresentação** no `docs/plans/.md` (template). Se N/A, uma linha basta. -- **`implement-roadmap-item`:** auditar essa seção no Passo 4; se ausente e o item claramente apresenta dados → defasado (completar no Passo 7). Nas fases de UI, a escolha de forma é input do craft/critique — não reinventar no meio do polish. +- **`plan-issue`:** seção **Dados → decisão → apresentação** no `docs/plans/.md` (template). Se N/A, uma linha basta. +- **`work-issue`:** auditar essa seção no Passo 4; se ausente e o item claramente apresenta dados → defasado (completar no Passo 7). Nas fases de UI, a escolha de forma é input do craft/critique — não reinventar no meio do polish. - Skills externas (opcional, leitura sob demanda): `visualization-choice-reporting` (famílias de chart + narrativa); `.agents/skills/refactoring-ui/references/data-visualization.md` (quando NÃO chartar); Mapbox patterns só se o item for mapa Mapbox (hoje o mapa Teqo é Leaflet/`BahiaMap`). diff --git a/.cursor/skills/roadmap-item/decision-quality.md b/.cursor/skills/plan-issue/decision-quality.md similarity index 97% rename from .cursor/skills/roadmap-item/decision-quality.md rename to .cursor/skills/plan-issue/decision-quality.md index 6dbb282f..91e805ff 100644 --- a/.cursor/skills/roadmap-item/decision-quality.md +++ b/.cursor/skills/plan-issue/decision-quality.md @@ -35,7 +35,7 @@ Além da **janela** eleitoral, declare um **appetite** (quanto o slice vale), n - Exemplos: `~0,5 dia eng, só utility` · `~1–2 dias, migration + 1 action + encaixe em lista` · `~1 ciclo curto, UI nova 1 rota`. - Se a Abordagem proposta estourar o appetite → cortar rabbit holes / Não escopo, não inflar o item. -- Em `implement-roadmap-item`, cada fase declara quanto do appetite consome; preferir um **tracer bullet** cedo (schema → uma action → uma superfície UI) antes de polish paralelo. +- Em `work-issue`, cada fase declara quanto do appetite consome; preferir um **tracer bullet** cedo (schema → uma action → uma superfície UI) antes de polish paralelo. ## Rabbit holes diff --git a/.cursor/skills/roadmap-item/plan-template.md b/.cursor/skills/plan-issue/plan-template.md similarity index 92% rename from .cursor/skills/roadmap-item/plan-template.md rename to .cursor/skills/plan-issue/plan-template.md index 3a4d38f5..826e7141 100644 --- a/.cursor/skills/roadmap-item/plan-template.md +++ b/.cursor/skills/plan-issue/plan-template.md @@ -1,6 +1,6 @@ # Template de plano (`docs/plans/.md`) -Estrutura extraída dos planos existentes (`overview-lista-nucleos.md`, `visitados-recentemente.md`, etc.). Manter as seções nesta ordem; omitir "Design (Impeccable)" apenas na classe **A** (só backend); **sempre** incluir "Dados → decisão → apresentação" (`N/A` se não houver superfície de dados); omitir a subseção "Referência visual (UX Pilot)" quando não houver design-ref; omitir "Wireframe (texto)" quando não houver layout a posicionar (ver skill `implement-roadmap-item`). +Estrutura extraída dos planos existentes (`overview-lista-nucleos.md`, `visitados-recentemente.md`, etc.). Manter as seções nesta ordem; omitir "Design (Impeccable)" apenas na classe **A** (só backend); **sempre** incluir "Dados → decisão → apresentação" (`N/A` se não houver superfície de dados); omitir a subseção "Referência visual (UX Pilot)" quando não houver design-ref; omitir "Wireframe (texto)" quando não houver layout a posicionar (ver skill `work-issue`). Filtros de decisão (caro vs barato, appetite, rabbit holes, depth): [decision-quality.md](decision-quality.md). Filtro de dados (apresentar? decisão? forma?): [data-presentation.md](data-presentation.md) — obrigatório se houver KPI/mapa/série/ranking; senão `Dados: N/A`. @@ -10,7 +10,9 @@ Filtro de dados (apresentar? decisão? forma?): [data-presentation.md](data-pres Status: rascunho Atualizado em: -Item do roadmap: [docs/roadmap.md](../roadmap.md) () +Issue: # (preencher após `pnpm agent:register`; enquanto não registrado: "—") +Priority: +Model: Impeccable: — Appetite: Responsável: — @@ -21,7 +23,7 @@ Responsável: — Âncoras: `PRODUCT.md` / `DESIGN.md` (register ) · tema `data-theme='campaign'` (ou tokens do site público). -Na implementação (`implement-roadmap-item`): . Declarar `harden`/`optimize` só se o Passo 8 do implement acionar gatilho (não pipeline fixo). +Na implementação (`work-issue`): . Declarar `harden`/`optimize` só se o Passo 8 do implement acionar gatilho (não pipeline fixo). Brief compacto (obrigatório em C; se B ambíguo): @@ -33,7 +35,7 @@ Brief compacto (obrigatório em C; se B ambíguo): ### Wireframe (texto) - @@ -138,7 +140,7 @@ Componentes: ## Referências -- `docs/roadmap.md` () +- GitHub Issue # (spec + frontmatter `id/depends/serializes/priority/model`) - - AGENTS.md — - `PRODUCT.md` / `DESIGN.md` — @@ -150,5 +152,5 @@ Notas: - Nível de detalhe alvo: ~100–130 linhas, como os planos existentes. Menos que isso costuma significar que o Passo 3 (exploração do código) foi pulado. - Classe **A**: omita a seção "Design (Impeccable)" e use no cabeçalho `Impeccable: A — N/A (sem superfície UI)`. - Seção **Dados → decisão → apresentação** é sempre presente (preenchida ou `Dados: N/A`); não omita. -- Não rode `/impeccable craft|critique|polish` ao criar o plano — só classifique e semeie; a skill `implement-roadmap-item` executa o ciclo. +- Não rode `/impeccable craft|critique|polish` ao criar o plano — só classifique e semeie; a skill `work-issue` executa o ciclo. - Self-score de qualidade de decisão (0–5) antes de gravar: ver [decision-quality.md](decision-quality.md). Se Dados ≠ N/A, self-check em [data-presentation.md](data-presentation.md) (≥3/5). Se Rabbit holes ou Adiado com gatilho estiverem vazios de propósito, escreva `Nenhum neste item.` — não omita a seção. diff --git a/.cursor/skills/roadmap-item/SKILL.md b/.cursor/skills/roadmap-item/SKILL.md deleted file mode 100644 index dbecb475..00000000 --- a/.cursor/skills/roadmap-item/SKILL.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -name: roadmap-item -description: Adiciona uma ideia, tarefa ou funcionalidade ao docs/roadmap.md do Teqo no local correto (trilha, janela do calendário eleitoral, grafo de dependências, paralelismo) e cria o plano detalhado correspondente em docs/plans/. Usar quando o usuário pedir para adicionar algo ao roadmap, registrar uma ideia/feature/débito, criar um plano para um item, ou disser "adiciona ao roadmap", "cria um plano para", "registra essa ideia". ---- - -# Adicionar item ao roadmap + criar plano - -Esta skill transforma uma ideia solta em: (1) um item posicionado corretamente no `docs/roadmap.md` e (2) um arquivo de plano em `docs/plans/.md` linkado a partir do item. O roadmap é o registro canônico **em ordem de execução, com dependências e paralelismo explícitos** — um item mal posicionado é pior que um item ausente. - -**Divisão com `/impeccable`, `implement-roadmap-item` e `compile-roadmap`:** aqui se **classifica** a superfície UI e se **semeia** âncoras de design no plano (`PRODUCT.md` / `DESIGN.md` / design-refs / brief compacto). **Não** se implementa UI nem se roda craft/critique/polish — isso pertence a `implement-roadmap-item` (Passos 8–10). Rodar Impeccable completo neste fluxo atrasa o registro e duplica trabalho. Se o `docs/roadmap.md` estiver inchado com ciclos já entregues, rode `compile-roadmap` **antes** de posicionar um item novo — senão o grafo/janelas ficam inconsistentes. - -**Entrada desde reviews:** débitos de `/simplify` / `/impeccable` triageados por `capture-review-debts` chegam aqui já mesclados em lotes — não re-expanda um lote em um item por achado micro. - -**Qualidade de decisão (não é tour):** aplique [decision-quality.md](decision-quality.md) em silêncio — filtro caro vs barato, Opções+Recomendação+rejeitadas, appetite, rabbit holes, depth check, self-score ≥4 antes de gravar. Não abra fases de `design-code-architecture`; só o sistema de decisão. - -**Dados → decisão → apresentação:** se o item produz, agrega ou exibe números/séries/mapas/KPIs, aplique [data-presentation.md](data-presentation.md) em silêncio **antes** de travar a Abordagem — as três perguntas (vou apresentar dados? quais decisões? qual forma mais pobre que auxilia?). Se não há superfície de dados, `Dados: N/A` no plano. Não abra tour de `visualization-choice-reporting`; use só o filtro + tabela de famílias nesse arquivo (e `docs/research/` quando for inteligência territorial). - -## Checklist do fluxo - -``` -- [ ] 1. Ler docs/roadmap.md inteiro (nunca editar sem ler a versão atual) -- [ ] 2. Classificar a ideia e checar duplicidade/absorção -- [ ] 3. Explorar o código relevante para fundamentar o plano -- [ ] 4. Classificar superfície UI (A–D) e semear Impeccable no plano se B/C/D -- [ ] 4b. Dados → decisão → apresentação (ou Dados: N/A) — ver data-presentation.md -- [ ] 5. Decidir posicionamento: seção, ID, dependências, janela, paralelismo, appetite -- [ ] 6. Criar docs/plans/.md a partir do template (incl. rabbit holes / adiados / dados) -- [ ] 7. Editar o roadmap em TODOS os pontos de consistência -- [ ] 8. Verificar links, mermaid, consistência cruzada e self-score de decisão (≥4/5) -``` - -## Passo 1 — Ler o roadmap atual - -Leia `docs/roadmap.md` por completo antes de qualquer edição. A estrutura que importa: - -- **Âncoras do calendário eleitoral** — datas fixas (convenções 20/07–05/08, registro 15/08, propaganda 16/08, congelamento ~20/09, 1º turno 04/10) que definem as janelas. -- **Trilhas com IDs**: A (dados eleitorais e território), B (superfícies de coordenação), C (operação de campo), D (plataforma e engajamento). IDs são sequenciais por trilha (próximo livre, ex.: `C6`, `D3`). -- **Grafo mermaid de dependências** — setas cheias = dependência dura; tracejadas = suave. -- **Tabelas por janela** (Janela 1–4) com colunas Ordem / Item / Plano / Depende de / Paralelizável com. A coluna "Ordem" é numeração global contínua. -- Seções paralelas: **Onda 0** (caminho crítico p/ produção), **Fill-ins**, **Bloqueadores atuais**, **Site público**, **Admin Payload**, **Plataforma white-label**, **Fora de escopo**, **Cortes seguros**. - -## Passo 2 — Classificar e checar duplicidade - -Determine o que a ideia é: - -| Tipo | Destino no roadmap | -| --------------------------------------------- | --------------------------------------------------------- | -| Feature de `/campanha` com escopo próprio | Nova linha numa trilha A/B/C/D + tabela de janela + grafo | -| Feature do site público | Lista da seção "Site público" | -| Melhoria do admin Payload | Lista da seção "Admin Payload" | -| Tarefa pequena que não bloqueia nada | Lista "Fill-ins" | -| Débito/risco que impede algo de ir a produção | Tabela "Bloqueadores atuais" (e possivelmente Onda 0) | -| Fase 2 / multi-tenant | "Plataforma white-label" | -| Decisão de NÃO fazer | "Fora de escopo (por enquanto)" com racional e fonte | - -**Antes de criar item novo, cheque se já existe.** Faça grep no roadmap e em `docs/plans/*.md` por termos da ideia. Três desfechos possíveis: - -- **Já coberto** → não crie nada; aponte o item/plano existente ao usuário. -- **É uma fase de um plano existente** → adicione ao plano existente (nova fase/seção), não crie item paralelo. Precedente: "Gap vs 2022" foi absorvido como Fase 4 do baseline em vez de item próprio. -- **Realmente novo** → siga adiante. - -## Passo 3 — Explorar o código antes de escrever o plano - -Um plano competente cita arquivos, utilities e padrões **reais** — não abstrações. Antes de escrever, localize no código: - -- Onde a feature se pluga (páginas em `src/app/(campaign)/...`, `src/app/(frontend)/...`). -- O que já existe para reusar (`src/utilities/*`, `src/components/campaign/*`, `src/components/ui/*`, `src/lib/*`) — **depth check**: preferir módulo profundo existente a wrapper novo. -- Se exige collection nova ou campo novo → então exige migration (`pnpm migrate:create`) e grupo `admin.group` correto (caro de reverter → Decisão travada com alternativas rejeitadas). -- Se toca pessoa → é join com `Contact`, nunca cadastro paralelo. Se toca opt-in/PII → `Consent` por chave estável, falhando fechado. -- Precedente análogo: encontre o plano existente em `docs/plans/` mais parecido e espelhe o nível de detalhe dele. - -## Passo 4 — Classificar superfície UI e semear Impeccable - -Classifique o item **antes** de travar a abordagem do plano. Use a mesma tabela que `implement-roadmap-item` (Passo 8) — divergência aqui vira plano que a implementação precisa reescrever. - -| Classe | Critério | Neste fluxo (`roadmap-item`) | -| ---------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | -| **A — Só backend** | Migration, seed, utility, access, aggregate SQL; zero rota/componente UI | Declare `Impeccable: N/A` no plano; **não** leia DESIGN.md só por formalidade | -| **B — UI encaixada** | Edita tela/componente existente sob o tema `campaign` / site público | Semear âncoras + decisões de UX no plano; shape completo fica para a implementação | -| **C — UI nova / ambígua** | Rota nova, fluxo multi-tela, ou sem design-ref claro | Semear âncoras + **brief compacto** (ver abaixo); marcar shape obrigatório na implementação | -| **D — Design-ref já existe** | Par em `docs/design-refs/latest/` (tabela do roadmap ou pasta) | Linkar ref no plano; estrutura vale, paleta NÃO; shape compacto na implementação | - -**Se A:** pule o restante deste passo e vá ao Passo 5. - -**Se B, C ou D — âncoras obrigatórias (ler, não reinventar):** - -1. `PRODUCT.md` + `DESIGN.md` na raiz (register `product` → Field Desk / Signal Red para `/campanha`; `brand` só se for marketing do site público). -2. Design-ref em `docs/design-refs/latest/` se existir (grep na tabela "Referências de design" do roadmap). -3. Critique recente em `.impeccable/critique/` só se o item **nasce** de um débito de critique (precedente: FD2 / `field-desk-ux-pos-critique.md`) — cite o snapshot; não rode critique novo aqui. -4. Componentes/shells já no produto (`CampaignPageShell`, `CampaignMetricStrip`, shadcn em `src/components/ui`) — o plano deve reusar, não propor segundo design system. - -**Brief compacto (obrigatório em C; opcional em B se a direção ainda for ambígua):** - -Não rode a entrevista longa de `/impeccable shape` nem craft. No plano (seção "Design (Impeccable)" do template), registre em ≤½ página: - -- Persona / estado de espírito na tela (Alex, Casey, Lia — ou quem o PRODUCT.md nomear). -- Um job principal da superfície (uma frase). -- Estratégia de cor desta superfície: Restrained (default de produto) salvo exceção justificada. -- Anti-goals (ex.: não hero-metric SaaS; não segundo sistema de cards). -- Na implementação: `Impeccable: shape → craft → critique → polish` (C) ou `craft compacto → critique → polish` (B/D). `harden`/`optimize` só sob gatilho do `implement-roadmap-item` (Passo 8) — não no pipeline fixo. - -**Proibido neste passo:** - -- `/impeccable craft`, `critique`, `polish`, `live` — pertencem a `implement-roadmap-item`. -- Entrevista shape de várias rodadas que bloqueia o registro no roadmap. Se C estiver **demasiado** ambíguo para até um brief compacto, pergunte **2–3** perguntas ao usuário (assert-then-confirm), registre as respostas como decisões travadas, e siga — não abra um ciclo Impeccable completo. -- Inventar paleta ou tipografia novas quando `DESIGN.md` / tokens `data-theme='campaign'` já existem. - -## Passo 4b — Dados → decisão → apresentação - -Antes de posicionar e escrever a Abordagem, rode o filtro de [data-presentation.md](data-presentation.md): - -1. **Vou apresentar dados?** Não → `Dados: N/A` no plano e vá ao Passo 5. Sim (neste item ou só como aggregate para outra superfície) → continue. -2. **Quais decisões** (ator + escolha) estes dados desbloqueiam? Sem decisão nomeável → corte vaidade ou rebaixe a contexto secundário. -3. **Como apresentar** na escada de pobreza (número → tabela/lista → série → mapa → chart → dashboard)? Escolha + rejeitadas. Preferir reuso (`CampaignMetricStrip`, lista ranqueada, `BahiaMap`) a lib/chart novos. - -Se o item for inteligência/mapa/metas/fila: leia o trecho relevante de `docs/research/` (playbook dado→decisão) **antes** de inventar métrica ou escala — anti-goals de `PRODUCT.md` §5 valem como Decisões travadas quando a métrica for canônica. - -Registre no plano na seção **Dados → decisão → apresentação** do template. Self-check do arquivo de dados (≥3/5) além do self-score de decisão. - -## Passo 5 — Decidir o posicionamento - -Responda explicitamente, nesta ordem. Para cada escolha não óbvia use **Opções | Recomendação | Alternativas rejeitadas** ([decision-quality.md](decision-quality.md)) — decisão silenciosa é defeito. - -1. **Filtro caro vs barato**: o que neste item é caro de reverter (schema, access, Consent, URL, fronteira de trilha)? Só isso vira Decisões travadas. O resto → Não escopo, fill-in, ou Adiado com gatilho. -2. **Dependências duras**: sem quais itens este não funciona? (ex.: precisa de `cities[]` → depende de A1). Dependências **suaves** melhoram mas não bloqueiam — marque como tracejadas. -3. **Dependentes**: quais itens existentes passam a depender dele? Atualize-os também. -4. **Paralelismo**: sem seta de entrada = paralelizável a qualquer momento → entra na lista de paralelizáveis abaixo do grafo. -5. **Janela**: a mais cedo possível dado (a) as dependências e (b) a âncora de calendário que o item serve. Item que serve a propaganda de rua precisa estar pronto antes de 16/08; nada de migration arriscada depois de ~20/09 (congelamento). -6. **Appetite**: quanto o slice vale (ex. `~1–2 dias eng`)? Janela ≠ appetite. Se a solução proposta estoura o appetite, corte rabbit holes — não inflar o item. -7. **Prioridade dentro da janela**: caminho crítico (jurídico/Onda 0) > base de dados > operação de campo > inteligência > engajamento/plataforma. Quick wins de campo podem furar fila se forem baratos e paralelizáveis. -8. **Cortável?** Decida se entra na lista de "Cortes seguros" (e em que posição) ou na lista de "não cortáveis" — todo item de trilha precisa estar em uma das duas, com racional. **Nunca** classificar como cortável uma decisão cara de reverter só para “caber no tempo”. -9. **Bloqueador externo?** Se depende de jurídico/LGPD (novo texto de `Consent`), o texto entra no **lote jurídico da Onda 0** — nunca criar rodada jurídica separada (decisão travada: fatiar multiplica lead time). - -Se a priorização depender de decisão de produto que você não tem como inferir, posicione com a sua melhor recomendação (Opções+Recomendação explícitos) e marque o item como _(proposto — validar com produto)_, como foi feito com C5. - -## Passo 6 — Criar o plano em `docs/plans/` - -- **Slug**: kebab-case em português, descritivo, curto (padrão existente: `cadastro-nominal-apoiadores.md`, `zonas-por-municipio.md`). Idioma do conteúdo: pt-BR; identificadores de código citados: inglês. -- **Estrutura**: siga [plan-template.md](plan-template.md) à risca — mesmas seções, mesma ordem (incl. **Appetite**, **Rabbit holes**, **Adiado com gatilho**). Leia o template antes de escrever. -- **Qualidade mínima** (o que separa um plano útil de um genérico): - - Cabeçalho traz **Appetite** alinhado ao Passo 5. - - "Decisões travadas" = só o caro de reverter: data, fonte, **por quê** e **alternativas rejeitadas**. Desejo sem rejeitadas não é decisão. - - "Questões em aberto" = **Opções + Recomendação** — nunca pergunta sem posição. - - "Abordagem proposta" tem mermaid + componentes com caminhos reais; **depth check**: reusar shells/helpers profundos (`CampaignPageShell`, `campaignAccess`, …); não propor pass-through raso. - - "Não escopo" cita destino (outro plano/ID); "Rabbit holes" nomeia explosões se tocadas de passagem; "Adiado com gatilho" usa evidência concreta de revisitação (ou `Nenhum neste item.`). - - "Referências" lista os arquivos-fonte reais que o implementador vai abrir. - - Classe Impeccable **A/B/C/D** aparece no plano (cabeçalho ou seção Design); se B/C/D, a seção "Design (Impeccable)" está preenchida. - - Seção **Dados → decisão → apresentação** preenchida ou `Dados: N/A` ([data-presentation.md](data-presentation.md)); se há dados, decisões nomeáveis + forma com rejeitadas. -- Se existir design em `docs/design-refs/latest/`, inclua a subseção de referência visual (UX Pilot) com o aviso padrão de paleta (a estrutura vale, a paleta não — usar tokens do tema `data-theme='campaign'`). -- **Self-score** ([decision-quality.md](decision-quality.md)): ≥4/5 antes de gravar; se <4, corrija o plano — não peça tour ao usuário. Se Dados ≠ N/A, self-check de [data-presentation.md](data-presentation.md) ≥3/5. - -## Passo 7 — Editar o roadmap (todos os pontos de consistência) - -Um item novo de trilha toca **até 7 lugares** no roadmap. Pule apenas os que não se aplicam: - -1. **`Atualizado em:`** (linha 3) — nova data + nota curta do que mudou. -2. **Grafo mermaid** — nó novo na subgraph da trilha (`X9["X9 Nome curto"]`) + setas de/para. Setas cheias `-->` para dependência dura, `-.rótulo.->` para suave. -3. **Lista de paralelizáveis** (parágrafo logo abaixo do grafo) — se o item não tem seta de entrada. -4. **Tabela da janela** — linha nova com Ordem (renumere as seguintes se inserir no meio), Item, link `[detalhes](plans/.md)`, Depende de, Paralelizável com. Atualize a coluna "Paralelizável com" dos itens vizinhos afetados. -5. **Tabela de referências de design** — se houver design correspondente em `docs/design-refs/latest/`. -6. **Cortes seguros / não cortáveis** — insira na posição certa da lista de cortes, ou justifique como não cortável. -7. **Onda 0** — se o item exigir novo texto jurídico/`Consent`, adicione o texto ao lote jurídico único. - -Para itens fora das trilhas (site público, admin, fill-in, bloqueador, fora de escopo): edite só a lista/tabela da seção correspondente + `Atualizado em`, mantendo o padrão da seção — bullets com _(fonte)_ em itálico no final, ou linha de tabela com Status e Fonte. - -## Passo 8 — Verificação final - -- Todos os links relativos resolvem (`plans/.md` a partir de `docs/`, `../roadmap.md` a partir de `docs/plans/`). -- O mermaid continua válido (nomes de nó únicos, subgraphs fechadas — renderize mentalmente ou cole num validador se a edição foi grande). -- Consistência tripla: o que a **tabela de janela** diz em "Depende de" = setas do **grafo** = seção "Dependências" do **plano**. Divergência aqui é o bug mais comum. -- O plano referencia o roadmap (`Item do roadmap:` no cabeçalho) e o roadmap referencia o plano (link na tabela). -- Não inventou ID duplicado nem quebrou a numeração de "Ordem". -- Classe Impeccable do Passo 4 está no plano; se B/C/D, há âncoras (`PRODUCT.md`/`DESIGN.md` e/ou design-ref) citadas — não só "fazer uma tela bonita". -- Dados: seção preenchida ou `N/A`; se há dados, forma de apresentação alinhada à decisão (não chart por default). -- Appetite + Rabbit holes presentes; Decisões travadas caras têm alternativas rejeitadas; self-score ≥4/5. - -Ao final, resuma para o usuário: ID atribuído, janela, **appetite**, dependências assumidas, **classe Impeccable (A–D)**, `Dados: N/A | `, `Qualidade de decisão: N/5`, e as decisões de posicionamento que merecem validação de produto. diff --git a/.cursor/skills/roadmap-items/SKILL.md b/.cursor/skills/roadmap-items/SKILL.md deleted file mode 100644 index 9226511c..00000000 --- a/.cursor/skills/roadmap-items/SKILL.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -name: roadmap-items -description: Registra VÁRIOS itens no docs/roadmap.md do Teqo de uma vez, aplicando a skill roadmap-item a cada um e consolidando as edições do roadmap num único passe (IDs sem colisão, dependências intra-lote, renumeração de Ordem, mermaid, Atualizado em). Usar quando o usuário passar uma lista de ideias/features/débitos para registrar, ou disser "adiciona esses itens ao roadmap", "cria planos para essas ideias", "registra tudo isso no roadmap", "roadmap em lote". ---- - -# Adicionar VÁRIOS itens ao roadmap (lote) - -Esta skill recebe **N ideias de uma vez** e produz: N planos em `docs/plans/.md` + **uma** edição consistente do `docs/roadmap.md` cobrindo todos eles. - -**REQUIRED SUB-SKILL:** `.cursor/skills/roadmap-item/SKILL.md` — leia-a integralmente antes de começar. Ela é a autoridade sobre **como** classificar, explorar, decidir posicionamento e escrever cada plano (incl. [decision-quality.md](../roadmap-item/decision-quality.md), [data-presentation.md](../roadmap-item/data-presentation.md), [plan-template.md](../roadmap-item/plan-template.md)). **Não reimplemente nada dela aqui.** Esta skill só orquestra o lote e resolve o que só existe em lote: colisão de IDs, dependências entre os próprios itens do lote, e uma renumeração/edição única do roadmap. - -**Announce at start:** "Using roadmap-items: N itens → planos individuais + um passe consolidado no roadmap." - -## O que muda em relação a rodar `roadmap-item` N vezes - -| Aspecto | `roadmap-item` × N | `roadmap-items` (esta) | -| -------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------ | -| Leitura do `docs/roadmap.md` | Uma por item | **Uma só** no início (Fase 0) + releitura antes do passe de escrita | -| Atribuição de ID | Próximo livre por trilha, item a item | **Reservados de uma vez** no Fase 1 → sem colisão dentro do lote | -| Dependência entre itens do lote | Invisível (item 3 não sabe que o item 1 existirá) | Resolvida explicitamente (grafo intra-lote no Fase 1) | -| Edição do roadmap (7 pontos) | N vezes, renumerando "Ordem" a cada vez | **Um passe** com renumeração única (Fase 2) | -| `Atualizado em:` | N edições da mesma linha | Uma linha, uma nota cobrindo o lote | -| Perguntas ao usuário | Interrompe N vezes | **Uma rodada** de perguntas agregada (gate do Fase 1) | - -## Checklist do fluxo - -``` -- [ ] 0. Parse do lote: separar itens, deduplicar entre si, ler o roadmap uma vez -- [ ] 1. Por item: Passos 2–6 de roadmap-item (classificar, explorar, posicionar, plano) - com IDs reservados e dependências intra-lote resolvidas -- [ ] 1b. Gate único: perguntas agregadas ao usuário (se houver) -- [ ] 2. Passe consolidado no roadmap (Passo 7 de roadmap-item para todos de uma vez) -- [ ] 3. Verificação cruzada do lote (Passo 8) + resumo em tabela -``` - -## Fase 0 — Parse do lote e leitura única - -1. **Separe os itens.** A entrada pode vir como lista numerada, bullets, parágrafo corrido ou colagem de notas. Se a separação for ambígua (ex.: uma frase que pode ser 1 item ou 3), assuma a leitura mais provável, **liste os itens como você os entendeu** e siga — a confirmação vai junto do gate do Fase 1b, não numa rodada só para isso. -2. **Deduplique dentro do lote.** Antes de olhar o roadmap, cheque se dois itens do lote são o mesmo item, ou se um é fase/sub-escopo de outro. Desfechos: **mesclar** (um item, plano único), **absorver** (vira fase de outro plano), ou **manter separados** com dependência explícita. Registre a decisão — ela vai no resumo final. -3. **Leia `docs/roadmap.md` inteiro uma única vez** (Passo 1 de `roadmap-item`). Se ele estiver inchado com ciclos entregues, rode `compile-roadmap` **antes** — em lote o custo de um grafo inconsistente se multiplica. -4. **Deduplique contra o que já existe** (Passo 2 de `roadmap-item`) para **todos** os itens de uma vez: um grep por lote em `docs/roadmap.md` e `docs/plans/*.md`. Itens já cobertos saem do lote agora (viram linha "já coberto" no resumo), não depois. - -## Fase 1 — Por item: Passos 2–6 de `roadmap-item` - -Para cada item sobrevivente, execute **Passos 2 a 6** da skill filha (classificação, exploração de código, classe Impeccable A–D, filtro de dados, posicionamento com Opções/Recomendação/rejeitadas, appetite, e criação de `docs/plans/.md`). Sem atalhos: um plano de lote tem o mesmo padrão de qualidade de um plano avulso, incluindo self-score ≥4/5. - -Três regras que só existem no lote: - -**a) Reserve os IDs de uma vez, antes de escrever qualquer plano.** Levante o último ID usado por trilha no roadmap lido no Fase 0 e distribua sequencialmente para os itens do lote (ex.: trilha B em `B24` → os três itens de B viram `B25`, `B26`, `B27`). Fixe essa tabela antes de escrever — atribuir ID durante a escrita é como nascem os duplicados. - -**b) Resolva as dependências intra-lote explicitamente.** Um item do lote pode depender de outro item do lote. Monte o grafo do lote antes de decidir janelas: se `B26` precisa de `B25`, `B26` não pode cair numa janela anterior. Ordene a execução do Fase 1 em ordem topológica — o plano do dependente cita o ID do dependido, que já existe. - -**c) Acumule as perguntas, não pergunte item a item.** Quando a skill filha mandaria perguntar (classe C ambígua demais para brief compacto; priorização que depende de decisão de produto), **anote a pergunta com a sua recomendação** e siga para o próximo item. - -### Fase 1b — Gate único - -Se houve perguntas acumuladas, faça **uma** rodada com `AskQuestion` cobrindo todos os itens (a recomendação primeiro, marcada como recomendada). Inclua aqui também a confirmação da separação/dedup do Fase 0 se ela ficou ambígua. - -Se não houve perguntas, **não pare** — siga direto ao Fase 2. - -Não escreva nada no `docs/roadmap.md` antes deste gate. Os planos em `docs/plans/` podem ser escritos antes (são arquivos novos, isolados); ajuste-os depois se a resposta mudar o posicionamento. - -## Fase 2 — Passe consolidado no roadmap - -Releia `docs/roadmap.md` (pode ter mudado desde o Fase 0) e aplique o **Passo 7 da skill filha uma única vez para o lote inteiro**, nos 7 pontos de consistência: - -1. **`Atualizado em:`** — uma data, uma nota curta cobrindo o lote (ex.: "B25–B27 registrados: …"). Nunca N notas. -2. **Grafo mermaid** — todos os nós novos + todas as setas de uma vez, incluindo as **setas intra-lote** do Fase 1b. -3. **Lista de paralelizáveis** — some os itens sem seta de entrada; cheque que nenhum item do lote listado como paralelizável depende de outro item do lote. -4. **Tabelas de janela** — insira todas as linhas e **renumere a coluna "Ordem" uma vez só**, ao final das inserções. Renumerar a cada item é o erro clássico do lote. Atualize "Paralelizável com" dos vizinhos afetados depois que todas as linhas estiverem no lugar. -5. **Tabela de referências de design** — para os itens com par em `docs/design-refs/latest/`. -6. **Cortes seguros / não cortáveis** — cada item do lote precisa cair em uma das duas listas, com racional. Ordene os cortáveis do lote entre si. -7. **Onda 0** — se **qualquer** item exigir novo texto de `Consent`/jurídico, todos os textos do lote entram no **mesmo** lote jurídico existente. Nunca criar uma segunda rodada jurídica. - -Itens fora das trilhas (site público, admin, fill-in, bloqueador, fora de escopo) entram nas suas listas próprias no mesmo passe, mantendo o padrão da seção. - -## Fase 3 — Verificação cruzada e resumo - -Rode o Passo 8 da skill filha **para cada item** e mais estas checagens que só o lote exige: - -- Nenhum ID duplicado — nem contra o roadmap antigo, nem entre itens do lote. -- Coluna "Ordem" contínua e sem repetição após a renumeração única. -- Consistência tripla (tabela de janela ↔ grafo ↔ seção "Dependências" do plano) verificada **item a item**, incluindo as dependências intra-lote nos três lugares. -- Nenhum item do lote em janela anterior à de um item do mesmo lote de que ele dependa. -- Um link de plano por item, todos resolvendo; todo plano com `Item do roadmap:` no cabeçalho. -- `Atualizado em` foi tocado uma vez só. - -**Resumo final** — uma tabela do lote, uma linha por item: - -| Item | ID | Janela | Appetite | Depende de | Impeccable | Dados | Decisão N/5 | Plano | -| ---- | --- | ------ | -------- | ---------- | ---------- | ----- | ----------- | ----- | - -Abaixo da tabela, em prosa curta: itens mesclados/absorvidos/descartados por duplicidade e por quê; decisões de posicionamento que merecem validação de produto; e o que o gate do Fase 1b decidiu. - -## Regras de orquestração - -| Situação | Ação | -| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------- | -| Um item do lote já está coberto no roadmap | Tire do lote no Fase 0; reporte no resumo apontando o item/plano existente | -| Dois itens do lote são o mesmo | Mescle em um plano; o resumo diz o que foi mesclado | -| Um item é fase de um plano existente | Adicione a fase ao plano existente; **não** consome ID novo | -| Um item exige decisão de produto | Posicione com a sua recomendação, marque _(proposto — validar com produto)_, pergunte no gate | -| Um item é grande demais para um slice | Fatie em itens do lote com dependência entre si — não infle o appetite | -| O lote inteiro cai na mesma janela e estoura a janela | Mantenha o registro; sinalize no resumo qual item é cortável primeiro | -| `compile-roadmap` é necessário | Rode antes do Fase 0; registrar em cima de roadmap inchado multiplica a inconsistência | -| O lote é grande (>~6 itens) e a exploração de código é cara | Paralelize **só** o Passo 3 (exploração) com subagents `explore`; escrita fica sequencial | - -**Nunca paralelize a escrita.** Planos podem ser escritos em sequência rápida, mas o `docs/roadmap.md` é editado por um único passe (Fase 2) — dois agentes editando mermaid/tabelas do mesmo arquivo produzem grafo quebrado e "Ordem" duplicada. - -## Posição no fluxo - -``` -ideias soltas (várias) - → roadmap-items (= roadmap-item por item + passe consolidado) - → suggest-next-roadmap-items - → implement-roadmap-item → /simplify + /impeccable → close-delivery -``` - -Para **uma** ideia só, use `roadmap-item` direto — esta skill só paga o overhead a partir de dois itens. diff --git a/.cursor/skills/ship-to-main/SKILL.md b/.cursor/skills/ship-to-main/SKILL.md deleted file mode 100644 index 05b13676..00000000 --- a/.cursor/skills/ship-to-main/SKILL.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -name: ship-to-main -description: >- - Commit all session work, push the feature branch, merge into main, push main, - then remove the session git worktree and delete the feature branch. Use after - capture-review-debts when the user says "commit all, push, merge to main", - "ship", "merge to main", "fecha a entrega", "sobe pro main", or asks to finish - the worktree session and land on main. ---- - -# Ship to main - -Etapa final do fluxo de entrega Teqo em worktree: **commit all → push feature → merge em main → push main → apagar worktree da sessão**. - -**Inspiração:** `superpowers:finishing-a-development-branch` (merge local + cleanup de worktree com `cd` no repo principal), regras de commit/PR do usuário, `gh` quando houver PR aberto. - -**Announce at start:** "Using ship-to-main to land this branch on main and clean up the worktree." - -**Pré-condição típica:** `rebase-on-main` já rodou (branch em dia com `origin/main`). Se estiver atrás de main, rode `rebase-on-main` antes de mergear — não mergeie feature stale. - -## Checklist - -``` -- [ ] 0. Gate de modelo (skill model-selection: pool model; pare se metered premium) -- [ ] 1. Detectar ambiente (branch, MAIN_ROOT, worktree path) -- [ ] 2. Commit all (se houver mudanças; seguir protocolo de commit) -- [ ] 3. Push da feature branch -- [ ] 4. Merge da feature em main (no checkout principal) + push main -- [ ] 5. Remover worktree da sessão + deletar feature branch -- [ ] 6. Reportar URLs/SHAs e avisar se a sessão Cursor ficou em path morto -``` - -## Passo 0 — Gate de modelo - -Esta skill é classe **docs/chores** (git mecânico, sem decisão de código) — skill `model-selection`: o modelo certo é **Grok 4.5 ou Composer 2.5 (pool Cursor Models)**, effort low. Skills não detectam o modelo ativo programaticamente, então o gate é declaratório: - -- Se esta sessão estiver rodando em **modelo metered premium** (Kimi K3, Gemini 3.1 Pro, GLM 5.2, GPT-5.6, Haiku), **PARE antes do Passo 1** e diga: _"ship-to-main é trabalho mecânico de git — o melhor custo/valor é Grok 4.5 / Composer 2.5 (pool). Troque no seletor de modelo, ou confirme que aceita o custo metered."_ Só continue após confirmação explícita do usuário. -- Se já estiver em pool model ou metered barato (Kimi K2.7), siga sem mencionar. - -## Passo 1 — Detectar ambiente - -```bash -git status -sb -FEATURE_BRANCH=$(git branch --show-current) -WORKTREE_PATH=$(git rev-parse --show-toplevel) -GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P) -GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P) -# Primary checkout (safe even when CWD is a linked worktree): -MAIN_ROOT=$(git worktree list --porcelain | awk '/^worktree / {print $2; exit}') -git worktree list -git -C "$MAIN_ROOT" branch --show-current -git fetch origin main -git merge-base --is-ancestor origin/main HEAD && echo "in-sync-or-ahead" || echo "behind-main" -``` - -Se `GIT_DIR == GIT_COMMON`, você já está no checkout principal: `MAIN_ROOT="$WORKTREE_PATH"` e o Passo 5a vira no-op. - -**Guards:** - -| Condição | Ação | -| ----------------------------------------- | ----------------------------------------------------- | -| `FEATURE_BRANCH` é `main`/`master` | Pare — não “ship” de main para main. | -| Detached HEAD | Pare — precisa de branch nomeada. | -| Rebase/merge em andamento | Termine ou aborte antes. | -| Feature atrás de `origin/main` | Rode `rebase-on-main` primeiro. | -| Usuário pediu só commit / só push / só PR | Não execute o fluxo completo; honre o pedido parcial. | - -Capture `WORKTREE_PATH` **antes** de qualquer `cd` — é o path a remover no Passo 5. - -## Passo 2 — Commit all - -Siga o protocolo de commit do usuário (status + diff staged/unstaged + log recente **em paralelo**; mensagem via HEREDOC; sem `--no-verify`; sem amend salvo regras dele). - -```bash -git status -sb -git diff --stat && git diff --cached --stat -git log -5 --oneline -``` - -- Inclua arquivos relevantes da entrega (código + docs de roadmap/planos da sessão). -- **Não** commite segredos (`.env`, credenciais). -- Se working tree limpa e já há commits na feature: pule o commit, siga. -- Mensagem: 1–2 frases no estilo do repo, foco no **porquê** da entrega (item do roadmap se conhecido). - -## Passo 3 — Push da feature - -```bash -git push -u origin HEAD -``` - -Se o rebase reescreveu commits já pushed e o push for rejeitado: - -```bash -git push --force-with-lease origin HEAD -``` - -Use `--force-with-lease` **somente** neste caso (feature branch própria, nunca `main`). Sem lease cego (`--force`). - -## Passo 4 — Merge em main e push main - -Tudo a partir do **checkout principal**, nunca de dentro do worktree da feature: - -```bash -cd "$MAIN_ROOT" -git checkout main -git pull --ff-only origin main -git merge --no-ff "$FEATURE_BRANCH" -m "Merge branch '$FEATURE_BRANCH'" -``` - -Preferência Teqo (solo / worktree): merge local. Se `git pull --ff-only` falhar, pare e diagnostique — não force main. - -**Alternativa só se o usuário pedir PR em vez de merge local:** - -```bash -gh pr create --title "…" --body "…" # ou merge de PR existente -gh pr merge --merge # ou --squash se o usuário pedir -``` - -Após merge local bem-sucedido: - -```bash -git push origin main -``` - -Verifique: - -```bash -git status -sb -git log -3 --oneline -git -C "$MAIN_ROOT" merge-base --is-ancestor "$FEATURE_BRANCH" main && echo "feature ⊆ main" -``` - -**Só avance ao Passo 5 se main contém a feature e o push de main OK.** - -Se testes/CI forem gate explícito do usuário neste momento, espere; caso contrário não rode a suíte completa de AGENTS.md de novo (já veio de simplify/implement). - -## Passo 5 — Apagar worktree + branch - -Ordem obrigatória (igual Superpowers): **merge OK → remove worktree → delete branch**. Nunca delete a branch enquanto o worktree ainda a referencia. - -```bash -cd "$MAIN_ROOT" -``` - -### 5a. Remover worktree da sessão - -Se `WORKTREE_PATH` == `MAIN_ROOT`: **não remova** — não há worktree extra. - -Se `WORKTREE_PATH` ≠ `MAIN_ROOT`: - -```bash -git worktree remove "$WORKTREE_PATH" -# Se dirty residual após merge (raro): -# git worktree remove --force "$WORKTREE_PATH" -git worktree prune -``` - -**Cursor / harness (`~/.cursor/worktrees/...`):** esta skill **é** o consentimento explícito para remover o worktree da sessão após o merge — diferente do default cauteloso de `finishing-a-development-branch`. Ainda assim: - -- Remova **somente** o `WORKTREE_PATH` da sessão atual, nunca outros worktrees listados. -- Remova sempre com CWD em `$MAIN_ROOT`. -- Avise que a janela/agente Cursor pode estar apontando para um diretório já apagado — o usuário deve reabrir o checkout principal (`$MAIN_ROOT`). - -Se existir ferramenta nativa de exit/cleanup de worktree do harness, prefira-a; senão `git worktree remove` como acima. - -### 5b. Deletar feature branch - -```bash -git branch -d "$FEATURE_BRANCH" -git push origin --delete "$FEATURE_BRANCH" 2>/dev/null || true -``` - -Use `-d` (safe). Só `-D` se o merge foi confirmado mas o Git ainda reclama e você verificou `feature ⊆ main`. - -## Passo 6 — Resumo - -1. SHA de `main` após o merge + mensagem do merge/commit -2. Feature branch deleted? remote deleted? -3. Worktree removido: path (ou “n/a — já era main”) -4. Aviso Cursor se aplicável: reabrir `$MAIN_ROOT` -5. Próximo passo natural: `suggest-next-roadmap-items` - -## Anti-padrões - -| Nunca | Em vez disso | -| ------------------------------------------------------------ | ----------------------------------------- | -| Mergear de dentro do worktree feature com checkout bagunçado | `cd "$MAIN_ROOT"` → checkout main → merge | -| `git worktree remove` com CWD dentro do worktree | Sempre a partir de `$MAIN_ROOT` | -| Apagar worktree **antes** do merge/push de main OK | Passo 4 completo primeiro | -| Remover _outros_ worktrees do `git worktree list` | Só `WORKTREE_PATH` da sessão | -| `push --force` em `main` | Só ff / merge commit normal | -| `git clean -fdx` / `reset --hard` no main | Fora de escopo | -| Pular commit com mudanças uncommitted | Commit no Passo 2 ou pergunte | - -## Posição no fluxo - -``` -suggest-next → implement-roadmap-item → /simplify+/impeccable - → rebase-on-main → capture-review-debts → ship-to-main - # ou atalho: close-delivery -``` diff --git a/.cursor/skills/suggest-next-roadmap-items/SKILL.md b/.cursor/skills/suggest-next-roadmap-items/SKILL.md deleted file mode 100644 index 04ab7c4e..00000000 --- a/.cursor/skills/suggest-next-roadmap-items/SKILL.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -name: suggest-next-roadmap-items -description: >- - Lê docs/roadmap.md (e planos/notebook/calendário necessários), filtra o que - já foi entregue e o que ainda está bloqueado por dependência, e indica o - próximo item a implementar no Teqo mais a lista completa — sem teto de - quantidade — dos itens que podem correr em paralelo com ele (priorizados). - Usar quando o usuário perguntar "o que fazer agora", "próximo item do - roadmap", "o que priorizar", "sugere o próximo", "what's next", "qual item - implementar", "o que dá para tocar em paralelo", ou pedir recomendações de - priorização a partir do roadmap. ---- - -# Sugerir próximos itens do roadmap - -Esta skill **só recomenda** — não implementa, não edita o roadmap e não cria planos. O deliverable é **uma recomendação principal + a lista completa dos itens paralelizados com ela** (sem limite de quantidade), ordenados por prioridade: cada um pode ser tocado ao mesmo tempo que o principal, em sua própria branch/worktree, sem brigar com o principal. Não são alternativas ao principal; são trabalho simultâneo possível. Colisões **entre** itens do lote (irmão×irmão) ficam anotadas — o leitor escolhe um subconjunto livre de conflito. Depois disso, o fluxo natural é `implement-roadmap-item` por ID (um por sessão/worktree), ou `roadmap-item` se a sugestão revelar um gap de registro. - -**Divisão com as skills irmãs:** - -| Skill | Papel | -| ---------------------------- | -------------------------------------------------------------------------- | -| `compile-roadmap` | Enxugar roadmap: resumir feito, destacar abertos | -| `suggest-next-roadmap-items` | **Escolher o próximo + todos os paralelos** entre o que o roadmap já lista | -| `roadmap-item` | Registrar ideia nova / criar plano | -| `implement-roadmap-item` | Auditar plano + implementar o ID escolhido | -| `rebase-on-main` | Após simplify: fetch + rebase em main + conflitos | -| `capture-review-debts` | Triagear débitos de `/simplify` / critique | -| `ship-to-main` | Commit + push + merge main + apagar worktree | -| `close-delivery` | Orquestra rebase + debts (auto-confirm) + ship | -| `model-selection` | Modelo × effort por classe de tarefa (custo/valor) | - -## Checklist - -``` -- [ ] 1. Ler docs/roadmap.md inteiro + notebook do projeto -- [ ] 2. Extrair pool de itens ainda abertos (sem ✓ / sem "entregue") -- [ ] 3. Verificar dependências duras e bloqueios externos -- [ ] 4. Pontuar candidatos (calendário × valor × prontidão × risco) -- [ ] 5. Ler planos: principal em profundidade; demais paralelos só cabeçalho se preciso -- [ ] 6. Checar colisões vs principal e listar TODOS os paralelos (priorizados, sem teto) -- [ ] 6b. Para o principal e **cada linha** da tabela paralela, atribuir modelo × effort via `.cursor/skills/model-selection/SKILL.md` (tabela canônica + regras de effort) -- [ ] 7. Entregar principal + lista paralela completa + próximo passo; parar -``` - -## Passo 1 — Ler as fontes canônicas - -Leia **nesta ordem** (não pule o roadmap): - -1. **`docs/roadmap.md` inteiro** — âncoras do calendário, Onda 0, grafo mermaid, tabelas por janela, **tabela do programa "Inteligência de campanha"** (E8–E15/B13/C12 — tem colunas próprias Plano/Classe/Appetite/Janela/Depende de), Fill-ins, Cortes seguros / não cortáveis, Bloqueadores, Fora de escopo. -2. **`.cursor/rules/projects/nucleos-eleitorais.mdc`** (ou notebook do projeto ativo) — status operacional posterior à linha "Atualizado em" do roadmap. -3. **Data de hoje** (contexto da sessão) vs âncoras do calendário eleitoral — define a janela vigente (1–4). -4. **Contexto da conversa** — se o usuário já pediu foco (ex.: "só mapa", "só DRY", "nada de fill-in"), aplique como filtro explícito. - -**Não** leia todos os `docs/plans/*.md` de uma vez. Planos entram só no Passo 5. - -## Passo 2 — Montar o pool de abertos - -Um item está **aberto** se **não** estiver marcado entregue. Sinais de entregue (qualquer um basta): - -- `✓` no nó do grafo mermaid -- "(entregue YYYY-MM-DD)" / "implementado e mesclado" / "engenharia pronta e mesclada" na tabela ou seção Ciclo -- Fill-in com ✓ explícito - -Exclua do pool: - -- Seção **Fora de escopo** e **Itens consolidados/removidos** -- Itens cuja engenharia já está em `main` e só falta ativação externa (ex.: C2 produção = lote jurídico) — marque-os como **bloqueio operacional**, não como candidato de implementação de código -- Itens em hold explícito (ex.: E5 "futuro"; C5 "proposto — validar com produto" só entra se o usuário pedir features de produto) - -Inclua Fill-ins e débitos `escala-dry-pos-*` / `*+` — eles competem na shortlist, mas com peso menor que features de caminho crítico (Passo 4). - -Inclua também os itens da tabela de programa (hoje: "Inteligência de campanha") — são itens de trilha normais para fins de pool; a coluna "Depende de" deles é a fonte de dependências duras, e o embasamento de valor (OMTM, anti-metas) está sumarizado no notebook e em `docs/research/` — **não** releia o relatório de discovery para ranquear. - -## Passo 3 — Filtrar por prontidão - -Para cada aberto, classifique: - -| Estado | Critério | Ação na shortlist | -| --------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -| **Pronto** | Todas as dependências **duras** (setas `-->` / coluna "Depende de") entregues | Candidato normal | -| **Quase** | Só falta dependência **suave** (`-.->`) | Candidato; note o que degrada se seguir sem a suave | -| **Bloqueado duro** | Dependência dura aberta | Fora da shortlist; cite o predecessor a fazer antes | -| **Bloqueado externo** | Jurídico (Onda 0), TSE após 15/08, resultado TSE 2026 (E15, pós-eleição), validação de produto | Fora da shortlist de código; mencione em "Bloqueios" | -| **Cortável agora** | Está em "Cortes seguros" **e** o prazo da janela aperta | Só sugerir se for quick win barato ou se o usuário pedir DRY | - -Dependência "deploy remodelagem" (ou outro ato operacional com código já pronto) conta como **Quase**, não bloqueado duro: a engenharia pode começar em local; só a ativação em produção espera o deploy — note isso na shortlist. - -Confirme no notebook/código só quando o roadmap e o notebook **divergirem** (ex.: roadmap sem ✓ mas notebook diz entregue). Não faça auditoria profunda de código aqui — isso é `implement-roadmap-item`. - -## Passo 4 — Pontuar e ranquear - -Atribua a cada **Pronto** / **Quase** uma nota 1–5 (soma ponderada mental; não precisa ser fórmula rígida). Âncoras Teqo: - -| Peso | Critério | Preferir | -| ----- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Alto | **Calendário** | Serve a janela vigente (hoje → próxima âncora). Janela 1–2: produção, base nominal, agenda, fundação de dados. Janela 3: inteligência, mapa, engajamento. Janela 4: só o que falta p/ dia D + estabilização; nada de migration arriscada perto de ~20/09. | -| Alto | **Caminho crítico** | Onda 0 / não cortáveis > operação de campo > inteligência > plataforma/engajamento > fill-in DRY. **Atenção:** o núcleo do programa de inteligência (E8/E9/C12) está em "não cortáveis" — conta como caminho crítico, não como "inteligência" genérica; e **C12 é perecível** (cada semana de campanha sem registro é história irrecuperável para o backtest E15 — o atraso dele tem custo que não se recupera depois) | -| Médio | **Paralelismo / desbloqueio** | Item que desbloqueia vários outros (ex.: A7 antes de A5/B3/E\*) ou fecha um lote (E4 após E1–E3) | -| Médio | **Prontidão do plano** | Tem `docs/plans/.md` acionável > só design-ref > sem plano (C5) | -| Médio | **Custo vs valor** | Quick win de campo / insight barato pode furar fila; cadeia `escala-dry-pos-*` só se a superfície já dói (volume, lista lenta) ou se for Fase 1 de alto ROI citada em "Cortes seguros" | -| Baixo | **Risco** | Migration + Consent novo = mais caro; item só utility/seed = mais barato | - -**Regras de desempate (travadas):** - -1. Não sugerir como #1 um fill-in DRY se houver feature **Pronta** da janela vigente que desbloqueie operação (ex. atuais: E8, C12, E9; B8 F2; D2). -2. Preferir **uma fatia** de um programa (um ID: E8, C12, …) a "fazer o programa de inteligência inteiro" — diga qual plano (`docs/plans/.md`), e respeite a ordem do grafo (E8 antes de E9/E10/E12; C12 antes de E11/E14/E15). -3. Cadeias DRY (`escala-dry-pos-*` / `*+`) entram no lote paralelo se passarem nos testes do Passo 6, mas **ficam no fim da ordenação** (depois de features/quick wins de campo) — não competem com o #1. -4. Itens _(proposto — validar com produto)_ (ex.: C5) só entram se o usuário pedir exploração de produto; senão liste em "Depois / validar". -5. Trabalho externo (lote jurídico) **nunca** substitui um candidato de engenharia — reporte em seção própria. -6. O #1 é o de maior valor/urgência de calendário, **nunca** o "mais isolado". Isolamento decide quem entra no lote paralelo (Passo 6), não quem é o principal. - -## Passo 5 — Aprofundar o principal (e skim nos paralelos) - -1. **Principal:** abra o plano linkado (`docs/plans/...`) — leia cabeçalho, Status, Dependências, Não escopo, e o tamanho das fases (1 parágrafo basta). Para itens do programa de inteligência, a tabela do programa já traz classe Impeccable/appetite/depende-de — só abra o plano do candidato final se precisar de detalhe além da tabela. -2. **Demais candidatos ao lote:** não leia o plano inteiro. Use o roadmap + notebook + (se houver dúvida de superfície) só o cabeçalho do plano (Status / appetite / dependências). Progressive disclosure: plano completo só quando a colisão for ambígua. -3. Se houver design-ref na tabela do roadmap para o principal, cite o nome do par em `docs/design-refs/latest/` (não precisa abrir o HTML). -4. Classifique superficialmente Impeccable A/B/C/D no principal — uma letra + meia frase. Nos paralelos, a letra basta quando conhecida (tabela do programa / cabeçalho); senão omita. - -Se dois candidatos forem quase equivalentes para o #1, prefira o de menor risco de migration / o que o calendário pune mais se atrasar. - -### Modelo × effort (principal + paralelos) - -Antes de entregar, leia **só a tabela canônica e as regras** em `.cursor/skills/model-selection/SKILL.md` (não precisa reler gates de `/simplify`/`ship` aqui). Para **cada** item (principal e todas as linhas paralelas), escolha **um** par modelo + effort para a **worktree de `implement-roadmap-item`**: - -| Sinal no item | Classe típica → modelo (1ª escolha) · effort | -| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -| Feature/fill-in B/E/C multi-arquivo, gates completos, sem migration de risco | Composer 2.5 · **medium** | -| Fix pequeno/localizado (1 arquivo, teste quebrado) | Kimi K2.7 · medium | -| Migration, access/RBAC, Consent/LGPD, hooks com `req`/transação | Kimi K3 · **high** | -| Perf/loader/bundle/waterfall (medir antes de otimizar) | Gemini 3.1 Pro · medium | -| Débito `escala-dry-pos-*` com risco de race/closure/drift de string (auditoria) | Kimi K3 · high na fase `/simplify`; entrega em si pode ser Composer · medium se o plano for só refactor mecânico | -| R6 / passes `/impeccable` / critique multi-superfície | Composer · medium na implementação; **avisar** K3 · high na sessão que rodar `/impeccable` (subagentes herdam o modelo pai) | -| Rename/chore/docs/roadmap bookkeeping | Grok 4.5 · **low** | -| Discovery/research longo pt-BR | GLM 5.2 · medium | - -**Formato na célula da tabela:** `Composer 2.5 · med` — modelo legível + effort `low`/`med`/`high` (abrevie `medium` → `med` na tabela para caber). Opcional, após travessão: meia frase da classe (`perf loader`, `migration+Consent`, etc.). Se o item tiver **duas fases** com classes diferentes (ex.: D2 schema + polish), use a fase de **maior blast radius** na célula e uma nota curta em "Por que agora" (`schema: K3 high`). - -**Pool primeiro:** não recomende K3/Pro/GLM para trabalho que cabe em Composer/Grok sem violar as regras de effort (migrations e Consent são exceção obrigatória). - -## Passo 6 — Checar colisões e listar TODOS os paralelos - -Premissa: cada item roda na **sua própria branch/worktree** e fecha com `close-delivery` (rebase em `main` antes do merge). Logo, paralelizável não é "cabe no mesmo dia" — é "pode viver em worktree separada e reencontrar `main` sem conflito que exija reescrita **com o principal**". - -Um candidato entra na lista paralela quando passa **nos três testes contra o principal**: - -1. **Independência vs principal** — não depende (nem suave) do principal, e o principal não depende dele. Dependência suave em ambos os sentidos → fora da lista, vai para "Serializar depois". -2. **Superfície disjunta do principal** — não disputa nenhuma superfície serializadora com o principal (tabela abaixo). -3. **Fechamento independente** — pode ser mesclado sozinho e entregar valor sem esperar o principal (nada de "só faz sentido junto"). - -**Sem teto de quantidade.** Percorra **todos** os Pronto/Quase (exceto o principal) em ordem de score e inclua cada um que passar nos três testes. Não corte em 2–4 nem em 5. - -**Colisões irmão×irmão:** itens na lista **podem** colidir entre si (mesma migration, mesma rota, mesma seam). Isso **não** os remove da lista — anote na coluna/nota `Colide com` (IDs dos irmãos + superfície). O leitor monta um subconjunto livre de conflito. Opcionalmente, ao final, sugira **um** clique máximo sem colisão mútua ("subconjunto sem atrito") usando greedy por score — isso é ajuda, não substitui a lista completa. - -**Superfícies serializadoras do Teqo (no máximo 1 item ativo por linha em qualquer worktree simultânea):** - -| Superfície | Por que serializa | -| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -| `src/migrations/` (SQL + `.json` snapshot + `index.ts`) e o `src/payload-types.ts` que a segue | A cadeia de snapshots é linear: dois itens com migration não se resolvem por merge textual, um tem que refazer | -| Artefato TSE (`src/lib/electionAggregates/`, `build:election-aggregates`, orçamento de bytes) | Arquivo gerado grande + teste de tamanho; dois geradores em paralelo colidem inteiros | -| Seams do sistema de listas (`CampaignTable`, `campaignListUrl`, shells de `campaign/shared`) | Quem **altera** a seam serializa; quem só **consome** pode ir junto | -| Um mesmo loader/rota de domínio (ex.: `municipalityPageData.ts` + colunas da lista) | Precedente real: E9/E10/B13 empilharam no mesmo arquivo | -| Mesma collection/global no schema (mesmo sem migration nova) | Access, zod, view models e form mudam juntos | - -**Não** serializam (append trivial, resolve no rebase): `docs/roadmap.md`, `docs/plans/`, `campaignIntelligenceConcepts.ts` (E18), `nav.ts`, novos arquivos em domínios distintos. Só avise a ordem de merge. - -Se um candidato falha só pelo teste 2 contra o principal, liste-o em "Serializar depois de \" em vez de descartar do radar. - -Se **nada** for paralelizável com o principal, diga isso explicitamente e nomeie o que destrava paralelismo (normalmente: o principal ser o único com migration / única superfície quente). - -## Passo 7 — Entregar e parar - -Formato obrigatório da resposta (conciso; sem reescrever o roadmap): - -```markdown -## Contexto - -- Janela vigente: N (âncora → data) -- Bloqueios externos: … -- Foco do usuário (se houver): … - -## Recomendação principal - -**ID — Nome** — uma frase do porquê agora. - -- Plano: `docs/plans/…` -- Dependências: ok / suave pendente: … -- Impeccable: A|B|C|D -- Modelo (skill `model-selection`): · effort — classe da tarefa em meia frase -- Próximo passo: skill `implement-roadmap-item` neste ID (na worktree do item, já no modelo acima) - -## Em paralelo com ele (todos, por prioridade) - -Cada um em sua própria worktree; nenhum depende do principal. Ordenados por score (maior primeiro). **Sem limite de linhas.** - -| # | ID | Por que agora | Por que não colide com o principal | Colide com (irmãos) | Modelo (`model-selection`) | Plano | -| --- | --- | ------------- | ---------------------------------- | ------------------- | -------------------------- | ----- | -| 2 | … | … | … | — / ID (superfície) | Composer 2.5 · med — … | … | - -- Migration no lote: liste os IDs com migration (no máximo um por worktree simultânea). -- Serializar depois do principal: \ — colide em \. -- Subconjunto sem atrito (opcional, greedy): #2, #4, #7… — um clique máximo sem colisão mútua. -- Ordem de merge sugerida: … (só se importar) - -## Deixados de fora (amostra) - -- **Bloqueados:** ID — falta X -- **Cortáveis / depois:** ID — racional curto -- **Validar com produto:** … - -Quer que eu rode `implement-roadmap-item` em algum destes? -``` - -**Proibido neste fluxo:** - -- Implementar código, abrir PR, ou marcar item como entregue -- Editar `docs/roadmap.md` / `docs/plans/` (se achar inconsistência material, **reporte** e ofereça `roadmap-item` / correção via `implement-roadmap-item` Passo 7) -- Inventar IDs ou itens que não estão no roadmap -- **Omitir** um Pronto/Quase que passa nos três testes contra o principal só para "encurtar" a resposta — a lista paralela é completa; concisão vem das células curtas, não do corte -- **Omitir** a coluna **Modelo** na tabela paralela ou deixar linha sem par modelo × effort — cada linha precisa de recomendação para a worktree de implementação -- Apresentar o lote como "alternativas ao principal" ou como um plano de execução sequencial -- Colocar na lista paralela item que colide com o **principal** (Passo 6) — ele vai para "Serializar depois" -- Auditoria afirmação-a-afirmação do plano (isso é `implement-roadmap-item`) - -Se o usuário já disser "faz o X" / "implementa o segundo", pare esta skill e invoque `implement-roadmap-item` no ID escolhido (um por sessão/worktree). diff --git a/scripts/agent-register.mjs b/scripts/agent-register.mjs index 048554f7..d31b29db 100644 --- a/scripts/agent-register.mjs +++ b/scripts/agent-register.mjs @@ -13,12 +13,12 @@ import { dieAgent, gh, issuesById, parseArgs, serializeFrontmatter } from './lib const die = dieAgent('register') const { flags } = parseArgs( process.argv.slice(2), - new Set(['id', 'title', 'prio', 'depends', 'kind', 'plan', 'body', 'labels']), + new Set(['id', 'title', 'prio', 'depends', 'kind', 'plan', 'body', 'labels', 'model']), ) if (!flags.id || !flags.title) die( - 'Usage: pnpm agent:register -- --id --title [--prio P2] [--depends A,B] [--kind feature] [--plan path] [--body text] [--labels extra,labels] [--blocked]', + 'Usage: pnpm agent:register -- --id <ID> --title <title> [--prio P2] [--depends A,B] [--kind feature] [--plan path] [--body text] [--labels extra,labels] [--model slug] [--blocked]', ) const priority = /^P[0-3]$/.test(flags.prio ?? 'P2') @@ -34,7 +34,13 @@ if (existing) die(`An issue with id ${flags.id} already exists: #${existing.number} — ${existing.title}`) const body = serializeFrontmatter( - { id: flags.id, depends, serializes: [], priority }, + { + id: flags.id, + depends, + serializes: [], + priority, + ...(flags.model ? { model: flags.model } : {}), + }, [flags.plan ? `Plano: [\`${flags.plan}\`](${flags.plan})` : null, flags.body ?? ''] .filter((chunk) => chunk !== null) .join('\n\n'),