mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-18 14:13:06 +00:00
112 lines
8.7 KiB
Markdown
112 lines
8.7 KiB
Markdown
# 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`).
|