aiox-opencode 5.0.1

package/docs/guides/agents/DATA-ENGINEER-SYSTEM.md

@@ -0,0 +1,801 @@
+# Sistema do Agente @data-engineer
+
+> **Versao:** 1.0.0
+> **Criado:** 2026-02-04
+> **Owner:** @data-engineer (Dara - The Sage)
+> **Status:** Documentacao Oficial
+
+---
+
+## Visao Geral
+
+O agente **@data-engineer (Dara)** e o Database Architect & Operations Engineer do AIOX, responsavel pelo design de schemas, migracoes, seguranca (RLS), otimizacao de performance e operacoes de DBA. Este agente atua como um **Sage** que modela dominios de negocio, implementa migracoes seguras com snapshots e rollback, e garante integridade e seguranca dos dados.
+
+### Caracteristicas Principais
+
+| Caracteristica | Descricao |
+|----------------|-----------|
+| **Persona** | Dara - The Sage |
+| **Arquetipo** | Sage / Gemini |
+| **Tom** | Tecnico, preciso, metodico, consciente de seguranca |
+| **Foco** | Design de schema, migracoes, RLS, performance, operacoes DBA |
+| **Fechamento** | "-- Dara, arquitetando dados" |
+
+### Principios Criticos de Database
+
+- **Corretude antes de velocidade** - Acertar primeiro, otimizar depois
+- **Tudo versionado e reversivel** - Snapshots + scripts de rollback
+- **Seguranca por padrao** - RLS, constraints, triggers para consistencia
+- **Idempotencia em todo lugar** - Seguro executar operacoes multiplas vezes
+- **Design orientado a dominio** - Entender negocio antes de modelar dados
+- **Access pattern first** - Design baseado em como dados serao consultados
+- **Defesa em profundidade** - RLS + defaults + check constraints + triggers
+- **Observabilidade integrada** - Logs, metricas, explain plans
+- **Zero-downtime como objetivo** - Planejar migracoes cuidadosamente
+
+### Vocabulario Caracteristico
+
+- Consultar
+- Modelar
+- Armazenar
+- Configurar
+- Normalizar
+- Indexar
+- Migrar
+
+---
+
+## Lista Completa de Arquivos
+
+### Arquivos Core de Tasks do @data-engineer
+
+| Arquivo | Comando | Proposito |
+|---------|---------|-----------|
+| `.aiox-core/development/tasks/db-domain-modeling.md` | `*model-domain` | Sessao interativa de modelagem de dominio |
+| `.aiox-core/development/tasks/setup-database.md` | `*setup-database [type]` | Setup de projeto de database (Supabase, PostgreSQL, MongoDB, MySQL, SQLite) |
+| `.aiox-core/development/tasks/db-bootstrap.md` | `*bootstrap` | Cria estrutura padrao de projeto Supabase |
+| `.aiox-core/development/tasks/db-env-check.md` | `*env-check` | Valida variaveis de ambiente do database |
+| `.aiox-core/development/tasks/db-apply-migration.md` | `*apply-migration {path}` | Aplica migracao com snapshot e lock advisory |
+| `.aiox-core/development/tasks/db-dry-run.md` | `*dry-run {path}` | Testa migracao sem commit |
+| `.aiox-core/development/tasks/db-seed.md` | `*seed {path}` | Aplica seed data (idempotent) |
+| `.aiox-core/development/tasks/db-snapshot.md` | `*snapshot {label}` | Cria snapshot do schema |
+| `.aiox-core/development/tasks/db-rollback.md` | `*rollback {snapshot_or_file}` | Restaura snapshot ou executa rollback |
+| `.aiox-core/development/tasks/db-smoke-test.md` | `*smoke-test {version}` | Testes abrangentes de database |
+| `.aiox-core/development/tasks/security-audit.md` | `*security-audit {scope}` | Auditoria de seguranca (rls, schema, full) |
+| `.aiox-core/development/tasks/analyze-performance.md` | `*analyze-performance {type}` | Analise de performance (query, hotpaths, interactive) |
+| `.aiox-core/development/tasks/db-policy-apply.md` | `*policy-apply {table} {mode}` | Instala politica RLS (KISS ou granular) |
+| `.aiox-core/development/tasks/test-as-user.md` | `*test-as-user {user_id}` | Emula usuario para testar RLS |
+| `.aiox-core/development/tasks/db-verify-order.md` | `*verify-order {path}` | Valida ordenacao DDL para dependencias |
+| `.aiox-core/development/tasks/db-load-csv.md` | `*load-csv {table} {file}` | Carregador seguro de CSV (staging->merge) |
+| `.aiox-core/development/tasks/db-run-sql.md` | `*run-sql {file_or_inline}` | Executa SQL raw com transacao |
+| `.aiox-core/development/tasks/create-deep-research-prompt.md` | `*research {topic}` | Gera prompt de pesquisa profunda |
+| `.aiox-core/development/tasks/execute-checklist.md` | `*execute-checklist {checklist}` | Executa checklist DBA |
+| `.aiox-core/development/tasks/create-doc.md` | `*doc-out` | Output de documento completo |
+
+### Tasks Depreciadas (Backward Compatibility v2.0->v3.0)
+
+| Task Antiga | Nova Task | Migracao |
+|-------------|-----------|----------|
+| `db-rls-audit.md` | `security-audit.md` | `*security-audit rls` |
+| `schema-audit.md` | `security-audit.md` | `*security-audit schema` |
+| `db-explain.md` | `analyze-performance.md` | `*analyze-performance query` |
+| `db-analyze-hotpaths.md` | `analyze-performance.md` | `*analyze-performance hotpaths` |
+| `query-optimization.md` | `analyze-performance.md` | `*analyze-performance interactive` |
+| `db-impersonate.md` | `test-as-user.md` | `*test-as-user {user_id}` |
+| `db-supabase-setup.md` | `setup-database.md` | `*setup-database supabase` |
+
+### Arquivos de Definicao do Agente
+
+| Arquivo | Proposito |
+|---------|-----------|
+| `.aiox-core/development/agents/data-engineer.md` | Definicao core do agente @data-engineer (persona, comandos, workflows) |
+| `.claude/commands/AIOX/agents/data-engineer.md` | Comando Claude Code para ativar @data-engineer |
+
+### Arquivos de Templates SQL
+
+| Arquivo | Proposito |
+|---------|-----------|
+| `schema-design-tmpl.yaml` | Template de documentacao de schema |
+| `rls-policies-tmpl.yaml` | Template de politicas RLS |
+| `migration-plan-tmpl.yaml` | Template de plano de migracao |
+| `index-strategy-tmpl.yaml` | Template de estrategia de indices |
+| `tmpl-migration-script.sql` | Template de script de migracao |
+| `tmpl-rollback-script.sql` | Template de script de rollback |
+| `tmpl-smoke-test.sql` | Template de smoke test |
+| `tmpl-rls-kiss-policy.sql` | Template de politica RLS KISS |
+| `tmpl-rls-granular-policies.sql` | Template de politicas RLS granulares |
+| `tmpl-staging-copy-merge.sql` | Template de staging para CSV |
+| `tmpl-seed-data.sql` | Template de seed data |
+| `tmpl-comment-on-examples.sql` | Exemplos de COMMENT ON |
+
+### Arquivos de Checklists
+
+| Arquivo | Proposito |
+|---------|-----------|
+| `dba-predeploy-checklist.md` | Checklist pre-deploy DBA |
+| `dba-rollback-checklist.md` | Checklist de rollback |
+| `database-design-checklist.md` | Checklist de design de database |
+
+### Arquivos de Data/Conhecimento
+
+| Arquivo | Proposito |
+|---------|-----------|
+| `database-best-practices.md` | Melhores praticas de database |
+| `supabase-patterns.md` | Padroes Supabase |
+| `postgres-tuning-guide.md` | Guia de tuning PostgreSQL |
+| `rls-security-patterns.md` | Padroes de seguranca RLS |
+| `migration-safety-guide.md` | Guia de seguranca de migracao |
+
+### Workflows que Usam @data-engineer
+
+| Arquivo | Proposito |
+|---------|-----------|
+| `.aiox-core/development/workflows/brownfield-discovery.yaml` | Workflow de discovery brownfield (Fase 2 e 5) |
+
+---
+
+## Flowchart: Sistema Completo do @data-engineer
+
+```mermaid
+flowchart TB
+    subgraph ACTIVATION["ATIVACAO DO AGENTE"]
+        A["@data-engineer"] --> B["generate-greeting.js"]
+        B --> C["Exibe Greeting Sage"]
+        C --> D["Quick Commands"]
+        D --> E["HALT - Aguarda Usuario"]
+    end
+
+    subgraph COMMANDS["CATEGORIAS DE COMANDOS"]
+        E --> F{"Comando Recebido"}
+
+        F -->|"Arquitetura"| G["Design Commands"]
+        F -->|"Operacoes"| H["DBA Commands"]
+        F -->|"Seguranca"| I["Security Commands"]
+        F -->|"Performance"| J["Performance Commands"]
+        F -->|"Dados"| K["Data Commands"]
+    end
+
+    subgraph DESIGN["DESIGN & ARQUITETURA"]
+        G --> G1["*create-schema"]
+        G --> G2["*create-rls-policies"]
+        G --> G3["*model-domain"]
+        G --> G4["*design-indexes"]
+        G --> G5["*create-migration-plan"]
+    end
+
+    subgraph DBA["OPERACOES DBA"]
+        H --> H1["*setup-database"]
+        H --> H2["*bootstrap"]
+        H --> H3["*apply-migration"]
+        H --> H4["*dry-run"]
+        H --> H5["*snapshot"]
+        H --> H6["*rollback"]
+        H --> H7["*smoke-test"]
+        H --> H8["*seed"]
+    end
+
+    subgraph SECURITY["SEGURANCA"]
+        I --> I1["*security-audit"]
+        I --> I2["*policy-apply"]
+        I --> I3["*test-as-user"]
+        I --> I4["*verify-order"]
+    end
+
+    subgraph PERF["PERFORMANCE"]
+        J --> J1["*analyze-performance query"]
+        J --> J2["*analyze-performance hotpaths"]
+        J --> J3["*analyze-performance interactive"]
+    end
+
+    subgraph DATA["OPERACOES DE DADOS"]
+        K --> K1["*load-csv"]
+        K --> K2["*run-sql"]
+    end
+
+    style ACTIVATION fill:#e3f2fd
+    style COMMANDS fill:#e8f5e9
+    style DESIGN fill:#fff8e1
+    style DBA fill:#f3e5f5
+    style SECURITY fill:#ffebee
+    style PERF fill:#e1f5fe
+    style DATA fill:#f1f8e9
+```
+
+### Diagrama do Ciclo de Migracao
+
+```mermaid
+stateDiagram-v2
+    [*] --> Design: Novo Requisito
+
+    state Design {
+        D1: Entender Dominio
+        D2: Modelar Entidades
+        D3: Definir Relacionamentos
+        D4: Criar Schema SQL
+
+        D1 --> D2
+        D2 --> D3
+        D3 --> D4
+    }
+
+    Design --> PreMigration: Schema Pronto
+
+    state PreMigration {
+        P1: *snapshot pre_migration
+        P2: *verify-order migration.sql
+        P3: *dry-run migration.sql
+        P4: Validar Output
+
+        P1 --> P2
+        P2 --> P3
+        P3 --> P4
+    }
+
+    PreMigration --> Migration: Dry-run OK
+
+    state Migration {
+        M1: *apply-migration
+        M2: Advisory Lock
+        M3: Execute SQL
+        M4: Release Lock
+        M5: *snapshot post_migration
+
+        M1 --> M2
+        M2 --> M3
+        M3 --> M4
+        M4 --> M5
+    }
+
+    Migration --> PostMigration: Aplicado
+
+    state PostMigration {
+        PM1: *smoke-test
+        PM2: *security-audit
+        PM3: *analyze-performance
+        PM4: Validar RLS
+
+        PM1 --> PM2
+        PM2 --> PM3
+        PM3 --> PM4
+    }
+
+    PostMigration --> [*]: Completo
+
+    Migration --> Rollback: Falha
+    PostMigration --> Rollback: Issues Criticos
+
+    state Rollback {
+        R1: *rollback snapshot
+        R2: Verificar Estado
+        R3: Investigar Causa
+    }
+
+    Rollback --> Design: Fix e Retry
+```
+
+### Fluxo de Security Audit
+
+```mermaid
+flowchart TB
+    subgraph AUDIT["SECURITY AUDIT (*security-audit)"]
+        A["Selecionar Escopo"] --> B{"Tipo?"}
+
+        B -->|"rls"| C["RLS Audit Only"]
+        B -->|"schema"| D["Schema Audit Only"]
+        B -->|"full"| E["RLS + Schema + Best Practices"]
+
+        subgraph RLS_AUDIT["RLS AUDIT"]
+            C --> C1["Listar Tabelas"]
+            C1 --> C2["Verificar RLS Enabled"]
+            C2 --> C3["Listar Policies"]
+            C3 --> C4["Coverage por Comando"]
+            C4 --> C5["Tabelas Sem RLS"]
+        end
+
+        subgraph SCHEMA_AUDIT["SCHEMA AUDIT"]
+            D --> D1["Primary Keys"]
+            D1 --> D2["NOT NULL Constraints"]
+            D2 --> D3["Foreign Keys"]
+            D3 --> D4["Audit Timestamps"]
+            D4 --> D5["Indices em FKs"]
+        end
+
+        subgraph FULL_AUDIT["FULL AUDIT"]
+            E --> E1["RLS Audit"]
+            E1 --> E2["Schema Audit"]
+            E2 --> E3["PII/Sensitive Check"]
+            E3 --> E4["Permissions Check"]
+        end
+
+        C5 --> F["Gerar Relatorio"]
+        D5 --> F
+        E4 --> F
+
+        F --> G{"Issues Criticos?"}
+        G -->|"Sim"| H["Recomendar Fixes"]
+        G -->|"Nao"| I["Schema Seguro"]
+
+        H --> J["*policy-apply para RLS"]
+        H --> K["ALTER TABLE para Constraints"]
+    end
+
+    style C fill:#e1f5fe
+    style D fill:#fff8e1
+    style E fill:#ffebee
+    style I fill:#c8e6c9
+    style H fill:#ffcdd2
+```
+
+### Fluxo de Snapshot e Rollback
+
+```mermaid
+flowchart TB
+    subgraph SNAPSHOT["SISTEMA DE SNAPSHOTS"]
+        direction TB
+
+        A["*snapshot {label}"] --> B["Criar Diretorio<br/>supabase/snapshots/"]
+        B --> C["pg_dump --schema-only"]
+        C --> D["Gerar Metadata"]
+        D --> E["Verificar Conteudo"]
+        E --> F["Snapshot Criado"]
+
+        F --> G["supabase/snapshots/<br/>{TS}_{label}.sql"]
+        F --> H["supabase/snapshots/<br/>{TS}_{label}.meta"]
+    end
+
+    subgraph MIGRATION["MIGRACAO COM AUTO-SNAPSHOT"]
+        I["*apply-migration"] --> J["Pre-Snapshot Automatico"]
+        J --> K["Advisory Lock"]
+        K --> L["Execute Migration"]
+        L --> M{"Sucesso?"}
+
+        M -->|"Sim"| N["Post-Snapshot"]
+        M -->|"Nao"| O["Transaction Rollback"]
+
+        N --> P["Gerar Diff"]
+        P --> Q["Release Lock"]
+    end
+
+    subgraph ROLLBACK["SISTEMA DE ROLLBACK"]
+        R["*rollback {target}"] --> S["Confirmar ROLLBACK"]
+        S --> T["Emergency Snapshot"]
+        T --> U["Validar Target"]
+        U --> V["Advisory Lock"]
+        V --> W["Execute Restore"]
+
+        W --> X{"Sucesso?"}
+        X -->|"Sim"| Y["Post-Rollback Validation"]
+        X -->|"Nao"| Z["Restore Emergency"]
+
+        Y --> AA["Release Lock"]
+        Z --> AA
+    end
+
+    F -.-> R
+    J -.-> G
+    T -.-> G
+
+    style F fill:#c8e6c9
+    style O fill:#ffcdd2
+    style Z fill:#ffcdd2
+    style Y fill:#c8e6c9
+```
+
+---
+
+## Mapeamento de Comandos para Tasks
+
+### Comandos de Arquitetura e Design
+
+| Comando | Task File | Operacao |
+|---------|-----------|----------|
+| `*create-schema` | (inline) | Design de schema de database |
+| `*create-rls-policies` | (inline) | Design de politicas RLS |
+| `*create-migration-plan` | (inline) | Cria estrategia de migracao |
+| `*design-indexes` | (inline) | Design de estrategia de indices |
+| `*model-domain` | `db-domain-modeling.md` | Sessao interativa de modelagem |
+
+### Comandos de Operacoes DBA
+
+| Comando | Task File | Operacao |
+|---------|-----------|----------|
+| `*setup-database [type]` | `setup-database.md` | Setup de projeto (supabase/postgresql/mongodb/mysql/sqlite) |
+| `*bootstrap` | `db-bootstrap.md` | Scaffold de estrutura Supabase |
+| `*env-check` | `db-env-check.md` | Valida variaveis de ambiente |
+| `*apply-migration {path}` | `db-apply-migration.md` | Aplica migracao com snapshot de seguranca |
+| `*dry-run {path}` | `db-dry-run.md` | Testa migracao sem commit |
+| `*seed {path}` | `db-seed.md` | Aplica seed data idempotente |
+| `*snapshot {label}` | `db-snapshot.md` | Cria snapshot de schema |
+| `*rollback {target}` | `db-rollback.md` | Restaura snapshot ou executa rollback |
+| `*smoke-test {version}` | `db-smoke-test.md` | Testes de validacao |
+
+### Comandos de Seguranca e Performance (Consolidados - Story 6.1.2.3)
+
+| Comando | Task File | Operacao |
+|---------|-----------|----------|
+| `*security-audit rls` | `security-audit.md` | Auditoria de cobertura RLS |
+| `*security-audit schema` | `security-audit.md` | Auditoria de qualidade de schema |
+| `*security-audit full` | `security-audit.md` | Auditoria completa |
+| `*analyze-performance query` | `analyze-performance.md` | EXPLAIN ANALYZE de query |
+| `*analyze-performance hotpaths` | `analyze-performance.md` | Detecta bottlenecks do sistema |
+| `*analyze-performance interactive` | `analyze-performance.md` | Sessao de otimizacao interativa |
+| `*policy-apply {table} {mode}` | `db-policy-apply.md` | Instala politica RLS (KISS ou granular) |
+| `*test-as-user {user_id}` | `test-as-user.md` | Emula usuario para testar RLS |
+| `*verify-order {path}` | `db-verify-order.md` | Valida ordenacao DDL |
+
+### Comandos de Operacoes de Dados
+
+| Comando | Task File | Operacao |
+|---------|-----------|----------|
+| `*load-csv {table} {file}` | `db-load-csv.md` | Carregador seguro de CSV |
+| `*run-sql {file_or_inline}` | `db-run-sql.md` | Executa SQL com transacao |
+
+### Comandos de Contexto e Sessao
+
+| Comando | Operacao |
+|---------|----------|
+| `*help` | Mostra todos os comandos disponiveis |
+| `*guide` | Mostra guia de uso completo |
+| `*yolo` | Toggle de confirmacao (skip/require) |
+| `*exit` | Sai do modo data-engineer |
+| `*doc-out` | Output de documento completo |
+| `*execute-checklist {checklist}` | Executa checklist DBA |
+| `*research {topic}` | Gera prompt de pesquisa profunda |
+
+---
+
+## Integracoes entre Agentes
+
+### Diagrama de Colaboracao
+
+```mermaid
+flowchart TB
+    subgraph DATA_ECOSYSTEM["ECOSSISTEMA DO @data-engineer"]
+        DATA["@data-engineer (Dara)"]
+    end
+
+    subgraph UPSTREAM["UPSTREAM - Fornece Requisitos"]
+        ARCH["@architect (Aria)<br/>System Architecture"]
+    end
+
+    subgraph DOWNSTREAM["DOWNSTREAM - Recebe Schema"]
+        DEV["@dev (Dex)<br/>Developer"]
+    end
+
+    subgraph COLLABORATION["COLABORACAO EM DISCOVERY"]
+        QA["@qa (Quinn)<br/>Quality Gate"]
+    end
+
+    ARCH -->|"Requisitos de Arquitetura<br/>Gate 2 Decision"| DATA
+    DATA -->|"Schema Design<br/>Migrations<br/>RLS Policies"| DEV
+
+    DATA -->|"DB Audit<br/>Fase 2 brownfield-discovery"| QA
+    QA -->|"Validacao<br/>Fase 7"| DATA
+
+    style DATA fill:#e8f5e9
+    style ARCH fill:#e3f2fd
+    style DEV fill:#fff3e0
+    style QA fill:#fce4ec
+```
+
+### Fluxo de Colaboracao
+
+| De | Para | Trigger | Acao |
+|----|------|---------|------|
+| @architect | @data-engineer | Gate 2 Decision | @data-engineer recebe requisitos de schema |
+| @data-engineer | @dev | Schema pronto | @dev implementa data layer |
+| @data-engineer | @qa | brownfield-discovery Fase 2 | @data-engineer documenta schema e debitos |
+| @qa | @data-engineer | Fase 5 validation | @qa valida e @data-engineer ajusta |
+
+### Delegacao do @architect (Gate 2 Decision)
+
+O @architect delega para @data-engineer:
+- Database schema design
+- Query optimization
+- RLS policies design
+- Index strategy
+- Migration planning
+
+### Quando Usar Outro Agente
+
+| Tarefa | Agente | Motivo |
+|--------|--------|--------|
+| System architecture | @architect | Padroes de app-level, design de API |
+| Application code | @dev | Implementacao de repository pattern, DAL |
+| Frontend design | @ux-design-expert | Design de UI/UX |
+| Git operations | @github-devops | Push, PR, deploy |
+
+---
+
+## Workflow: Brownfield Discovery
+
+O @data-engineer participa do workflow `brownfield-discovery.yaml` em duas fases criticas:
+
+### Fase 2: Coleta de Database
+
+```yaml
+step: database_documentation
+phase: 2
+phase_name: "Coleta: Database"
+agent: data-engineer
+action: db-schema-audit
+creates:
+  - supabase/docs/SCHEMA.md
+  - supabase/docs/DB-AUDIT.md
+duration_estimate: "20-40 min"
+```
+
+**Analises realizadas:**
+- Schema completo (tabelas, colunas, tipos)
+- Relacionamentos e foreign keys
+- Indices existentes e faltantes
+- RLS policies (cobertura e qualidade)
+- Views e functions
+- Performance (queries lentas conhecidas)
+
+**Debitos identificados (nivel dados):**
+- Tabelas sem RLS
+- Indices faltantes
+- Normalizacao inadequada
+- Constraints ausentes
+- Migrations nao versionadas
+- Dados orfaos
+
+### Fase 5: Validacao Database
+
+```yaml
+step: database_specialist_review
+phase: 5
+phase_name: "Validacao: Database"
+agent: data-engineer
+action: review_and_validate
+creates: docs/reviews/db-specialist-review.md
+duration_estimate: "20-30 min"
+```
+
+**Responsabilidades:**
+1. Validar debitos identificados
+2. Estimar custos (horas)
+3. Priorizar (perspectiva DB)
+4. Responder perguntas do @architect
+
+---
+
+## Configuracao
+
+### Variaveis de Ambiente Necessarias
+
+```bash
+# Supabase Database Connection
+SUPABASE_DB_URL="postgresql://postgres.[PASSWORD]@[PROJECT-REF].supabase.co:6543/postgres?sslmode=require"
+
+# Para backups/analise (conexao direta)
+# SUPABASE_DB_URL="postgresql://postgres.[PASSWORD]@[PROJECT-REF].supabase.co:5432/postgres"
+```
+
+### Estrutura de Diretorio Padrao (Supabase)
+
+```
+supabase/
+├── migrations/      # Arquivos de migracao
+│   └── README.md
+├── seeds/           # Seed data
+│   └── README.md
+├── tests/           # Smoke tests
+│   └── README.md
+├── rollback/        # Scripts de rollback
+│   └── README.md
+├── snapshots/       # Schema snapshots
+├── docs/            # Documentacao
+│   ├── SCHEMA.md
+│   └── migration-log.md
+├── config.toml      # Configuracao local
+└── .gitignore
+```
+
+### CodeRabbit Integration
+
+```yaml
+coderabbit_integration:
+  enabled: true
+  focus: SQL quality, schema design, query performance, RLS security, migration safety
+
+  when_to_use:
+    - Before applying migrations (review DDL changes)
+    - After creating RLS policies (check policy logic)
+    - When adding database access code (review query patterns)
+    - During schema refactoring (validate changes)
+
+  severity_handling:
+    CRITICAL:
+      action: Block migration/deployment
+      focus: SQL injection risks, RLS bypass, data exposure
+    HIGH:
+      action: Fix before migration or create rollback plan
+      focus: Performance issues, missing constraints
+    MEDIUM:
+      action: Document as technical debt
+      focus: Schema design, normalization
+    LOW:
+      action: Note for future refactoring
+      focus: SQL style, readability
+```
+
+---
+
+## Best Practices
+
+### Quando Usar o @data-engineer
+
+**USE @data-engineer para:**
+- Design de schema de database
+- Modelagem de dominio
+- Migracoes e versionamento
+- Politicas RLS e seguranca
+- Otimizacao de queries e performance
+- Operacoes DBA (backup, restore, smoke-test)
+- Auditoria de seguranca e qualidade
+
+**NAO USE @data-engineer para:**
+- System architecture (use @architect)
+- Codigo de aplicacao (use @dev)
+- Git operations (use @github-devops)
+- Frontend/UI (use @ux-design-expert)
+
+### Workflow de Migracao Segura
+
+```bash
+# 1. Antes de qualquer migracao
+*snapshot pre_migration
+
+# 2. Testar migracao
+*dry-run path/to/migration.sql
+
+# 3. Aplicar migracao
+*apply-migration path/to/migration.sql
+
+# 4. Validar resultado
+*smoke-test
+*security-audit rls
+
+# 5. Se problemas
+*rollback supabase/snapshots/{TS}_pre_migration.sql
+```
+
+### Padrao de Tabela
+
+Toda tabela deve ter como baseline:
+- `id` (UUID PRIMARY KEY)
+- `created_at` (TIMESTAMPTZ)
+- `updated_at` (TIMESTAMPTZ)
+- Foreign keys para relacionamentos
+- RLS enabled por padrao
+- Indices em FKs e colunas de query frequente
+
+### Seguranca
+
+- Nunca expor secrets - redact passwords/tokens automaticamente
+- Preferir conexao Pooler (porta 6543) com SSL
+- Quando nao ha Auth layer, avisar que `auth.uid()` retorna NULL
+- RLS deve ser validado com casos positivos/negativos
+- Service role key bypassa RLS - usar com extremo cuidado
+- Sempre usar transacoes para operacoes multi-statement
+- Validar input do usuario antes de construir SQL dinamico
+
+---
+
+## Troubleshooting
+
+### Database connection failed
+
+```
+Erro: pg_dump: error: connection failed
+```
+
+**Solucao:**
+1. Verificar SUPABASE_DB_URL: `*env-check`
+2. Checar formato da connection string
+3. Verificar SSL mode
+4. Testar conexao manual: `psql "$SUPABASE_DB_URL"`
+
+### Migration failed mid-execution
+
+**Situacao:** `*apply-migration` falhou no meio
+
+**Acao:** PostgreSQL ja fez rollback da transacao automaticamente
+
+**Proximos passos:**
+1. Fix no arquivo de migracao
+2. `*dry-run` para testar
+3. `*apply-migration` novamente
+
+### Lock already held
+
+```
+Erro: Another migration is running
+```
+
+**Solucao:**
+1. Aguardar conclusao da outra migracao
+2. Verificar locks travados:
+   ```sql
+   SELECT * FROM pg_locks WHERE locktype = 'advisory';
+   ```
+3. Se necessario, cancelar lock manualmente
+
+### Snapshot file is empty
+
+**Problema:** Nenhum objeto de schema ou conexao falhou
+
+**Solucao:**
+1. Verificar se database tem tabelas: `SELECT * FROM pg_tables WHERE schemaname='public';`
+2. Checar compatibilidade de versao do pg_dump
+3. Verificar conectividade de rede
+
+### RLS policies not working
+
+**Sintomas:** Usuarios veem dados que nao deveriam
+
+**Solucao:**
+1. Verificar se RLS esta enabled: `*security-audit rls`
+2. Testar como usuario especifico: `*test-as-user {user_id}`
+3. Verificar se ha policy com USING clause correta
+4. Checar se auth.uid() esta retornando valor esperado
+
+---
+
+## Referencias
+
+### Tasks do @data-engineer
+
+- [db-domain-modeling.md](.aiox-core/development/tasks/db-domain-modeling.md)
+- [setup-database.md](.aiox-core/development/tasks/setup-database.md)
+- [db-apply-migration.md](.aiox-core/development/tasks/db-apply-migration.md)
+- [security-audit.md](.aiox-core/development/tasks/security-audit.md)
+- [analyze-performance.md](.aiox-core/development/tasks/analyze-performance.md)
+- [db-snapshot.md](.aiox-core/development/tasks/db-snapshot.md)
+- [db-rollback.md](.aiox-core/development/tasks/db-rollback.md)
+- [db-bootstrap.md](.aiox-core/development/tasks/db-bootstrap.md)
+
+### Agente
+
+- [data-engineer.md](.aiox-core/development/agents/data-engineer.md)
+
+### Workflows
+
+- [brownfield-discovery.yaml](.aiox-core/development/workflows/brownfield-discovery.yaml)
+
+### Relacionados
+
+- [BACKLOG-MANAGEMENT-SYSTEM.md](../BACKLOG-MANAGEMENT-SYSTEM.md)
+- [DEV-SYSTEM.md](DEV-SYSTEM.md)
+
+---
+
+## Resumo
+
+| Aspecto | Detalhes |
+|---------|----------|
+| **Total de Tasks Core** | 20 task files |
+| **Comandos Principais** | 25+ comandos (*setup-database, *apply-migration, *security-audit, etc.) |
+| **Databases Suportados** | 5 (Supabase, PostgreSQL, MongoDB, MySQL, SQLite) |
+| **Tipos de Audit** | 3 (rls, schema, full) |
+| **Tipos de Performance Analysis** | 3 (query, hotpaths, interactive) |
+| **Templates SQL** | 12 templates |
+| **Checklists DBA** | 3 checklists |
+| **Data Files** | 5 arquivos de conhecimento |
+| **Workflows Integrados** | 1 (brownfield-discovery) |
+| **Agentes Colaboradores** | 3 (@architect, @dev, @qa) |
+| **Fases no brownfield-discovery** | 2 (Fase 2: Coleta, Fase 5: Validacao) |
+
+---
+
+## Changelog
+
+| Data | Autor | Descricao |
+|------|-------|-----------|
+| 2026-02-04 | @data-engineer | Documento inicial criado |
+
+---
+
+*-- Dara, arquitetando dados*