8.7 KiB
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.
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:
- As três perguntas estão respondidas por escrito?
- Há pelo menos uma decisão nomeável (ator + escolha)?
- A forma escolhida é o degrau mais pobre que resolve — com alternativas rejeitadas?
- Anti-goals do research/
PRODUCT.md§5 não foram violados? - Depth: reusa
CampaignMetricStrip/ lista /BahiaMap/ tabela existente quando bastam?
Onde registrar
plan-issue: seção Dados → decisão → apresentação nodocs/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).