teqo-backup/.cursor/skills/plan-issue/data-presentation.md
Francisco Ignácio Fontoura Solla 1c1a379897 feat: plan-issue skill
2026-07-30 12:22:05 -03:00

112 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Dados → decisão → apresentação
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 `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)
Responda nesta ordem. Pular para “qual chart?” antes de fechar (1)–(2) é o erro clássico.
```text
1. Vou apresentar dados?
2. Quais decisões serão tomadas a partir destes dados?
3. Como apresentar estes dados para auxiliar essa decisão de forma efetiva?
```
### 1. Vou apresentar dados?
| Resposta | Critério | Ação no plano |
| ------------------------------ | ---------------------------------------------------------------------- | ------------------------------------------------- |
| **Não** | Só schema/action/access; nenhum número lido por humano nesta entrega | `Dados: N/A` — fim |
| **Sim, derivado / API só** | Utility/aggregate que **outra** superfície já consome (ou item futuro) | Registrar payload + quem consome; UI fica no dono |
| **Sim, superfície neste item** | Lista, detalhe, dashboard, mapa, CSV export legível, card de insight | Preencher seção completa abaixo |
Se “sim”: profile rápido do dado — tipo (categórico / numérico / temporal / geo), granularidade (praça / município / TI / estado), tamanho típico (1 KPI vs 436 linhas vs série 3 anos), e se é **absoluto ou relativo** (no `/campanha` electoral, preferir relativo/local — ver anti-goals).
### 2. Quais decisões serão tomadas a partir destes dados?
Uma frase por decisão, no formato **ator + escolha**. Sem decisão nomeável → o dado é vaidade; corte ou rebaixe a “contexto secundário”.
Exemplos Teqo bons:
- Coordenador: “nesta semana, atacar déficit descoberto em quais Praças?”
- Assessor: “minha meta fecha? se não, renegociar pledge ou abrir demanda?”
- Staff: “comparar candidato X vs Solla neste município — manter ou pivotar discurso?”
Exemplos ruins (rejeitar):
- “Ter visibilidade do % estadual” (anti-goal; não decide alocação)
- “Ver quantos apoiadores cadastrados” sem vínculo a cobertura/meta
- “Dashboard bonito para impressionar”
Se o item toca inteligência de campanha / mapa / metas / fila: consulte **antes** o playbook em `docs/research/relatorio-entrevista-persona-campanha.md` (§6 padrões dado→decisão) e o anti-catálogo do plano-mestre `docs/plans/inteligencia-campanha.md`. Não invente métrica que o research vetou.
### 3. Como apresentar para auxiliar essa decisão?
Escolha a **forma mais pobre que ainda responde a decisão** (depth: reusar shell existente > chart novo > lib de charts). Registre no plano: forma + racional + o que foi rejeitado.
**Escada de pobreza (preferir o degrau mais baixo que resolve):**
| Degrau | Quando usar | Reuso Teqo típico |
| ------------------------------ | ----------------------------------------------------------------- | ----------------------------------------------------- |
| **Número + contexto** | 1–2 valores, “fecha / não fecha”, delta vs meta/semana | `CampaignMetricStrip`, linha no overview |
| **Tabela / lista ranqueada** | Comparar muitas entidades (Praças), ordenar por déficit/cobertura | `PlazaList` + colunas; fila de alocação |
| **Série temporal simples** | Evolução curta (3–5 pontos: 2014/2018/2022 ou delta semanal) | sparkline / tabela ano×valor; não multi-eixo |
| **Mapa (cor / símbolo)** | Decisão é **onde** agir; geo é central à pergunta | `BahiaMap` + escala relativa (quantil/LQ), não % est. |
| **Chart (barra / linha)** | Comparação de poucas categorias ou tendência com >~5 pontos | shadcn/`src/components/ui`; tokens `campaign` |
| **Chart composto / dashboard** | Só se appetite e research pedirem; senão rabbit hole | Adiar com gatilho |
**Família de pergunta → forma** (resumo de visualization-choice-reporting, calibrado ao Field Desk):
| Pergunta que o dado responde | Preferir | Evitar neste produto |
| ---------------------------------- | -------------------------------- | ----------------------------------- |
| Quanto falta / cobre a meta? | Número + % cobertura + delta | Gauge/velocímetro SaaS, hero-metric |
| Onde está o buraco / oportunidade? | Mapa relativo ou lista ranqueada | Choropleth de % estadual absoluto |
| Como evoluiu no tempo? | Linha/sparkline ou tabela anos | Pie; dual Y-axis |
| Como A se compara a B (poucos)? | Barra horizontal ou tabela | Pie com muitas fatias; 3D |
| Qual a composição do todo? | Stacked bar ou tabela | Donut decorativo |
| Correlação / nuvem de pontos? | Quase nunca em v1 `/campanha` | Scatter exploratório sem decisão |
**Narrativa mínima na UI** (mesmo sem relatório formal): o bloco de dados deve permitir ler, nesta ordem — **insight → padrão → contexto (vs meta/histórico) → implicação → próxima ação possível**. Título descritivo (“Votos por mês”) sem insight é falha. Em `/campanha`, a “ação” é menu para julgamento humano (nunca auto-decisão) — alinhado ao research.
## Anti-goals Teqo (não negociar sem fonte nova)
- KPI de **% estadual absoluto** como escala principal (achatamento; DF ≠ majoritária).
- Contagem bruta de cadastros / “vanity metrics” sem vínculo a cobertura/meta/fila.
- Cartograma, gauge, rainbow choropleth, dual-axis enganoso.
- Mapa bonito com pergunta errada (visualização serve à análise; análise serve à decisão — research § ordem Brewer/Pickle).
- Segunda lib de charts / design system paralelo; inventar paleta fora de `data-theme='campaign'`.
- Sugestão automática sem registro de decisão humana (C12 / motor de sugestões).
## Quando NÃO usar gráfico
- Um único número decisivo → número tipográfico + unidade + vs quê.
- Dois números → lado a lado com delta %.
- Poucas linhas densas de auditoria → tabela.
- Export/CSV para operação → tabela; chart é opcional depois.
## Caro vs barato nesta superfície
| Caro (Decisão travada + rejeitadas) | Barato (Não escopo / Adiado) |
| ------------------------------------------------ | ----------------------------------------- |
| Métrica canônica (fórmula, denominador, quem vê) | Cor da barra, ordem de colunas |
| Escala do mapa (absoluta vs % vs quantil/LQ) | Tooltip copy |
| Staff-only vs leader-visible | Sparkline vs número só |
| Persistência de derivado vs compute on read | Biblioteca de chart (se já há shadcn/SVG) |
## Self-check (30s, só se Dados ≠ N/A)
Antes de gravar o plano ou declarar a fase de UI pronta — 1 ponto cada; **<3 → corrigir**:
1. As três perguntas estão respondidas por escrito?
2. Há pelo menos uma **decisão nomeável** (ator + escolha)?
3. A forma escolhida é o degrau mais pobre que resolve — com alternativas rejeitadas?
4. Anti-goals do research/`PRODUCT.md` §5 não foram violados?
5. Depth: reusa `CampaignMetricStrip` / lista / `BahiaMap` / tabela existente quando bastam?
## Onde registrar
- **`plan-issue`:** seção **Dados → decisão → apresentação** no `docs/plans/<slug>.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`).