Code Review Skill

Este skill providencia capacidades de revisão de código compreensivas para o projecto Breath of Now. Verifica issues comuns, enforça convenções do projecto, e garante código de alta qualidade.

Quando Usar

Aplica este skill quando:

• Rever pull requests
• Validar novas implementações
• Verificar bugs e issues
• Garantir qualidade antes de merge
• Fechar sessões de trabalho (CLOSE-PROMPT)

Categorias de Revisão

1. Compliance TypeScript

// ❌ EVITAR: any type
const data: any = response;
function handleClick(event: any) { }

// ✅ PREFERIR: Tipos explícitos
interface ApiResponse {
  data: Expense[];
  error: string | null;
}
const data: ApiResponse = response;

function handleClick(event: React.MouseEvent<HTMLButtonElement>) { }

// ❌ EVITAR: Returns implícitos sem tipos
const getUser = (id) => users.find(u => u.id === id);

// ✅ PREFERIR: Tipos e returns explícitos
const getUser = (id: string): User | undefined => {
  return users.find(u => u.id === id);
};

2. Compliance i18n

// ❌ REJEITAR: Texto hardcoded
<Button>Save Changes</Button>
<p className="error">Something went wrong</p>
<Input placeholder="Enter email" />

// ✅ ACEITAR: Texto traduzido
const t = useTranslations('Common');
<Button>{t('saveChanges')}</Button>
<p className="error">{t('errors.generic')}</p>
<Input placeholder={t('emailPlaceholder')} />

3. Arquitectura Local-First

// ❌ REJEITAR: Leituras directas do Supabase para dados do utilizador
const expenses = await supabase.from('expenses').select('*');

// ✅ ACEITAR: Leituras de Dexie
const expenses = await db.expenses.toArray();

4. Issues de Performance

// ❌ PROBLEMA: Async sequencial em loops
for (const item of items) {
  await processItem(item);  // Lento!
}

// ✅ MELHOR: Execução paralela
await Promise.all(items.map(item => processItem(item)));

// ❌ PROBLEMA: Missing useMemo/useCallback
const filteredExpenses = expenses.filter(e => e.category === category);
const handleClick = () => doSomething(id);

// ✅ MELHOR: Memoizado
const filteredExpenses = useMemo(
  () => expenses.filter(e => e.category === category),
  [expenses, category]
);
const handleClick = useCallback(() => doSomething(id), [id]);

5. Error Handling

// ❌ REJEITAR: Falhas silenciosas
try {
  await saveData();
} catch (e) {
  // Nada
}

// ✅ ACEITAR: Error handling adequado
try {
  await saveData();
} catch (error) {
  console.error('Failed to save:', error);
  toast.error(t('errors.saveFailed'));
}

6. Issues de Segurança

// ❌ REJEITAR: Secrets expostos
const API_KEY = "sk-ant-xxxxx";
const SUPABASE_KEY = "eyJhbGc...";

// ✅ ACEITAR: Variáveis de ambiente
const API_KEY = process.env.NEXT_PUBLIC_API_KEY;

7. Convenções de Nomenclatura

Checklist de Revisão

Must Pass (Blocking) 🔴

• Sem tipos any (usar unknown se realmente desconhecido)
• Sem texto hardcoded em UI (usar traduções)
• Sem leituras directas de Supabase para dados do utilizador (usar Dexie)
• Sem console.log em código de produção
• Sem secrets expostos ou API keys
• Error handling em todas as operações async
• Consultar .claude/supabase-schema.md antes de queries

Should Pass (Non-blocking) 🟡

• Interfaces TypeScript definidas adequadamente
• Componentes têm tamanho razoável (<300 linhas)
• Lógica complexa tem comentários
• Convenções de nomenclatura consistentes
• Estados de loading/error adequados em UI

Nice to Have 🟢

• Unit tests para business logic
• Comentários JSDoc em funções exportadas
• Atributos de acessibilidade (aria-labels)
• Optimização de performance (memoização)

Formato de Mensagem de Commit

tipo(scope): descrição curta (máx 50 chars)

Descrição mais detalhada do que foi feito e porquê.
Pode ter múltiplas linhas.

- Lista de mudanças principais
- Outra mudança
- Mais uma mudança

Files changed:
- path/to/file1.ts
- path/to/file2.tsx

Tipos de commit:

• feat: Nova funcionalidade
• fix: Correcção de bug
• docs: Mudanças em documentação
• style: Formatação, missing semi-colons, etc
• refactor: Refactoring de código
• test: Adicionar testes
• chore: Manutenção (deps, config, etc)

Scopes comuns:

• expenses: ExpenseFlow
• fitlog: FitLog
• auth: Autenticação
• i18n: Internacionalização
• db: Base de dados
• ui: Interface/Componentes
• sync: Sync engine

Template de Resposta de Revisão

## Code Review: [Nome da Feature/PR]

### ✅ Aprovado / ❌ Mudanças Necessárias / 🔄 Precisa Discussão

### Sumário
Breve visão geral do que o código faz.

### Issues Encontradas

#### 🔴 Crítico (Must Fix)
- Issue 1: Descrição e localização
- Issue 2: Descrição e localização

#### 🟡 Importante (Should Fix)
- Issue 1: Descrição e sugestão

#### 🟢 Menor (Nice to Fix)
- Issue 1: Sugestão de melhoria

### O Que Está Bom
- Feedback positivo sobre a implementação

### Sugestões
- Melhorias adicionais a considerar

Verificações Automatizadas

Correr estes comandos para apanhar issues comuns:

# Erros TypeScript
npx tsc --noEmit

# Issues de linting
npm run lint

# Encontrar strings hardcoded (potenciais issues de i18n)
grep -r ">[A-Z][a-z]" --include="*.tsx" src/

# Encontrar console.log statements
grep -rn "console.log" --include="*.ts" --include="*.tsx" src/

# Encontrar tipos 'any'
grep -rn ": any" --include="*.ts" --include="*.tsx" src/

# Verificar imports não utilizados
npx eslint --rule 'no-unused-vars: error' src/

Matriz de Prioridade

Integração com CLOSE-PROMPT

Este skill é automaticamente invocado quando usas o CLOSE-PROMPT para:

• Verificar qualidade do código antes de commit
• Gerar mensagem de commit adequada
• Identificar issues não resolvidas
• Sugerir próximos passos

Lembra-te: Code review é sobre melhorar qualidade, não criticar o autor. Sê construtivo e útil.