name: code-review description: Comprehensive code review skill for Breath of Now. Use this skill when reviewing PRs, checking code quality, or validating implementations. Focuses on TypeScript best practices, performance, and project conventions.

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

Tipo	Convenção	Exemplo
Ficheiros	kebab-case	`expense-chart.tsx`
Componentes	PascalCase	`ExpenseChart`
Funções	camelCase	`handleClick`
Constantes	SCREAMING_SNAKE	`MAX_FILE_SIZE`
Types/Interfaces	PascalCase	`UserPreferences`
DB Columns (Supabase)	snake_case	`apps_selected_at`
TS Properties	camelCase	`appsSelectedAt`

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

Tipo de Issue	Severidade	Acção
Vulnerabilidade de segurança	🔴 Crítico	Bloquear merge
Texto hardcoded	🔴 Crítico	Bloquear merge
Uso de tipo `any`	🟡 Alto	Requerer mudança
Missing error handling	🟡 Alto	Requerer mudança
Issue de performance	🟡 Médio	Sugerir fix
Estilo de código	🟢 Baixo	Fix opcional

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.

code-review

$ Instalar