---
id: consolidate-patterns
agent: ux-design-expert
title: Reduzir redundância por clustering inteligente
inputs: [audit-report, inventário de padrões de UI]
outputs: [padrões consolidados, mapa antigo→novo, métricas de redução]
elicit: false
modes: [interactive, yolo]
---

# Reduzir redundância por clustering inteligente

**Objetivo:** transformar o inventário caótico da auditoria num conjunto enxuto de padrões
canônicos, agrupando variantes similares por clustering e provando a redução com número.

**Pré-condições:**
- Existe um audit-report da task `audit-codebase` com inventário e métricas. Sem ele, **pare** —
  consolidar sem medir antes é consolidar no escuro.
- O inventário traz a localização (arquivo:linha) de cada padrão, para o mapa antigo→novo rastrear ao
  código real.

## Passos

1. **Carregue o inventário** do audit-report: todos os padrões com suas propriedades visuais (cor,
   espaçamento, tipografia, raio, etc.).
2. **Agrupe por similaridade (clustering).** Padrões com propriedades próximas caem no mesmo cluster
   — ex.: 12 tons de azul que servem à mesma intenção viram um candidato a token único.
3. **Eleja o padrão canônico de cada cluster:** o representante que melhor atende a necessidade,
   respeitando contraste WCAG AA. O canônico nunca pode reprovar em acessibilidade.
4. **Monte o mapa antigo→novo:** cada variante original aponta para o padrão canônico que a
   substitui, com a localização (arquivo:linha) de origem. É o rastro da migração.
5. **Calcule a redução:** nº de variantes antes → nº de canônicos depois, e o percentual (ex.: 47 → 3,
   93,6%). Número antes de opinião.
6. **Sinalize divergências que precisam de decisão humana** (dois canônicos legítimos, conflito de
   marca) em vez de fundir à força — registro a escolha pendente.
7. **Registre os padrões consolidados** e o mapa em `docs/stories/{epic}/audit/consolidation.md`, e
   roteie: alimenta `extract-tokens` (tokens dos canônicos) e `generate-shock-report` (visual + ROI).

## Critério de pronto (DoD)

- [ ] Todos os padrões do inventário agrupados em clusters
- [ ] Um padrão canônico por cluster, cada um aprovado em contraste WCAG AA
- [ ] Mapa antigo→novo com localização (arquivo:linha) de cada variante
- [ ] Métrica de redução calculada (antes → depois → %)
- [ ] Divergências que exigem decisão humana sinalizadas, não fundidas à força
- [ ] Consolidação registrada e roteada a `extract-tokens` / `generate-shock-report`

## Falha / recuperação

- **Não há audit-report** → volto para `audit-codebase`; não consolido sem o inventário medido.
- **Um cluster não tem canônico que passe em a11y** → não rebaixo o critério; escalo a necessidade de
  um novo padrão acessível em vez de eleger um que reprova em contraste.
- **Conflito de marca/identidade entre canônicos** → registro como decisão pendente e busco validação
  antes de fundir — não invento a regra de marca.