From 1ef8bc1e72a3461bc554fc7e4d01042307387881 Mon Sep 17 00:00:00 2001 From: Paulo Victor Gomes Date: Sat, 21 Mar 2026 14:06:49 +0100 Subject: [PATCH] docs(pt-BR): add commands translation --- docs/pt-BR/commands/build-fix.md | 62 +++++ docs/pt-BR/commands/checkpoint.md | 74 +++++ docs/pt-BR/commands/code-review.md | 40 +++ docs/pt-BR/commands/e2e.md | 365 +++++++++++++++++++++++++ docs/pt-BR/commands/eval.md | 120 ++++++++ docs/pt-BR/commands/go-build.md | 183 +++++++++++++ docs/pt-BR/commands/go-review.md | 148 ++++++++++ docs/pt-BR/commands/go-test.md | 268 ++++++++++++++++++ docs/pt-BR/commands/learn.md | 70 +++++ docs/pt-BR/commands/orchestrate.md | 231 ++++++++++++++++ docs/pt-BR/commands/plan.md | 115 ++++++++ docs/pt-BR/commands/refactor-clean.md | 80 ++++++ docs/pt-BR/commands/setup-pm.md | 80 ++++++ docs/pt-BR/commands/tdd.md | 328 ++++++++++++++++++++++ docs/pt-BR/commands/test-coverage.md | 69 +++++ docs/pt-BR/commands/update-codemaps.md | 72 +++++ docs/pt-BR/commands/update-docs.md | 84 ++++++ docs/pt-BR/commands/verify.md | 59 ++++ 18 files changed, 2448 insertions(+) create mode 100644 docs/pt-BR/commands/build-fix.md create mode 100644 docs/pt-BR/commands/checkpoint.md create mode 100644 docs/pt-BR/commands/code-review.md create mode 100644 docs/pt-BR/commands/e2e.md create mode 100644 docs/pt-BR/commands/eval.md create mode 100644 docs/pt-BR/commands/go-build.md create mode 100644 docs/pt-BR/commands/go-review.md create mode 100644 docs/pt-BR/commands/go-test.md create mode 100644 docs/pt-BR/commands/learn.md create mode 100644 docs/pt-BR/commands/orchestrate.md create mode 100644 docs/pt-BR/commands/plan.md create mode 100644 docs/pt-BR/commands/refactor-clean.md create mode 100644 docs/pt-BR/commands/setup-pm.md create mode 100644 docs/pt-BR/commands/tdd.md create mode 100644 docs/pt-BR/commands/test-coverage.md create mode 100644 docs/pt-BR/commands/update-codemaps.md create mode 100644 docs/pt-BR/commands/update-docs.md create mode 100644 docs/pt-BR/commands/verify.md diff --git a/docs/pt-BR/commands/build-fix.md b/docs/pt-BR/commands/build-fix.md new file mode 100644 index 00000000..feda490a --- /dev/null +++ b/docs/pt-BR/commands/build-fix.md @@ -0,0 +1,62 @@ +# Build e Correção + +Corrija erros de build e de tipos incrementalmente com mudanças mínimas e seguras. + +## Passo 1: Detectar Sistema de Build + +Identifique a ferramenta de build do projeto e execute o build: + +| Indicator | Build Command | +|-----------|---------------| +| `package.json` with `build` script | `npm run build` or `pnpm build` | +| `tsconfig.json` (TypeScript only) | `npx tsc --noEmit` | +| `Cargo.toml` | `cargo build 2>&1` | +| `pom.xml` | `mvn compile` | +| `build.gradle` | `./gradlew compileJava` | +| `go.mod` | `go build ./...` | +| `pyproject.toml` | `python -m py_compile` or `mypy .` | + +## Passo 2: Parsear e Agrupar Erros + +1. Execute o comando de build e capture o stderr +2. Agrupe erros por caminho de arquivo +3. Ordene por ordem de dependência (corrija imports/tipos antes de erros de lógica) +4. Conte o total de erros para acompanhamento de progresso + +## Passo 3: Loop de Correção (Um Erro por Vez) + +Para cada erro: + +1. **Leia o arquivo** — Use a ferramenta Read para ver o contexto do erro (10 linhas ao redor do erro) +2. **Diagnostique** — Identifique a causa raiz (import ausente, tipo errado, erro de sintaxe) +3. **Corrija minimamente** — Use a ferramenta Edit para a menor mudança que resolve o erro +4. **Rode o build novamente** — Verifique que o erro sumiu e que nenhum novo erro foi introduzido +5. **Vá para o próximo** — Continue com os erros restantes + +## Passo 4: Guardrails + +Pare e pergunte ao usuário se: +- Uma correção introduz **mais erros do que resolve** +- O **mesmo erro persiste após 3 tentativas** (provavelmente há um problema mais profundo) +- A correção exige **mudanças arquiteturais** (não apenas correção de build) +- Os erros de build vêm de **dependências ausentes** (precisa de `npm install`, `cargo add`, etc.) + +## Passo 5: Resumo + +Mostre resultados: +- Erros corrigidos (com caminhos de arquivos) +- Erros restantes (se houver) +- Novos erros introduzidos (deve ser zero) +- Próximos passos sugeridos para problemas não resolvidos + +## Estratégias de Recuperação + +| Situation | Action | +|-----------|--------| +| Missing module/import | Check if package is installed; suggest install command | +| Type mismatch | Read both type definitions; fix the narrower type | +| Circular dependency | Identify cycle with import graph; suggest extraction | +| Version conflict | Check `package.json` / `Cargo.toml` for version constraints | +| Build tool misconfiguration | Read config file; compare with working defaults | + +Corrija um erro por vez por segurança. Prefira diffs mínimos em vez de refatoração. diff --git a/docs/pt-BR/commands/checkpoint.md b/docs/pt-BR/commands/checkpoint.md new file mode 100644 index 00000000..c69c1e6b --- /dev/null +++ b/docs/pt-BR/commands/checkpoint.md @@ -0,0 +1,74 @@ +# Comando Checkpoint + +Crie ou verifique um checkpoint no seu fluxo. + +## Uso + +`/checkpoint [create|verify|list] [name]` + +## Criar Checkpoint + +Ao criar um checkpoint: + +1. Rode `/verify quick` para garantir que o estado atual está limpo +2. Crie um git stash ou commit com o nome do checkpoint +3. Registre o checkpoint em `.claude/checkpoints.log`: + +```bash +echo "$(date +%Y-%m-%d-%H:%M) | $CHECKPOINT_NAME | $(git rev-parse --short HEAD)" >> .claude/checkpoints.log +``` + +4. Informe que o checkpoint foi criado + +## Verificar Checkpoint + +Ao verificar contra um checkpoint: + +1. Leia o checkpoint no log +2. Compare o estado atual com o checkpoint: + - Arquivos adicionados desde o checkpoint + - Arquivos modificados desde o checkpoint + - Taxa de testes passando agora vs antes + - Cobertura agora vs antes + +3. Reporte: +``` +CHECKPOINT COMPARISON: $NAME +============================ +Files changed: X +Tests: +Y passed / -Z failed +Coverage: +X% / -Y% +Build: [PASS/FAIL] +``` + +## Listar Checkpoints + +Mostre todos os checkpoints com: +- Nome +- Timestamp +- Git SHA +- Status (current, behind, ahead) + +## Fluxo + +Fluxo típico de checkpoint: + +``` +[Start] --> /checkpoint create "feature-start" + | +[Implement] --> /checkpoint create "core-done" + | +[Test] --> /checkpoint verify "core-done" + | +[Refactor] --> /checkpoint create "refactor-done" + | +[PR] --> /checkpoint verify "feature-start" +``` + +## Argumentos + +$ARGUMENTS: +- `create ` - Criar checkpoint nomeado +- `verify ` - Verificar contra checkpoint nomeado +- `list` - Mostrar todos os checkpoints +- `clear` - Remover checkpoints antigos (mantém os últimos 5) diff --git a/docs/pt-BR/commands/code-review.md b/docs/pt-BR/commands/code-review.md new file mode 100644 index 00000000..52b9e90d --- /dev/null +++ b/docs/pt-BR/commands/code-review.md @@ -0,0 +1,40 @@ +# Code Review + +Revisão completa de segurança e qualidade das mudanças não commitadas: + +1. Obtenha arquivos alterados: git diff --name-only HEAD + +2. Para cada arquivo alterado, verifique: + +**Problemas de Segurança (CRITICAL):** +- Credenciais, chaves de API ou tokens hardcoded +- Vulnerabilidades de SQL injection +- Vulnerabilidades de XSS +- Falta de validação de entrada +- Dependências inseguras +- Riscos de path traversal + +**Qualidade de Código (HIGH):** +- Funções > 50 linhas +- Arquivos > 800 linhas +- Profundidade de aninhamento > 4 níveis +- Falta de tratamento de erro +- Statements de console.log +- Comentários TODO/FIXME +- Falta de JSDoc para APIs públicas + +**Boas Práticas (MEDIUM):** +- Padrões de mutação (usar imutável no lugar) +- Uso de emoji em código/comentários +- Falta de testes para código novo +- Problemas de acessibilidade (a11y) + +3. Gere relatório com: + - Severidade: CRITICAL, HIGH, MEDIUM, LOW + - Localização no arquivo e números de linha + - Descrição do problema + - Correção sugerida + +4. Bloqueie commit se houver problemas CRITICAL ou HIGH + +Nunca aprove código com vulnerabilidades de segurança! diff --git a/docs/pt-BR/commands/e2e.md b/docs/pt-BR/commands/e2e.md new file mode 100644 index 00000000..41b77f5d --- /dev/null +++ b/docs/pt-BR/commands/e2e.md @@ -0,0 +1,365 @@ +--- +description: Gere e rode testes end-to-end com Playwright. Cria jornadas de teste, executa testes, captura screenshots/videos/traces e faz upload de artefatos. +--- + +# Comando E2E + +Este comando invoca o agente **e2e-runner** para gerar, manter e executar testes end-to-end usando Playwright. + +## O Que Este Comando Faz + +1. **Gerar Jornadas de Teste** - Cria testes Playwright para fluxos de usuário +2. **Rodar Testes E2E** - Executa testes em múltiplos navegadores +3. **Capturar Artefatos** - Screenshots, vídeos, traces em falhas +4. **Upload de Resultados** - Relatórios HTML e JUnit XML +5. **Identificar Testes Flaky** - Coloca testes instáveis em quarentena + +## Quando Usar + +Use `/e2e` quando: +- Testar jornadas críticas de usuário (login, trading, pagamentos) +- Verificar fluxos multi-etapa de ponta a ponta +- Testar interações de UI e navegação +- Validar integração entre frontend e backend +- Preparar para deploy em produção + +## Como Funciona + +O agente e2e-runner vai: + +1. **Analisar o fluxo de usuário** e identificar cenários de teste +2. **Gerar teste Playwright** usando padrão Page Object Model +3. **Rodar testes** em múltiplos navegadores (Chrome, Firefox, Safari) +4. **Capturar falhas** com screenshots, vídeos e traces +5. **Gerar relatório** com resultados e artefatos +6. **Identificar testes flaky** e recomendar correções + +## Exemplo de Uso + +``` +User: /e2e Test the market search and view flow + +Agent (e2e-runner): +# E2E Test Generation: Market Search and View Flow + +## Test Scenario Identified + +**User Journey:** Market Search → View Results → Click Market → View Details + +**Test Coverage:** +1. Navigate to markets page +2. Perform semantic search +3. Verify search results +4. Click on first result +5. Verify market details page loads +6. Verify chart renders + +## Generated Test Code + +```typescript +// tests/e2e/markets/search-and-view.spec.ts +import { test, expect } from '@playwright/test' +import { MarketsPage } from '../../pages/MarketsPage' +import { MarketDetailsPage } from '../../pages/MarketDetailsPage' + +test.describe('Market Search and View Flow', () => { + test('user can search markets and view details', async ({ page }) => { + // 1. Navigate to markets page + const marketsPage = new MarketsPage(page) + await marketsPage.goto() + + // Verify page loaded + await expect(page).toHaveTitle(/Markets/) + await expect(page.locator('h1')).toContainText('Markets') + + // 2. Perform semantic search + await marketsPage.searchMarkets('election') + + // Wait for API response + await page.waitForResponse(resp => + resp.url().includes('/api/markets/search') && resp.status() === 200 + ) + + // 3. Verify search results + const marketCards = marketsPage.marketCards + await expect(marketCards.first()).toBeVisible() + const resultCount = await marketCards.count() + expect(resultCount).toBeGreaterThan(0) + + // Take screenshot of search results + await page.screenshot({ path: 'artifacts/search-results.png' }) + + // 4. Click on first result + const firstMarketTitle = await marketCards.first().textContent() + await marketCards.first().click() + + // 5. Verify market details page loads + await expect(page).toHaveURL(/\/markets\/[a-z0-9-]+/) + + const detailsPage = new MarketDetailsPage(page) + await expect(detailsPage.marketName).toBeVisible() + await expect(detailsPage.marketDescription).toBeVisible() + + // 6. Verify chart renders + await expect(detailsPage.priceChart).toBeVisible() + + // Verify market name matches + const detailsTitle = await detailsPage.marketName.textContent() + expect(detailsTitle?.toLowerCase()).toContain( + firstMarketTitle?.toLowerCase().substring(0, 20) || '' + ) + + // Take screenshot of market details + await page.screenshot({ path: 'artifacts/market-details.png' }) + }) + + test('search with no results shows empty state', async ({ page }) => { + const marketsPage = new MarketsPage(page) + await marketsPage.goto() + + // Search for non-existent market + await marketsPage.searchMarkets('xyznonexistentmarket123456') + + // Verify empty state + await expect(page.locator('[data-testid="no-results"]')).toBeVisible() + await expect(page.locator('[data-testid="no-results"]')).toContainText( + /no.*results|no.*markets/i + ) + + const marketCount = await marketsPage.marketCards.count() + expect(marketCount).toBe(0) + }) + + test('can clear search and see all markets again', async ({ page }) => { + const marketsPage = new MarketsPage(page) + await marketsPage.goto() + + // Initial market count + const initialCount = await marketsPage.marketCards.count() + + // Perform search + await marketsPage.searchMarkets('trump') + await page.waitForLoadState('networkidle') + + // Verify filtered results + const filteredCount = await marketsPage.marketCards.count() + expect(filteredCount).toBeLessThan(initialCount) + + // Clear search + await marketsPage.searchInput.clear() + await page.waitForLoadState('networkidle') + + // Verify all markets shown again + const finalCount = await marketsPage.marketCards.count() + expect(finalCount).toBe(initialCount) + }) +}) +``` + +## Rodando os Testes + +```bash +# Run the generated test +npx playwright test tests/e2e/markets/search-and-view.spec.ts + +Running 3 tests using 3 workers + + ✓ [chromium] › search-and-view.spec.ts:5:3 › user can search markets and view details (4.2s) + ✓ [chromium] › search-and-view.spec.ts:52:3 › search with no results shows empty state (1.8s) + ✓ [chromium] › search-and-view.spec.ts:67:3 › can clear search and see all markets again (2.9s) + + 3 passed (9.1s) + +Artifacts generated: +- artifacts/search-results.png +- artifacts/market-details.png +- playwright-report/index.html +``` + +## Relatório de Teste + +``` +╔══════════════════════════════════════════════════════════════╗ +║ E2E Test Results ║ +╠══════════════════════════════════════════════════════════════╣ +║ Status: ✅ ALL TESTS PASSED ║ +║ Total: 3 tests ║ +║ Passed: 3 (100%) ║ +║ Failed: 0 ║ +║ Flaky: 0 ║ +║ Duration: 9.1s ║ +╚══════════════════════════════════════════════════════════════╝ + +Artifacts: +📸 Screenshots: 2 files +📹 Videos: 0 files (only on failure) +🔍 Traces: 0 files (only on failure) +📊 HTML Report: playwright-report/index.html + +View report: npx playwright show-report +``` + +✅ E2E test suite ready for CI/CD integration! +``` + +## Artefatos de Teste + +Quando os testes rodam, os seguintes artefatos são capturados: + +**Em Todos os Testes:** +- Relatório HTML com timeline e resultados +- JUnit XML para integração com CI + +**Somente em Falha:** +- Screenshot do estado de falha +- Gravação em vídeo do teste +- Arquivo de trace para debug (replay passo a passo) +- Logs de rede +- Logs de console + +## Visualizando Artefatos + +```bash +# View HTML report in browser +npx playwright show-report + +# View specific trace file +npx playwright show-trace artifacts/trace-abc123.zip + +# Screenshots are saved in artifacts/ directory +open artifacts/search-results.png +``` + +## Detecção de Teste Flaky + +Se um teste falhar de forma intermitente: + +``` +⚠️ FLAKY TEST DETECTED: tests/e2e/markets/trade.spec.ts + +Test passed 7/10 runs (70% pass rate) + +Common failure: +"Timeout waiting for element '[data-testid="confirm-btn"]'" + +Recommended fixes: +1. Add explicit wait: await page.waitForSelector('[data-testid="confirm-btn"]') +2. Increase timeout: { timeout: 10000 } +3. Check for race conditions in component +4. Verify element is not hidden by animation + +Quarantine recommendation: Mark as test.fixme() until fixed +``` + +## Configuração de Navegador + +Os testes rodam em múltiplos navegadores por padrão: +- ✅ Chromium (Desktop Chrome) +- ✅ Firefox (Desktop) +- ✅ WebKit (Desktop Safari) +- ✅ Mobile Chrome (optional) + +Configure em `playwright.config.ts` para ajustar navegadores. + +## Integração CI/CD + +Adicione ao seu pipeline de CI: + +```yaml +# .github/workflows/e2e.yml +- name: Install Playwright + run: npx playwright install --with-deps + +- name: Run E2E tests + run: npx playwright test + +- name: Upload artifacts + if: always() + uses: actions/upload-artifact@v3 + with: + name: playwright-report + path: playwright-report/ +``` + +## Fluxos Críticos Específicos do PMX + +Para PMX, priorize estes testes E2E: + +**🔴 CRITICAL (Must Always Pass):** +1. User can connect wallet +2. User can browse markets +3. User can search markets (semantic search) +4. User can view market details +5. User can place trade (with test funds) +6. Market resolves correctly +7. User can withdraw funds + +**🟡 IMPORTANT:** +1. Market creation flow +2. User profile updates +3. Real-time price updates +4. Chart rendering +5. Filter and sort markets +6. Mobile responsive layout + +## Boas Práticas + +**DO:** +- ✅ Use Page Object Model para manutenção +- ✅ Use atributos data-testid para seletores +- ✅ Aguarde respostas de API, não timeouts arbitrários +- ✅ Teste jornadas críticas de usuário end-to-end +- ✅ Rode testes antes de mergear em main +- ✅ Revise artefatos quando testes falharem + +**DON'T:** +- ❌ Use seletores frágeis (classes CSS podem mudar) +- ❌ Teste detalhes de implementação +- ❌ Rode testes contra produção +- ❌ Ignore testes flaky +- ❌ Pule revisão de artefatos em falhas +- ❌ Teste todo edge case com E2E (use testes unitários) + +## Notas Importantes + +**CRITICAL para PMX:** +- Testes E2E envolvendo dinheiro real DEVEM rodar apenas em testnet/staging +- Nunca rode testes de trading em produção +- Defina `test.skip(process.env.NODE_ENV === 'production')` para testes financeiros +- Use carteiras de teste com fundos de teste pequenos apenas + +## Integração com Outros Comandos + +- Use `/plan` para identificar jornadas críticas a testar +- Use `/tdd` para testes unitários (mais rápidos e granulares) +- Use `/e2e` para integração e jornadas de usuário +- Use `/code-review` para verificar qualidade dos testes + +## Agentes Relacionados + +Este comando invoca o agente `e2e-runner` fornecido pelo ECC. + +Para instalações manuais, o arquivo fonte fica em: +`agents/e2e-runner.md` + +## Comandos Rápidos + +```bash +# Run all E2E tests +npx playwright test + +# Run specific test file +npx playwright test tests/e2e/markets/search.spec.ts + +# Run in headed mode (see browser) +npx playwright test --headed + +# Debug test +npx playwright test --debug + +# Generate test code +npx playwright codegen http://localhost:3000 + +# View report +npx playwright show-report +``` diff --git a/docs/pt-BR/commands/eval.md b/docs/pt-BR/commands/eval.md new file mode 100644 index 00000000..438efda5 --- /dev/null +++ b/docs/pt-BR/commands/eval.md @@ -0,0 +1,120 @@ +# Comando Eval + +Gerencie o fluxo de desenvolvimento orientado por evals. + +## Uso + +`/eval [define|check|report|list] [feature-name]` + +## Definir Evals + +`/eval define feature-name` + +Crie uma nova definição de eval: + +1. Crie `.claude/evals/feature-name.md` com o template: + +```markdown +## EVAL: feature-name +Created: $(date) + +### Capability Evals +- [ ] [Description of capability 1] +- [ ] [Description of capability 2] + +### Regression Evals +- [ ] [Existing behavior 1 still works] +- [ ] [Existing behavior 2 still works] + +### Success Criteria +- pass@3 > 90% for capability evals +- pass^3 = 100% for regression evals +``` + +2. Peça ao usuário para preencher os critérios específicos + +## Verificar Evals + +`/eval check feature-name` + +Rode evals para uma feature: + +1. Leia a definição de eval em `.claude/evals/feature-name.md` +2. Para cada eval de capability: + - Tente verificar o critério + - Registre PASS/FAIL + - Salve tentativa em `.claude/evals/feature-name.log` +3. Para cada eval de regressão: + - Rode os testes relevantes + - Compare com baseline + - Registre PASS/FAIL +4. Reporte status atual: + +``` +EVAL CHECK: feature-name +======================== +Capability: X/Y passing +Regression: X/Y passing +Status: IN PROGRESS / READY +``` + +## Relatório de Evals + +`/eval report feature-name` + +Gere relatório completo de eval: + +``` +EVAL REPORT: feature-name +========================= +Generated: $(date) + +CAPABILITY EVALS +---------------- +[eval-1]: PASS (pass@1) +[eval-2]: PASS (pass@2) - required retry +[eval-3]: FAIL - see notes + +REGRESSION EVALS +---------------- +[test-1]: PASS +[test-2]: PASS +[test-3]: PASS + +METRICS +------- +Capability pass@1: 67% +Capability pass@3: 100% +Regression pass^3: 100% + +NOTES +----- +[Any issues, edge cases, or observations] + +RECOMMENDATION +-------------- +[SHIP / NEEDS WORK / BLOCKED] +``` + +## Listar Evals + +`/eval list` + +Mostre todas as definições de eval: + +``` +EVAL DEFINITIONS +================ +feature-auth [3/5 passing] IN PROGRESS +feature-search [5/5 passing] READY +feature-export [0/4 passing] NOT STARTED +``` + +## Argumentos + +$ARGUMENTS: +- `define ` - Criar nova definição de eval +- `check ` - Rodar e verificar evals +- `report ` - Gerar relatório completo +- `list` - Mostrar todos os evals +- `clean` - Remover logs antigos de eval (mantém as últimas 10 execuções) diff --git a/docs/pt-BR/commands/go-build.md b/docs/pt-BR/commands/go-build.md new file mode 100644 index 00000000..2e620bf9 --- /dev/null +++ b/docs/pt-BR/commands/go-build.md @@ -0,0 +1,183 @@ +--- +description: Corrija erros de build em Go, avisos de go vet e problemas de lint incrementalmente. Invoca o agente go-build-resolver para correções mínimas e cirúrgicas. +--- + +# Build e Correção Go + +Este comando invoca o agente **go-build-resolver** para corrigir erros de build Go incrementalmente com mudanças mínimas. + +## O Que Este Comando Faz + +1. **Rodar Diagnósticos**: Executa `go build`, `go vet`, `staticcheck` +2. **Parsear Erros**: Agrupa por arquivo e ordena por severidade +3. **Corrigir Incrementalmente**: Um erro por vez +4. **Verificar Cada Correção**: Roda build de novo após cada mudança +5. **Reportar Resumo**: Mostra o que foi corrigido e o que resta + +## Quando Usar + +Use `/go-build` quando: +- `go build ./...` falhar com erros +- `go vet ./...` reportar problemas +- `golangci-lint run` mostrar avisos +- Dependências do módulo estiverem quebradas +- Após puxar mudanças que quebraram o build + +## Comandos de Diagnóstico Executados + +```bash +# Primary build check +go build ./... + +# Static analysis +go vet ./... + +# Extended linting (if available) +staticcheck ./... +golangci-lint run + +# Module issues +go mod verify +go mod tidy -v +``` + +## Exemplo de Sessão + +```text +User: /go-build + +Agent: +# Go Build Resolution + +## Initial Diagnostics + +```bash +$ go build ./... +internal/service/user.go:25:15: undefined: UserRepository +internal/handler/api.go:42:9: cannot use x (type string) as type int +internal/handler/api.go:58:2: missing return at end of function +``` + +Errors found: 3 + +## Fix 1: Undefined Identifier + +File: internal/service/user.go:25 +Error: undefined: UserRepository +Cause: Missing import + +```go +// Added import +import "project/internal/repository" + +// Changed +var repo UserRepository +// To +var repo repository.UserRepository +``` + +```bash +$ go build ./... +# 2 errors remaining +``` + +## Fix 2: Type Mismatch + +File: internal/handler/api.go:42 +Error: cannot use x (type string) as type int + +```go +// Changed +count := params.Get("count") +// To +countStr := params.Get("count") +count, _ := strconv.Atoi(countStr) +``` + +```bash +$ go build ./... +# 1 error remaining +``` + +## Fix 3: Missing Return + +File: internal/handler/api.go:58 +Error: missing return at end of function + +```go +func GetUser(id string) (*User, error) { + if id == "" { + return nil, ErrInvalidID + } + user := findUser(id) + // Added missing return + return user, nil +} +``` + +```bash +$ go build ./... +# Build successful! +``` + +## Final Verification + +```bash +$ go vet ./... +# No issues + +$ go test ./... +ok project/internal/service 0.015s +ok project/internal/handler 0.023s +``` + +## Summary + +| Metric | Count | +|--------|-------| +| Build errors fixed | 3 | +| Vet warnings fixed | 0 | +| Files modified | 2 | +| Remaining issues | 0 | + +Build Status: ✅ SUCCESS +``` + +## Erros Comuns Corrigidos + +| Error | Typical Fix | +|-------|-------------| +| `undefined: X` | Add import or fix typo | +| `cannot use X as Y` | Type conversion or fix assignment | +| `missing return` | Add return statement | +| `X does not implement Y` | Add missing method | +| `import cycle` | Restructure packages | +| `declared but not used` | Remove or use variable | +| `cannot find package` | `go get` or `go mod tidy` | + +## Estratégia de Correção + +1. **Erros de build primeiro** - O código precisa compilar +2. **Avisos do vet depois** - Corrigir construções suspeitas +3. **Avisos de lint por último** - Estilo e boas práticas +4. **Uma correção por vez** - Verificar cada mudança +5. **Mudanças mínimas** - Não refatorar, apenas corrigir + +## Condições de Parada + +O agente vai parar e reportar se: +- O mesmo erro persistir após 3 tentativas +- A correção introduzir mais erros +- Exigir mudanças arquiteturais +- Faltarem dependências externas + +## Comandos Relacionados + +- `/go-test` - Rode testes após o build passar +- `/go-review` - Revise qualidade do código +- `/verify` - Loop completo de verificação + +## Relacionado + +- Agent: `agents/go-build-resolver.md` +- Skill: `skills/golang-patterns/` diff --git a/docs/pt-BR/commands/go-review.md b/docs/pt-BR/commands/go-review.md new file mode 100644 index 00000000..fb8e10d8 --- /dev/null +++ b/docs/pt-BR/commands/go-review.md @@ -0,0 +1,148 @@ +--- +description: Revisão completa de código Go para padrões idiomáticos, segurança de concorrência, tratamento de erro e segurança. Invoca o agente go-reviewer. +--- + +# Code Review Go + +Este comando invoca o agente **go-reviewer** para revisão abrangente e específica de Go. + +## O Que Este Comando Faz + +1. **Identificar Mudanças Go**: Encontra arquivos `.go` modificados via `git diff` +2. **Rodar Análise Estática**: Executa `go vet`, `staticcheck` e `golangci-lint` +3. **Varredura de Segurança**: Verifica SQL injection, command injection e race conditions +4. **Revisão de Concorrência**: Analisa segurança de goroutines, uso de channels e padrões com mutex +5. **Checagem de Go Idiomático**: Verifica se o código segue convenções e boas práticas de Go +6. **Gerar Relatório**: Categoriza problemas por severidade + +## Quando Usar + +Use `/go-review` quando: +- Após escrever ou modificar código Go +- Antes de commitar mudanças Go +- Ao revisar pull requests com código Go +- Ao entrar em um novo codebase Go +- Ao aprender padrões idiomáticos Go + +## Categorias de Revisão + +### CRITICAL (Obrigatório Corrigir) +- Vulnerabilidades de SQL/Command injection +- Race conditions sem sincronização +- Vazamento de goroutine +- Credenciais hardcoded +- Uso inseguro de ponteiros +- Erros ignorados em caminhos críticos + +### HIGH (Deve Corrigir) +- Falta de wrapping de erro com contexto +- Panic em vez de retorno de erro +- Context não propagado +- Canais não bufferizados causando deadlock +- Erros de interface não satisfeita +- Falta de proteção com mutex + +### MEDIUM (Considere) +- Padrões não idiomáticos +- Falta de comentários godoc em exports +- Concatenação de string ineficiente +- Slice sem pré-alocação +- Table-driven tests não usados + +## Checagens Automáticas Executadas + +```bash +# Static analysis +go vet ./... + +# Advanced checks (if installed) +staticcheck ./... +golangci-lint run + +# Race detection +go build -race ./... + +# Security vulnerabilities +govulncheck ./... +``` + +## Exemplo de Uso + +```text +User: /go-review + +Agent: +# Go Code Review Report + +## Files Reviewed +- internal/handler/user.go (modified) +- internal/service/auth.go (modified) + +## Static Analysis Results +✓ go vet: No issues +✓ staticcheck: No issues + +## Issues Found + +[CRITICAL] Race Condition +File: internal/service/auth.go:45 +Issue: Shared map accessed without synchronization +```go +var cache = map[string]*Session{} // Concurrent access! + +func GetSession(id string) *Session { + return cache[id] // Race condition +} +``` +Fix: Use sync.RWMutex or sync.Map +```go +var ( + cache = map[string]*Session{} + cacheMu sync.RWMutex +) + +func GetSession(id string) *Session { + cacheMu.RLock() + defer cacheMu.RUnlock() + return cache[id] +} +``` + +[HIGH] Missing Error Context +File: internal/handler/user.go:28 +Issue: Error returned without context +```go +return err // No context +``` +Fix: Wrap with context +```go +return fmt.Errorf("get user %s: %w", userID, err) +``` + +## Summary +- CRITICAL: 1 +- HIGH: 1 +- MEDIUM: 0 + +Recommendation: ❌ Block merge until CRITICAL issue is fixed +``` + +## Critérios de Aprovação + +| Status | Condition | +|--------|-----------| +| ✅ Approve | No CRITICAL or HIGH issues | +| ⚠️ Warning | Only MEDIUM issues (merge with caution) | +| ❌ Block | CRITICAL or HIGH issues found | + +## Integração com Outros Comandos + +- Use `/go-test` primeiro para garantir que os testes passam +- Use `/go-build` se houver erros de build +- Use `/go-review` antes de commitar +- Use `/code-review` para preocupações não específicas de Go + +## Relacionado + +- Agent: `agents/go-reviewer.md` +- Skills: `skills/golang-patterns/`, `skills/golang-testing/` diff --git a/docs/pt-BR/commands/go-test.md b/docs/pt-BR/commands/go-test.md new file mode 100644 index 00000000..d608c825 --- /dev/null +++ b/docs/pt-BR/commands/go-test.md @@ -0,0 +1,268 @@ +--- +description: Impõe fluxo de TDD para Go. Escreva table-driven tests primeiro e depois implemente. Verifique cobertura de 80%+ com go test -cover. +--- + +# Comando TDD Go + +Este comando impõe a metodologia de desenvolvimento orientado a testes para código Go usando padrões idiomáticos de teste em Go. + +## O Que Este Comando Faz + +1. **Definir Tipos/Interfaces**: Estrutura assinaturas de função primeiro +2. **Escrever Table-Driven Tests**: Criar casos de teste abrangentes (RED) +3. **Rodar Testes**: Verificar que os testes falham pelo motivo certo +4. **Implementar Código**: Escrever código mínimo para passar (GREEN) +5. **Refatorar**: Melhorar mantendo testes verdes +6. **Checar Cobertura**: Garantir 80%+ de cobertura + +## Quando Usar + +Use `/go-test` quando: +- Implementar novas funções Go +- Adicionar cobertura de testes a código existente +- Corrigir bugs (escreva primeiro o teste que falha) +- Construir lógica de negócio crítica +- Aprender fluxo TDD em Go + +## Ciclo TDD + +``` +RED → Write failing table-driven test +GREEN → Implement minimal code to pass +REFACTOR → Improve code, tests stay green +REPEAT → Next test case +``` + +## Exemplo de Sessão + +```` +User: /go-test I need a function to validate email addresses + +Agent: +# TDD Session: Email Validator + +## Step 1: Define Interface + +```go +// validator/email.go +package validator + +// ValidateEmail checks if the given string is a valid email address. +// Returns nil if valid, error describing the issue otherwise. +func ValidateEmail(email string) error { + panic("not implemented") +} +``` + +## Step 2: Write Table-Driven Tests (RED) + +```go +// validator/email_test.go +package validator + +import ( + "testing" +) + +func TestValidateEmail(t *testing.T) { + tests := []struct { + name string + email string + wantErr bool + }{ + // Valid emails + {"simple email", "user@example.com", false}, + {"with subdomain", "user@mail.example.com", false}, + {"with plus", "user+tag@example.com", false}, + {"with dots", "first.last@example.com", false}, + + // Invalid emails + {"empty string", "", true}, + {"no at sign", "userexample.com", true}, + {"no domain", "user@", true}, + {"no local part", "@example.com", true}, + {"double at", "user@@example.com", true}, + {"spaces", "user @example.com", true}, + {"no tld", "user@example", true}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + err := ValidateEmail(tt.email) + if tt.wantErr && err == nil { + t.Errorf("ValidateEmail(%q) = nil; want error", tt.email) + } + if !tt.wantErr && err != nil { + t.Errorf("ValidateEmail(%q) = %v; want nil", tt.email, err) + } + }) + } +} +``` + +## Step 3: Run Tests - Verify FAIL + +```bash +$ go test ./validator/... + +--- FAIL: TestValidateEmail (0.00s) + --- FAIL: TestValidateEmail/simple_email (0.00s) + panic: not implemented + +FAIL +``` + +✓ Tests fail as expected (panic). + +## Step 4: Implement Minimal Code (GREEN) + +```go +// validator/email.go +package validator + +import ( + "errors" + "regexp" +) + +var emailRegex = regexp.MustCompile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`) + +var ( + ErrEmailEmpty = errors.New("email cannot be empty") + ErrEmailInvalid = errors.New("email format is invalid") +) + +func ValidateEmail(email string) error { + if email == "" { + return ErrEmailEmpty + } + if !emailRegex.MatchString(email) { + return ErrEmailInvalid + } + return nil +} +``` + +## Step 5: Run Tests - Verify PASS + +```bash +$ go test ./validator/... + +PASS +ok project/validator 0.003s +``` + +✓ All tests passing! + +## Step 6: Check Coverage + +```bash +$ go test -cover ./validator/... + +PASS +coverage: 100.0% of statements +ok project/validator 0.003s +``` + +✓ Coverage: 100% + +## TDD Complete! +```` + +## Padrões de Teste + +### Table-Driven Tests +```go +tests := []struct { + name string + input InputType + want OutputType + wantErr bool +}{ + {"case 1", input1, want1, false}, + {"case 2", input2, want2, true}, +} + +for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got, err := Function(tt.input) + // assertions + }) +} +``` + +### Testes Paralelos +```go +for _, tt := range tests { + tt := tt // Capture + t.Run(tt.name, func(t *testing.T) { + t.Parallel() + // test body + }) +} +``` + +### Helpers de Teste +```go +func setupTestDB(t *testing.T) *sql.DB { + t.Helper() + db := createDB() + t.Cleanup(func() { db.Close() }) + return db +} +``` + +## Comandos de Cobertura + +```bash +# Basic coverage +go test -cover ./... + +# Coverage profile +go test -coverprofile=coverage.out ./... + +# View in browser +go tool cover -html=coverage.out + +# Coverage by function +go tool cover -func=coverage.out + +# With race detection +go test -race -cover ./... +``` + +## Metas de Cobertura + +| Code Type | Target | +|-----------|--------| +| Critical business logic | 100% | +| Public APIs | 90%+ | +| General code | 80%+ | +| Generated code | Exclude | + +## Boas Práticas de TDD + +**DO:** +- Escreva teste PRIMEIRO, antes de qualquer implementação +- Rode testes após cada mudança +- Use table-driven tests para cobertura abrangente +- Teste comportamento, não detalhes de implementação +- Inclua casos de borda (empty, nil, max values) + +**DON'T:** +- Escrever implementação antes dos testes +- Pular a fase RED +- Testar funções privadas diretamente +- Usar `time.Sleep` em testes +- Ignorar testes flaky + +## Comandos Relacionados + +- `/go-build` - Corrigir erros de build +- `/go-review` - Revisar código após implementação +- `/verify` - Rodar loop completo de verificação + +## Relacionado + +- Skill: `skills/golang-testing/` +- Skill: `skills/tdd-workflow/` diff --git a/docs/pt-BR/commands/learn.md b/docs/pt-BR/commands/learn.md new file mode 100644 index 00000000..6c6154d2 --- /dev/null +++ b/docs/pt-BR/commands/learn.md @@ -0,0 +1,70 @@ +# /learn - Extrair Padrões Reutilizáveis + +Analise a sessão atual e extraia padrões que valem ser salvos como skills. + +## Trigger + +Rode `/learn` em qualquer ponto da sessão quando você tiver resolvido um problema não trivial. + +## O Que Extrair + +Procure por: + +1. **Padrões de Resolução de Erro** + - Qual erro ocorreu? + - Qual foi a causa raiz? + - O que corrigiu? + - Isso é reutilizável para erros semelhantes? + +2. **Técnicas de Debug** + - Passos de debug não óbvios + - Combinações de ferramentas que funcionaram + - Padrões de diagnóstico + +3. **Workarounds** + - Quirks de bibliotecas + - Limitações de API + - Correções específicas de versão + +4. **Padrões Específicos do Projeto** + - Convenções de codebase descobertas + - Decisões de arquitetura tomadas + - Padrões de integração + +## Formato de Saída + +Crie um arquivo de skill em `~/.claude/skills/learned/[pattern-name].md`: + +```markdown +# [Descriptive Pattern Name] + +**Extracted:** [Date] +**Context:** [Brief description of when this applies] + +## Problem +[What problem this solves - be specific] + +## Solution +[The pattern/technique/workaround] + +## Example +[Code example if applicable] + +## When to Use +[Trigger conditions - what should activate this skill] +``` + +## Processo + +1. Revise a sessão para identificar padrões extraíveis +2. Identifique o insight mais valioso/reutilizável +3. Esboce o arquivo de skill +4. Peça confirmação do usuário antes de salvar +5. Salve em `~/.claude/skills/learned/` + +## Notas + +- Não extraia correções triviais (typos, erros simples de sintaxe) +- Não extraia problemas de uso único (indisponibilidade específica de API etc.) +- Foque em padrões que vão economizar tempo em sessões futuras +- Mantenha skills focadas - um padrão por skill diff --git a/docs/pt-BR/commands/orchestrate.md b/docs/pt-BR/commands/orchestrate.md new file mode 100644 index 00000000..b192321c --- /dev/null +++ b/docs/pt-BR/commands/orchestrate.md @@ -0,0 +1,231 @@ +--- +description: Orientação de orquestração sequencial e tmux/worktree para fluxos multiagente. +--- + +# Comando Orchestrate + +Fluxo sequencial de agentes para tarefas complexas. + +## Uso + +`/orchestrate [workflow-type] [task-description]` + +## Tipos de Workflow + +### feature +Workflow completo de implementação de feature: +``` +planner -> tdd-guide -> code-reviewer -> security-reviewer +``` + +### bugfix +Workflow de investigação e correção de bug: +``` +planner -> tdd-guide -> code-reviewer +``` + +### refactor +Workflow de refatoração segura: +``` +architect -> code-reviewer -> tdd-guide +``` + +### security +Revisão focada em segurança: +``` +security-reviewer -> code-reviewer -> architect +``` + +## Padrão de Execução + +Para cada agente no workflow: + +1. **Invoque o agente** com contexto do agente anterior +2. **Colete saída** como documento estruturado de handoff +3. **Passe para o próximo agente** na cadeia +4. **Agregue resultados** em um relatório final + +## Formato do Documento de Handoff + +Entre agentes, crie um documento de handoff: + +```markdown +## HANDOFF: [previous-agent] -> [next-agent] + +### Context +[Summary of what was done] + +### Findings +[Key discoveries or decisions] + +### Files Modified +[List of files touched] + +### Open Questions +[Unresolved items for next agent] + +### Recommendations +[Suggested next steps] +``` + +## Exemplo: Workflow de Feature + +``` +/orchestrate feature "Add user authentication" +``` + +Executa: + +1. **Planner Agent** + - Analisa requisitos + - Cria plano de implementação + - Identifica dependências + - Saída: `HANDOFF: planner -> tdd-guide` + +2. **TDD Guide Agent** + - Lê handoff do planner + - Escreve testes primeiro + - Implementa para passar testes + - Saída: `HANDOFF: tdd-guide -> code-reviewer` + +3. **Code Reviewer Agent** + - Revisa implementação + - Verifica problemas + - Sugere melhorias + - Saída: `HANDOFF: code-reviewer -> security-reviewer` + +4. **Security Reviewer Agent** + - Auditoria de segurança + - Verificação de vulnerabilidades + - Aprovação final + - Saída: Relatório Final + +## Formato do Relatório Final + +``` +ORCHESTRATION REPORT +==================== +Workflow: feature +Task: Add user authentication +Agents: planner -> tdd-guide -> code-reviewer -> security-reviewer + +SUMMARY +------- +[One paragraph summary] + +AGENT OUTPUTS +------------- +Planner: [summary] +TDD Guide: [summary] +Code Reviewer: [summary] +Security Reviewer: [summary] + +FILES CHANGED +------------- +[List all files modified] + +TEST RESULTS +------------ +[Test pass/fail summary] + +SECURITY STATUS +--------------- +[Security findings] + +RECOMMENDATION +-------------- +[SHIP / NEEDS WORK / BLOCKED] +``` + +## Execução Paralela + +Para verificações independentes, rode agentes em paralelo: + +```markdown +### Parallel Phase +Run simultaneously: +- code-reviewer (quality) +- security-reviewer (security) +- architect (design) + +### Merge Results +Combine outputs into single report +``` + +Para workers externos em tmux panes com git worktrees separados, use `node scripts/orchestrate-worktrees.js plan.json --execute`. O padrão embutido de orquestração permanece no processo atual; o helper é para sessões longas ou cross-harness. + +Quando os workers precisarem enxergar arquivos locais sujos ou não rastreados do checkout principal, adicione `seedPaths` ao arquivo de plano. O ECC faz overlay apenas desses caminhos selecionados em cada worktree do worker após `git worktree add`, mantendo o branch isolado e ainda expondo scripts, planos ou docs em andamento. + +```json +{ + "sessionName": "workflow-e2e", + "seedPaths": [ + "scripts/orchestrate-worktrees.js", + "scripts/lib/tmux-worktree-orchestrator.js", + ".claude/plan/workflow-e2e-test.json" + ], + "workers": [ + { "name": "docs", "task": "Update orchestration docs." } + ] +} +``` + +Para exportar um snapshot do control plane para uma sessão tmux/worktree ao vivo, rode: + +```bash +node scripts/orchestration-status.js .claude/plan/workflow-visual-proof.json +``` + +O snapshot inclui atividade da sessão, metadados de pane do tmux, estado dos workers, objetivos, overlays semeados e resumos recentes de handoff em formato JSON. + +## Handoff de Command Center do Operador + +Quando o workflow atravessar múltiplas sessões, worktrees ou panes tmux, acrescente um bloco de control plane ao handoff final: + +```markdown +CONTROL PLANE +------------- +Sessions: +- active session ID or alias +- branch + worktree path for each active worker +- tmux pane or detached session name when applicable + +Diffs: +- git status summary +- git diff --stat for touched files +- merge/conflict risk notes + +Approvals: +- pending user approvals +- blocked steps awaiting confirmation + +Telemetry: +- last activity timestamp or idle signal +- estimated token or cost drift +- policy events raised by hooks or reviewers +``` + +Isso mantém planner, implementador, revisor e loop workers legíveis pela superfície de operação. + +## Argumentos + +$ARGUMENTS: +- `feature ` - Workflow completo de feature +- `bugfix ` - Workflow de correção de bug +- `refactor ` - Workflow de refatoração +- `security ` - Workflow de revisão de segurança +- `custom ` - Sequência customizada de agentes + +## Exemplo de Workflow Customizado + +``` +/orchestrate custom "architect,tdd-guide,code-reviewer" "Redesign caching layer" +``` + +## Dicas + +1. **Comece com planner** para features complexas +2. **Sempre inclua code-reviewer** antes do merge +3. **Use security-reviewer** para auth/pagamento/PII +4. **Mantenha handoffs concisos** - foque no que o próximo agente precisa +5. **Rode verificação** entre agentes quando necessário diff --git a/docs/pt-BR/commands/plan.md b/docs/pt-BR/commands/plan.md new file mode 100644 index 00000000..e21e2b4d --- /dev/null +++ b/docs/pt-BR/commands/plan.md @@ -0,0 +1,115 @@ +--- +description: Reafirme requisitos, avalie riscos e crie plano de implementação passo a passo. ESPERE confirmação do usuário ANTES de tocar em qualquer código. +--- + +# Comando Plan + +Este comando invoca o agente **planner** para criar um plano abrangente de implementação antes de escrever qualquer código. + +## O Que Este Comando Faz + +1. **Reafirmar Requisitos** - Esclarecer o que precisa ser construído +2. **Identificar Riscos** - Levantar problemas e bloqueios potenciais +3. **Criar Plano em Etapas** - Quebrar implementação em fases +4. **Aguardar Confirmação** - DEVE receber aprovação do usuário antes de prosseguir + +## Quando Usar + +Use `/plan` quando: +- Estiver iniciando uma nova feature +- For fazer mudanças arquiteturais significativas +- Estiver trabalhando em refatoração complexa +- Múltiplos arquivos/componentes serão afetados +- Requisitos estiverem pouco claros ou ambíguos + +## Como Funciona + +O agente planner vai: + +1. **Analisar o pedido** e reafirmar os requisitos de forma clara +2. **Quebrar em fases** com etapas específicas e acionáveis +3. **Identificar dependências** entre componentes +4. **Avaliar riscos** e possíveis bloqueios +5. **Estimar complexidade** (High/Medium/Low) +6. **Apresentar o plano** e AGUARDAR sua confirmação explícita + +## Exemplo de Uso + +``` +User: /plan I need to add real-time notifications when markets resolve + +Agent (planner): +# Implementation Plan: Real-Time Market Resolution Notifications + +## Requirements Restatement +- Send notifications to users when markets they're watching resolve +- Support multiple notification channels (in-app, email, webhook) +- Ensure notifications are delivered reliably +- Include market outcome and user's position result + +## Implementation Phases + +### Phase 1: Database Schema +- Add notifications table with columns: id, user_id, market_id, type, status, created_at +- Add user_notification_preferences table for channel preferences +- Create indexes on user_id and market_id for performance + +### Phase 2: Notification Service +- Create notification service in lib/notifications.ts +- Implement notification queue using BullMQ/Redis +- Add retry logic for failed deliveries +- Create notification templates + +### Phase 3: Integration Points +- Hook into market resolution logic (when status changes to "resolved") +- Query all users with positions in market +- Enqueue notifications for each user + +### Phase 4: Frontend Components +- Create NotificationBell component in header +- Add NotificationList modal +- Implement real-time updates via Supabase subscriptions +- Add notification preferences page + +## Dependencies +- Redis (for queue) +- Email service (SendGrid/Resend) +- Supabase real-time subscriptions + +## Risks +- HIGH: Email deliverability (SPF/DKIM required) +- MEDIUM: Performance with 1000+ users per market +- MEDIUM: Notification spam if markets resolve frequently +- LOW: Real-time subscription overhead + +## Estimated Complexity: MEDIUM +- Backend: 4-6 hours +- Frontend: 3-4 hours +- Testing: 2-3 hours +- Total: 9-13 hours + +**WAITING FOR CONFIRMATION**: Proceed with this plan? (yes/no/modify) +``` + +## Notas Importantes + +**CRITICAL**: O agente planner **NÃO** vai escrever código até você confirmar explicitamente o plano com "yes", "proceed" ou resposta afirmativa similar. + +Se quiser mudanças, responda com: +- "modify: [your changes]" +- "different approach: [alternative]" +- "skip phase 2 and do phase 3 first" + +## Integração com Outros Comandos + +Após planejar: +- Use `/tdd` para implementar com test-driven development +- Use `/build-fix` se ocorrerem erros de build +- Use `/code-review` para revisar a implementação concluída + +## Agentes Relacionados + +Este comando invoca o agente `planner` fornecido pelo ECC. + +Para instalações manuais, o arquivo fonte fica em: +`agents/planner.md` diff --git a/docs/pt-BR/commands/refactor-clean.md b/docs/pt-BR/commands/refactor-clean.md new file mode 100644 index 00000000..cf8573d9 --- /dev/null +++ b/docs/pt-BR/commands/refactor-clean.md @@ -0,0 +1,80 @@ +# Refactor Clean + +Identifique e remova código morto com segurança, com verificação de testes em cada passo. + +## Passo 1: Detectar Código Morto + +Rode ferramentas de análise com base no tipo do projeto: + +| Tool | What It Finds | Command | +|------|--------------|---------| +| knip | Unused exports, files, dependencies | `npx knip` | +| depcheck | Unused npm dependencies | `npx depcheck` | +| ts-prune | Unused TypeScript exports | `npx ts-prune` | +| vulture | Unused Python code | `vulture src/` | +| deadcode | Unused Go code | `deadcode ./...` | +| cargo-udeps | Unused Rust dependencies | `cargo +nightly udeps` | + +Se nenhuma ferramenta estiver disponível, use Grep para encontrar exports com zero imports: +``` +# Find exports, then check if they're imported anywhere +``` + +## Passo 2: Categorizar Achados + +Classifique os achados em níveis de segurança: + +| Tier | Examples | Action | +|------|----------|--------| +| **SAFE** | Unused utilities, test helpers, internal functions | Delete with confidence | +| **CAUTION** | Components, API routes, middleware | Verify no dynamic imports or external consumers | +| **DANGER** | Config files, entry points, type definitions | Investigate before touching | + +## Passo 3: Loop de Remoção Segura + +Para cada item SAFE: + +1. **Rode a suíte completa de testes** — Estabeleça baseline (tudo verde) +2. **Delete o código morto** — Use a ferramenta Edit para remoção cirúrgica +3. **Rode a suíte de testes novamente** — Verifique se nada quebrou +4. **Se testes falharem** — Reverta imediatamente com `git checkout -- ` e pule este item +5. **Se testes passarem** — Vá para o próximo item + +## Passo 4: Tratar Itens CAUTION + +Antes de deletar itens CAUTION: +- Procure imports dinâmicos: `import()`, `require()`, `__import__` +- Procure referências em string: nomes de rota, nomes de componente em configs +- Verifique se é exportado por API pública de pacote +- Verifique ausência de consumidores externos (dependents, se publicado) + +## Passo 5: Consolidar Duplicatas + +Depois de remover código morto, procure: +- Funções quase duplicadas (>80% similares) — mesclar em uma +- Definições de tipo redundantes — consolidar +- Funções wrapper sem valor — inline +- Re-exports sem propósito — remover indireção + +## Passo 6: Resumo + +Reporte resultados: + +``` +Dead Code Cleanup +────────────────────────────── +Deleted: 12 unused functions + 3 unused files + 5 unused dependencies +Skipped: 2 items (tests failed) +Saved: ~450 lines removed +────────────────────────────── +All tests passing ✅ +``` + +## Regras + +- **Nunca delete sem rodar testes antes** +- **Uma remoção por vez** — Mudanças atômicas facilitam rollback +- **Se houver dúvida, pule** — Melhor manter código morto do que quebrar produção +- **Não refatore durante limpeza** — Separe responsabilidades (limpar primeiro, refatorar depois) diff --git a/docs/pt-BR/commands/setup-pm.md b/docs/pt-BR/commands/setup-pm.md new file mode 100644 index 00000000..ca978774 --- /dev/null +++ b/docs/pt-BR/commands/setup-pm.md @@ -0,0 +1,80 @@ +--- +description: Configure seu package manager preferido (npm/pnpm/yarn/bun) +disable-model-invocation: true +--- + +# Configuração de Package Manager + +Configure seu package manager preferido para este projeto ou globalmente. + +## Uso + +```bash +# Detect current package manager +node scripts/setup-package-manager.js --detect + +# Set global preference +node scripts/setup-package-manager.js --global pnpm + +# Set project preference +node scripts/setup-package-manager.js --project bun + +# List available package managers +node scripts/setup-package-manager.js --list +``` + +## Prioridade de Detecção + +Ao determinar qual package manager usar, esta ordem é verificada: + +1. **Environment variable**: `CLAUDE_PACKAGE_MANAGER` +2. **Project config**: `.claude/package-manager.json` +3. **package.json**: `packageManager` field +4. **Lock file**: Presence of package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb +5. **Global config**: `~/.claude/package-manager.json` +6. **Fallback**: First available package manager (pnpm > bun > yarn > npm) + +## Arquivos de Configuração + +### Configuração Global +```json +// ~/.claude/package-manager.json +{ + "packageManager": "pnpm" +} +``` + +### Configuração do Projeto +```json +// .claude/package-manager.json +{ + "packageManager": "bun" +} +``` + +### package.json +```json +{ + "packageManager": "pnpm@8.6.0" +} +``` + +## Variável de Ambiente + +Defina `CLAUDE_PACKAGE_MANAGER` para sobrescrever todos os outros métodos de detecção: + +```bash +# Windows (PowerShell) +$env:CLAUDE_PACKAGE_MANAGER = "pnpm" + +# macOS/Linux +export CLAUDE_PACKAGE_MANAGER=pnpm +``` + +## Rodar a Detecção + +Para ver os resultados atuais da detecção de package manager, rode: + +```bash +node scripts/setup-package-manager.js --detect +``` diff --git a/docs/pt-BR/commands/tdd.md b/docs/pt-BR/commands/tdd.md new file mode 100644 index 00000000..341b98cf --- /dev/null +++ b/docs/pt-BR/commands/tdd.md @@ -0,0 +1,328 @@ +--- +description: Impõe fluxo de desenvolvimento orientado a testes. Estruture interfaces, gere testes PRIMEIRO e depois implemente código mínimo para passar. Garanta cobertura de 80%+. +--- + +# Comando TDD + +Este comando invoca o agente **tdd-guide** para impor a metodologia de desenvolvimento orientado a testes. + +## O Que Este Comando Faz + +1. **Estruturar Interfaces** - Definir tipos/interfaces primeiro +2. **Gerar Testes Primeiro** - Escrever testes que falham (RED) +3. **Implementar Código Mínimo** - Escrever apenas o suficiente para passar (GREEN) +4. **Refatorar** - Melhorar o código mantendo testes verdes (REFACTOR) +5. **Verificar Cobertura** - Garantir cobertura de testes de 80%+ + +## Quando Usar + +Use `/tdd` quando: +- Implementar novas features +- Adicionar novas funções/componentes +- Corrigir bugs (escrever primeiro teste que reproduz o bug) +- Refatorar código existente +- Construir lógica de negócio crítica + +## Como Funciona + +O agente tdd-guide vai: + +1. **Definir interfaces** para entradas/saídas +2. **Escrever testes que vão FALHAR** (porque o código ainda não existe) +3. **Rodar testes** e verificar que falham pelo motivo correto +4. **Escrever implementação mínima** para fazer testes passarem +5. **Rodar testes** e verificar que passam +6. **Refatorar** código mantendo testes verdes +7. **Checar cobertura** e adicionar mais testes se estiver abaixo de 80% + +## Ciclo TDD + +``` +RED → GREEN → REFACTOR → REPEAT + +RED: Write a failing test +GREEN: Write minimal code to pass +REFACTOR: Improve code, keep tests passing +REPEAT: Next feature/scenario +``` + +## Exemplo de Uso + +``` +User: /tdd I need a function to calculate market liquidity score + +Agent (tdd-guide): +# TDD Session: Market Liquidity Score Calculator + +## Step 1: Define Interface (SCAFFOLD) + +```typescript +// lib/liquidity.ts +export interface MarketData { + totalVolume: number + bidAskSpread: number + activeTraders: number + lastTradeTime: Date +} + +export function calculateLiquidityScore(market: MarketData): number { + // TODO: Implementation + throw new Error('Not implemented') +} +``` + +## Step 2: Write Failing Test (RED) + +```typescript +// lib/liquidity.test.ts +import { calculateLiquidityScore } from './liquidity' + +describe('calculateLiquidityScore', () => { + it('should return high score for liquid market', () => { + const market = { + totalVolume: 100000, + bidAskSpread: 0.01, + activeTraders: 500, + lastTradeTime: new Date() + } + + const score = calculateLiquidityScore(market) + + expect(score).toBeGreaterThan(80) + expect(score).toBeLessThanOrEqual(100) + }) + + it('should return low score for illiquid market', () => { + const market = { + totalVolume: 100, + bidAskSpread: 0.5, + activeTraders: 2, + lastTradeTime: new Date(Date.now() - 86400000) // 1 day ago + } + + const score = calculateLiquidityScore(market) + + expect(score).toBeLessThan(30) + expect(score).toBeGreaterThanOrEqual(0) + }) + + it('should handle edge case: zero volume', () => { + const market = { + totalVolume: 0, + bidAskSpread: 0, + activeTraders: 0, + lastTradeTime: new Date() + } + + const score = calculateLiquidityScore(market) + + expect(score).toBe(0) + }) +}) +``` + +## Step 3: Run Tests - Verify FAIL + +```bash +npm test lib/liquidity.test.ts + +FAIL lib/liquidity.test.ts + ✕ should return high score for liquid market (2 ms) + Error: Not implemented + +1 test failed, 0 passed +``` + +✅ Tests fail as expected. Ready to implement. + +## Step 4: Implement Minimal Code (GREEN) + +```typescript +// lib/liquidity.ts +export function calculateLiquidityScore(market: MarketData): number { + // Handle zero volume edge case + if (market.totalVolume === 0) { + return 0 + } + + // Calculate component scores (0-100 scale) + const volumeScore = Math.min(market.totalVolume / 1000, 100) + const spreadScore = Math.max(100 - (market.bidAskSpread * 1000), 0) + const traderScore = Math.min(market.activeTraders / 10, 100) + + // Recent activity bonus + const hoursSinceLastTrade = (Date.now() - market.lastTradeTime.getTime()) / (1000 * 60 * 60) + const recencyScore = Math.max(100 - (hoursSinceLastTrade * 10), 0) + + // Weighted average + const score = ( + volumeScore * 0.4 + + spreadScore * 0.3 + + traderScore * 0.2 + + recencyScore * 0.1 + ) + + return Math.min(Math.max(score, 0), 100) // Clamp to 0-100 +} +``` + +## Step 5: Run Tests - Verify PASS + +```bash +npm test lib/liquidity.test.ts + +PASS lib/liquidity.test.ts + ✓ should return high score for liquid market (3 ms) + ✓ should return low score for illiquid market (2 ms) + ✓ should handle edge case: zero volume (1 ms) + +3 tests passed +``` + +✅ All tests passing! + +## Step 6: Refactor (IMPROVE) + +```typescript +// lib/liquidity.ts - Refactored with constants and better readability +const WEIGHTS = { + VOLUME: 0.4, + SPREAD: 0.3, + TRADERS: 0.2, + RECENCY: 0.1, +} as const + +const SCALE_FACTORS = { + VOLUME: 1000, + SPREAD: 1000, + TRADERS: 10, + RECENCY_PENALTY: 10, +} as const + +function clamp(value: number, min: number, max: number): number { + return Math.min(Math.max(value, min), max) +} + +export function calculateLiquidityScore(market: MarketData): number { + if (market.totalVolume === 0) return 0 + + const volumeScore = Math.min(market.totalVolume / SCALE_FACTORS.VOLUME, 100) + const spreadScore = clamp(100 - (market.bidAskSpread * SCALE_FACTORS.SPREAD), 0, 100) + const traderScore = Math.min(market.activeTraders / SCALE_FACTORS.TRADERS, 100) + + const hoursSinceLastTrade = (Date.now() - market.lastTradeTime.getTime()) / (1000 * 60 * 60) + const recencyScore = clamp(100 - (hoursSinceLastTrade * SCALE_FACTORS.RECENCY_PENALTY), 0, 100) + + const weightedScore = + volumeScore * WEIGHTS.VOLUME + + spreadScore * WEIGHTS.SPREAD + + traderScore * WEIGHTS.TRADERS + + recencyScore * WEIGHTS.RECENCY + + return clamp(weightedScore, 0, 100) +} +``` + +## Step 7: Verify Tests Still Pass + +```bash +npm test lib/liquidity.test.ts + +PASS lib/liquidity.test.ts + ✓ should return high score for liquid market (3 ms) + ✓ should return low score for illiquid market (2 ms) + ✓ should handle edge case: zero volume (1 ms) + +3 tests passed +``` + +✅ Refactoring complete, tests still passing! + +## Step 8: Check Coverage + +```bash +npm test -- --coverage lib/liquidity.test.ts + +File | % Stmts | % Branch | % Funcs | % Lines +---------------|---------|----------|---------|-------- +liquidity.ts | 100 | 100 | 100 | 100 + +Coverage: 100% ✅ (Target: 80%) +``` + +✅ TDD session complete! +``` + +## Boas Práticas de TDD + +**DO:** +- ✅ Escreva o teste PRIMEIRO, antes da implementação +- ✅ Rode testes e confirme que FALHAM antes de implementar +- ✅ Escreva código mínimo para fazer passar +- ✅ Refatore só depois que os testes estiverem verdes +- ✅ Adicione casos de borda e cenários de erro +- ✅ Mire 80%+ de cobertura (100% para código crítico) + +**DON'T:** +- ❌ Escrever implementação antes de testes +- ❌ Pular execução de testes após cada mudança +- ❌ Escrever código demais de uma vez +- ❌ Ignorar testes falhando +- ❌ Testar detalhes de implementação (teste comportamento) +- ❌ Fazer mock de tudo (prefira testes de integração) + +## Tipos de Teste a Incluir + +**Testes Unitários** (nível de função): +- Cenários happy path +- Casos de borda (vazio, null, valores máximos) +- Condições de erro +- Valores de fronteira + +**Testes de Integração** (nível de componente): +- Endpoints de API +- Operações de banco de dados +- Chamadas a serviços externos +- Componentes React com hooks + +**Testes E2E** (use comando `/e2e`): +- Fluxos críticos de usuário +- Processos multi-etapa +- Integração full stack + +## Requisitos de Cobertura + +- **Mínimo de 80%** para todo o código +- **100% obrigatório** para: + - Cálculos financeiros + - Lógica de autenticação + - Código crítico de segurança + - Lógica de negócio central + +## Notas Importantes + +**MANDATÓRIO**: Os testes devem ser escritos ANTES da implementação. O ciclo TDD é: + +1. **RED** - Escrever teste que falha +2. **GREEN** - Implementar para passar +3. **REFACTOR** - Melhorar código + +Nunca pule a fase RED. Nunca escreva código antes dos testes. + +## Integração com Outros Comandos + +- Use `/plan` primeiro para entender o que construir +- Use `/tdd` para implementar com testes +- Use `/build-fix` se ocorrerem erros de build +- Use `/code-review` para revisar implementação +- Use `/test-coverage` para verificar cobertura + +## Agentes Relacionados + +Este comando invoca o agente `tdd-guide` fornecido pelo ECC. + +A skill relacionada `tdd-workflow` também é distribuída com o ECC. + +Para instalações manuais, os arquivos fonte ficam em: +- `agents/tdd-guide.md` +- `skills/tdd-workflow/SKILL.md` diff --git a/docs/pt-BR/commands/test-coverage.md b/docs/pt-BR/commands/test-coverage.md new file mode 100644 index 00000000..e1c67d6d --- /dev/null +++ b/docs/pt-BR/commands/test-coverage.md @@ -0,0 +1,69 @@ +# Cobertura de Testes + +Analise cobertura de testes, identifique lacunas e gere testes faltantes para alcançar cobertura de 80%+. + +## Passo 1: Detectar Framework de Teste + +| Indicator | Coverage Command | +|-----------|-----------------| +| `jest.config.*` or `package.json` jest | `npx jest --coverage --coverageReporters=json-summary` | +| `vitest.config.*` | `npx vitest run --coverage` | +| `pytest.ini` / `pyproject.toml` pytest | `pytest --cov=src --cov-report=json` | +| `Cargo.toml` | `cargo llvm-cov --json` | +| `pom.xml` with JaCoCo | `mvn test jacoco:report` | +| `go.mod` | `go test -coverprofile=coverage.out ./...` | + +## Passo 2: Analisar Relatório de Cobertura + +1. Rode o comando de cobertura +2. Parseie a saída (resumo em JSON ou saída de terminal) +3. Liste arquivos **abaixo de 80% de cobertura**, ordenados do pior para o melhor +4. Para cada arquivo abaixo da meta, identifique: + - Funções ou métodos sem teste + - Cobertura de branch faltante (if/else, switch, caminhos de erro) + - Código morto que infla o denominador + +## Passo 3: Gerar Testes Faltantes + +Para cada arquivo abaixo da meta, gere testes seguindo esta prioridade: + +1. **Happy path** — Funcionalidade principal com entradas válidas +2. **Tratamento de erro** — Entradas inválidas, dados ausentes, falhas de rede +3. **Casos de borda** — Arrays vazios, null/undefined, valores de fronteira (0, -1, MAX_INT) +4. **Cobertura de branch** — Cada if/else, caso de switch, ternário + +### Regras para Geração de Testes + +- Coloque testes adjacentes ao código-fonte: `foo.ts` → `foo.test.ts` (ou convenção do projeto) +- Use padrões de teste existentes do projeto (estilo de import, biblioteca de asserção, abordagem de mocking) +- Faça mock de dependências externas (banco, APIs, sistema de arquivos) +- Cada teste deve ser independente — sem estado mutável compartilhado entre testes +- Nomeie testes de forma descritiva: `test_create_user_with_duplicate_email_returns_409` + +## Passo 4: Verificar + +1. Rode a suíte completa de testes — todos os testes devem passar +2. Rode cobertura novamente — confirme a melhoria +3. Se ainda estiver abaixo de 80%, repita o Passo 3 para as lacunas restantes + +## Passo 5: Reportar + +Mostre comparação antes/depois: + +``` +Coverage Report +────────────────────────────── +File Before After +src/services/auth.ts 45% 88% +src/utils/validation.ts 32% 82% +────────────────────────────── +Overall: 67% 84% ✅ +``` + +## Áreas de Foco + +- Funções com branching complexo (alta complexidade ciclomática) +- Error handlers e blocos catch +- Funções utilitárias usadas em todo o codebase +- Handlers de endpoint de API (fluxo request → response) +- Casos de borda: null, undefined, string vazia, array vazio, zero, números negativos diff --git a/docs/pt-BR/commands/update-codemaps.md b/docs/pt-BR/commands/update-codemaps.md new file mode 100644 index 00000000..8a5cb90f --- /dev/null +++ b/docs/pt-BR/commands/update-codemaps.md @@ -0,0 +1,72 @@ +# Atualizar Codemaps + +Analise a estrutura do codebase e gere documentação arquitetural enxuta em tokens. + +## Passo 1: Escanear Estrutura do Projeto + +1. Identifique o tipo de projeto (monorepo, app única, library, microservice) +2. Encontre todos os diretórios de código-fonte (src/, lib/, app/, packages/) +3. Mapeie entry points (main.ts, index.ts, app.py, main.go, etc.) + +## Passo 2: Gerar Codemaps + +Crie ou atualize codemaps em `docs/CODEMAPS/` (ou `.reports/codemaps/`): + +| File | Contents | +|------|----------| +| `architecture.md` | High-level system diagram, service boundaries, data flow | +| `backend.md` | API routes, middleware chain, service → repository mapping | +| `frontend.md` | Page tree, component hierarchy, state management flow | +| `data.md` | Database tables, relationships, migration history | +| `dependencies.md` | External services, third-party integrations, shared libraries | + +### Formato de Codemap + +Cada codemap deve ser enxuto em tokens — otimizado para consumo de contexto por IA: + +```markdown +# Backend Architecture + +## Routes +POST /api/users → UserController.create → UserService.create → UserRepo.insert +GET /api/users/:id → UserController.get → UserService.findById → UserRepo.findById + +## Key Files +src/services/user.ts (business logic, 120 lines) +src/repos/user.ts (database access, 80 lines) + +## Dependencies +- PostgreSQL (primary data store) +- Redis (session cache, rate limiting) +- Stripe (payment processing) +``` + +## Passo 3: Detecção de Diff + +1. Se codemaps anteriores existirem, calcule a porcentagem de diff +2. Se mudanças > 30%, mostre o diff e solicite aprovação do usuário antes de sobrescrever +3. Se mudanças <= 30%, atualize in-place + +## Passo 4: Adicionar Metadados + +Adicione um cabeçalho de freshness em cada codemap: + +```markdown + +``` + +## Passo 5: Salvar Relatório de Análise + +Escreva um resumo em `.reports/codemap-diff.txt`: +- Arquivos adicionados/removidos/modificados desde o último scan +- Novas dependências detectadas +- Mudanças de arquitetura (novas rotas, novos serviços etc.) +- Alertas de obsolescência para docs sem atualização em 90+ dias + +## Dicas + +- Foque em **estrutura de alto nível**, não em detalhes de implementação +- Prefira **caminhos de arquivo e assinaturas de função** em vez de blocos de código completos +- Mantenha cada codemap abaixo de **1000 tokens** para carregamento eficiente de contexto +- Use diagramas ASCII para fluxo de dados em vez de descrições verbosas +- Rode após grandes adições de feature ou sessões de refatoração diff --git a/docs/pt-BR/commands/update-docs.md b/docs/pt-BR/commands/update-docs.md new file mode 100644 index 00000000..9563299c --- /dev/null +++ b/docs/pt-BR/commands/update-docs.md @@ -0,0 +1,84 @@ +# Atualizar Documentação + +Sincronize a documentação com o codebase, gerando a partir de arquivos fonte da verdade. + +## Passo 1: Identificar Fontes da Verdade + +| Source | Generates | +|--------|-----------| +| `package.json` scripts | Available commands reference | +| `.env.example` | Environment variable documentation | +| `openapi.yaml` / route files | API endpoint reference | +| Source code exports | Public API documentation | +| `Dockerfile` / `docker-compose.yml` | Infrastructure setup docs | + +## Passo 2: Gerar Referência de Scripts + +1. Leia `package.json` (ou `Makefile`, `Cargo.toml`, `pyproject.toml`) +2. Extraia todos os scripts/comandos com suas descrições +3. Gere uma tabela de referência: + +```markdown +| Command | Description | +|---------|-------------| +| `npm run dev` | Start development server with hot reload | +| `npm run build` | Production build with type checking | +| `npm test` | Run test suite with coverage | +``` + +## Passo 3: Gerar Documentação de Ambiente + +1. Leia `.env.example` (ou `.env.template`, `.env.sample`) +2. Extraia todas as variáveis e seus propósitos +3. Categorize como required vs optional +4. Documente formato esperado e valores válidos + +```markdown +| Variable | Required | Description | Example | +|----------|----------|-------------|---------| +| `DATABASE_URL` | Yes | PostgreSQL connection string | `postgres://user:pass@host:5432/db` | +| `LOG_LEVEL` | No | Logging verbosity (default: info) | `debug`, `info`, `warn`, `error` | +``` + +## Passo 4: Atualizar Guia de Contribuição + +Gere ou atualize `docs/CONTRIBUTING.md` com: +- Setup do ambiente de desenvolvimento (pré-requisitos, passos de instalação) +- Scripts disponíveis e seus propósitos +- Procedimentos de teste (como rodar, como escrever novos testes) +- Enforcement de estilo de código (linter, formatter, hooks pre-commit) +- Checklist de submissão de PR + +## Passo 5: Atualizar Runbook + +Gere ou atualize `docs/RUNBOOK.md` com: +- Procedimentos de deploy (passo a passo) +- Endpoints de health check e monitoramento +- Problemas comuns e suas correções +- Procedimentos de rollback +- Caminhos de alerta e escalonamento + +## Passo 6: Checagem de Obsolescência + +1. Encontre arquivos de documentação sem modificação há 90+ dias +2. Cruze com mudanças recentes no código-fonte +3. Sinalize docs potencialmente desatualizadas para revisão manual + +## Passo 7: Mostrar Resumo + +``` +Documentation Update +────────────────────────────── +Updated: docs/CONTRIBUTING.md (scripts table) +Updated: docs/ENV.md (3 new variables) +Flagged: docs/DEPLOY.md (142 days stale) +Skipped: docs/API.md (no changes detected) +────────────────────────────── +``` + +## Regras + +- **Fonte única da verdade**: Sempre gere a partir do código, nunca edite manualmente seções geradas +- **Preserve seções manuais**: Atualize apenas seções geradas; mantenha prosa escrita manualmente intacta +- **Marque conteúdo gerado**: Use marcadores `` ao redor das seções geradas +- **Não crie docs sem solicitação**: Só crie novos arquivos de docs se o comando solicitar explicitamente diff --git a/docs/pt-BR/commands/verify.md b/docs/pt-BR/commands/verify.md new file mode 100644 index 00000000..5916a529 --- /dev/null +++ b/docs/pt-BR/commands/verify.md @@ -0,0 +1,59 @@ +# Comando Verification + +Rode verificação abrangente no estado atual do codebase. + +## Instruções + +Execute a verificação nesta ordem exata: + +1. **Build Check** + - Rode o comando de build deste projeto + - Se falhar, reporte erros e PARE + +2. **Type Check** + - Rode o TypeScript/type checker + - Reporte todos os erros com file:line + +3. **Lint Check** + - Rode o linter + - Reporte warnings e errors + +4. **Test Suite** + - Rode todos os testes + - Reporte contagem de pass/fail + - Reporte percentual de cobertura + +5. **Console.log Audit** + - Procure por console.log em arquivos de código-fonte + - Reporte localizações + +6. **Git Status** + - Mostre mudanças não commitadas + - Mostre arquivos modificados desde o último commit + +## Saída + +Produza um relatório conciso de verificação: + +``` +VERIFICATION: [PASS/FAIL] + +Build: [OK/FAIL] +Types: [OK/X errors] +Lint: [OK/X issues] +Tests: [X/Y passed, Z% coverage] +Secrets: [OK/X found] +Logs: [OK/X console.logs] + +Ready for PR: [YES/NO] +``` + +Se houver problemas críticos, liste-os com sugestões de correção. + +## Argumentos + +$ARGUMENTS podem ser: +- `quick` - Apenas build + types +- `full` - Todas as checagens (padrão) +- `pre-commit` - Checagens relevantes para commits +- `pre-pr` - Checagens completas mais security scan