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:

# {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