AICA PRD Quality Rubric

# AICA PRD Quality Rubric

> **Audience**: Claude Code, LLMs, e Lucas.
> **Purpose**: Criterios de qualidade para avaliar e criar PRDs. Nota maxima = 5 em todas as 10 dimensoes.
> **Updated**: Marco 2026

---

## Objetivo

Todo modulo/sistema do AICA deve ter um PRD dedicado que permita a qualquer agente AI implementar features sem perguntas ao Lucas. O PRD e a **unica fonte de verdade** — se nao esta no PRD, o agente deve perguntar antes de implementar.

---

## As 10 Dimensoes (0-5 cada, total maximo = 50)

### D1. Visao e Contexto (0-5)

| Nota | Criterio |
|------|----------|
| 0 | Nenhuma descricao do modulo |
| 1 | Nome e frase generica |
| 2 | Proposta de valor + target users |
| 3 | + Proposta de valor diferenciada (o que vs. concorrentes) |
| 4 | + Personas detalhadas com jobs-to-be-done |
| 5 | + Metricas de sucesso, KPIs, e como medir valor entregue |

**Referencia nota 5**: PRD_FLUX.md secoes 1-2 (personas Coach/Atleta com responsabilidades, telas principais, anti-patterns)

### D2. Rotas e Navegacao (0-5)

| Nota | Criterio |
|------|----------|
| 0 | Nenhuma rota documentada |
| 1 | Rota principal mencionada |
| 2 | Tabela de rotas com paths |
| 3 | + Componente de cada rota (View) + persona que acessa |
| 4 | + Fluxo de navegacao entre rotas (de onde vem, para onde vai) |
| 5 | + Deep links, query params, estados de URL, guards de acesso |

**Referencia nota 5**: PRD_FLUX.md secao 1 (tabela de rotas com View + Persona)

### D3. Data Model (0-5)

| Nota | Criterio |
|------|----------|
| 0 | Nenhuma tabela mencionada |
| 1 | Nomes de tabelas listados |
| 2 | + Colunas principais de cada tabela |
| 3 | + Relacionamentos entre tabelas (FKs), tipos TypeScript |
| 4 | + RLS policies, indices relevantes, constraints |
| 5 | + RPCs/functions, triggers, migration strategy, exemplos de queries |

**Referencia nota 5**: World Graph PRD secoes 2.1-2.3 (schema completo com constraints, triggers, indices, RLS)

### D4. UI Components e Design (0-5)

| Nota | Criterio |
|------|----------|
| 0 | Nenhuma especificacao de UI |
| 1 | Descricao textual generica ("tela com lista") |
| 2 | Lista de componentes por tela |
| 3 | + Ceramic tokens usados, layout description, responsiveness |
| 4 | + Estados de UI (loading, empty, error, success), interacoes (drag, click, hover) |
| 5 | + Mockups ASCII ou wireframes, animations, acessibilidade (ARIA), keyboard navigation |

**Referencia nota 5**: PRD_FLUX.md Canvas Editor (drag-drop, calendar month view, template library sidebar)

### D5. Edge Functions e AI (0-5)

| Nota | Criterio |
|------|----------|
| 0 | Nenhuma Edge Function documentada |
| 1 | Nomes de Edge Functions listados |
| 2 | + Request/response format por function |
| 3 | + Modelo AI usado, temperature, maxTokens, prompt strategy |
| 4 | + Error handling, retry logic, fallback strategy, cost estimate |
| 5 | + Exemplos de prompts em portugues, few-shot patterns, extractJSON usage |

**Referencia nota 5**: PRD.md secao 4.3 (AI Infrastructure) + OPENCLAW_ADAPTATION.md

### D6. Business Logic e Regras (0-5)

| Nota | Criterio |
|------|----------|
| 0 | Nenhuma regra de negocio documentada |
| 1 | Regras implicitas no texto |
| 2 | Lista de regras explicitas |
| 3 | + Formulas, thresholds, algoritmos de scoring |
| 4 | + Edge cases, boundary conditions, o que acontece quando X |
| 5 | + Exemplos numericos concretos, cenarios de teste, invariantes |

**Referencia nota 5**: PRD_FLUX.md (7-level progression, scoring formulas, intensity calculator logic)

### D7. Integracao com Outros Modulos (0-5)

| Nota | Criterio |
|------|----------|
| 0 | Modulo tratado como isolado |
| 1 | Mencao generica de integracoes |
| 2 | Lista de modulos que interagem |
| 3 | + Qual dado flui entre modulos, em qual direcao |
| 4 | + Event bus events, cross-module hooks, shared services |
| 5 | + Diagrama de dependencias, contrato de API entre modulos, anti-corruption layer |

**Referencia nota 5**: PRD.md secao 4.2 (Scoring Engine com domain scores → Life Score)

### D8. Seguranca e Privacidade (0-5)

| Nota | Criterio |
|------|----------|
| 0 | Nenhuma consideracao de seguranca |
| 1 | Mencao generica de RLS |
| 2 | + RLS policies documentadas por tabela |
| 3 | + Auth flow, CORS, API key handling |
| 4 | + LGPD compliance, data retention, what data is stored/not stored |
| 5 | + Threat model (quais ataques sao possiveis), PII handling, audit trail |

**Referencia nota 5**: PRD.md secao 4.4 (LGPD commands, privacy purge, consent tracking, encryption)

### D9. Acceptance Criteria (0-5)

| Nota | Criterio |
|------|----------|
| 0 | Nenhum criterio de aceite |
| 1 | "Funciona" |
| 2 | Lista de features que devem funcionar |
| 3 | + Given/When/Then para fluxos principais |
| 4 | + Edge cases cobertos, negative testing (o que NAO deve acontecer) |
| 5 | + Performance targets (latencia, tamanho, Lighthouse), test plan com cenarios especificos |

**Referencia nota 5**: Issues do World Graph (#1004-#1010 com acceptance criteria detalhados)

### D10. Glossario e Terminologia (0-5)

| Nota | Criterio |
|------|----------|
| 0 | Nenhum glossario |
| 1 | Termos usados sem definicao |
| 2 | Termos-chave definidos inline |
| 3 | + Glossario dedicado com termos do dominio |
| 4 | + Mapeamento termo PT → termo tecnico → tabela/coluna |
| 5 | + Anti-patterns de nomenclatura (o que NAO usar), sinonimos aceitos, termos proibidos |

**Referencia nota 5**: PRD_FLUX.md secao 2 (glossario CRITICO que previne erros de nomenclatura)

---

## Escala de Avaliacao Global

| Score Total | Classificacao | Status |
|-------------|--------------|--------|
| 0-15 | Insuficiente | Risco alto — agentes farao perguntas constantemente |
| 16-25 | Basico | Cobre o minimo mas falta profundidade |
| 26-35 | Bom | Maioria das dimensoes coberta, gaps menores |
| 36-45 | Excelente | Agentes podem implementar com confianca |
| 46-50 | Referencia | Documentacao de classe mundial — zero ambiguidade |

**Meta**: Todos os PRDs devem atingir **36+** (Excelente). PRDs de modulos core devem atingir **46+** (Referencia).

---

## Template para PRD

Todo novo PRD deve seguir esta estrutura:

```markdown
# {Module Name} — PRD

> **Audience**: Claude Code, LLMs, e desenvolvedores
> **Updated**: {date} | **Status**: Source of Truth
> **Module**: `src/modules/{name}/` ({N} files)

## 1. Visao e Contexto
- Proposta de valor
- Personas e jobs-to-be-done
- KPIs e metricas de sucesso

## 2. Glossario
- Termos do dominio → definicao → tabela/coluna
- Anti-patterns de nomenclatura

## 3. Rotas e Navegacao
- Tabela: rota, view component, persona, guards

## 4. Data Model
- Schema SQL ou tabela de colunas
- Relacionamentos, FKs, indices
- RLS policies
- RPCs e triggers

## 5. UI Components
- Por rota/view: componentes, layout, estados
- Ceramic tokens, responsiveness
- Interacoes (drag, click, keyboard)

## 6. Edge Functions e AI
- Request/response por function
- Modelo, temperature, prompt strategy
- Exemplos de prompts em PT-BR

## 7. Business Logic
- Regras, formulas, algoritmos
- Edge cases e boundary conditions
- Exemplos numericos

## 8. Integracoes
- Modulos que interagem
- Fluxo de dados, events, hooks
- Anti-corruption layer

## 9. Seguranca e Privacidade
- RLS, auth, CORS
- LGPD, data retention
- PII handling

## 10. Acceptance Criteria
- Given/When/Then por feature
- Performance targets
- Test plan

## 11. Referencias
- Arquivos-chave (paths)
- Docs relacionados
- Issues/PRs relevantes
```

---

## Como Usar Esta Rubrica

1. **Ao criar um novo PRD**: Seguir o template e visar 5 em todas dimensoes
2. **Ao auditar um PRD existente**: Pontuar cada dimensao, listar gaps especificos
3. **Ao pedir implementacao a um agente**: Referenciar o PRD. Se o PRD nao cobre o pedido, complementar ANTES de implementar
4. **Ao revisar codigo**: Verificar se a implementacao esta de acordo com o PRD

---

**Maintainer**: Lucas Boscacci Lima + Claude | **Version**: 1.0