@eltonssouza/development-utility-kit 0.10.0

package/.claude/skills/pair-debug/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: pair-debug
+description: "Pair-debug loop. Use when a bug is reported and the cause is not immediately obvious — typical for runtime errors, intermittent failures, integration mismatches, mysterious 4xx/5xx, missing data in DB after a write, console errors in the browser, race conditions, etc. Forces a disciplined cycle: state the symptom, formulate a hypothesis with a confidence level, choose ONE cheap probe to confirm/deny it (curl, log line, breakpoint, SELECT, browser console via Chrome MCP), gather the evidence, accept or reject the hypothesis, repeat. Bans 'tentar e ver' — every change must follow a tested hypothesis. DO NOT use for obvious bugs with obvious fixes (typo, missing import, syntax error — just fix it), for bugs that already have a solid pre-existing hypothesis, for features that were not yet implemented (use run-sprint), for proactive refactor (not a bug), or for performance tuning without a reported symptom (use dba or tech-lead). PT triggers: 'vamos debugar', 'pair debug', 'investiga esse bug', 'debug pair', 'achar a causa', 'investigar a falha', 'qual a causa raiz', 'descobrir por que', 'estranho, não funciona'."
+tools: Read, Glob, Grep, Bash(curl:*), Bash(grep:*), Bash(tail:*), Bash(head:*), Bash(jq:*), Bash(psql:*), Bash(docker logs:*), Bash(git log:*), Bash(git diff:*), Bash(git blame:*)
+model: sonnet
+---
+
+# Pair-debug — disciplined hypothesis-driven debugging
+
+> **Subagent dispatch (mandatory).** Debug loop runs in the calling session. For writing the confirming test (§3.5), dispatch to `qa-engineer` via Task tool. The disciplined loop below applies regardless.
+
+Your mission, in one line: **find the root cause of a bug by stating hypotheses with confidence, probing one at a time with cheap evidence, and refusing to fix anything until the cause is confirmed.**
+
+Principle: *"'tentar e ver' é debug sem disciplina — cada mudança no código sem hipótese testada vira ruído. Hipótese + probe + evidência + verdict = sinal."*
+
+---
+
+## 1. When you trigger
+
+- "vamos debugar X", "pair debug", "investiga esse bug", "achar a causa raiz", "por que isso não funciona"
+- Specialist está travado depois de 2+ tentativas
+- Bug reportado pelo `api-integration-test` ou pelo Chrome MCP console
+- Falha intermitente (passa 1x, falha outras vezes — sinal de race ou estado sujo)
+- 4xx/5xx misterioso, exception sem stack útil, dados sumindo do banco, console.error no front
+
+## 2. When you do NOT trigger
+
+- **Erro óbvio com fix óbvio** (typo, import faltando, sintaxe quebrada). Apenas conserta — debug ritual é overkill.
+- **Bug já tem hipótese sólida**: vai direto pro fix com confiança alta.
+- **Feature nova que ainda não foi implementada** — não é bug, é falta. Vá pro `run-sprint`.
+- **Falha de teste no `auto-test-guard`** se o erro for de assert claro — `auto-test-guard` já roteia pro specialist.
+
+## 3. The loop (5 fases, repete até convergir)
+
+### Stage 0 — Stack pre-resolution (per ADR-026 Layer 1)
+
+> **MANDATORY before §3.1 Symptom framing.** Resolves the project's stack so the debug loop chooses probes that make sense for the stack (e.g. `psql` for Postgres, `redis-cli` for Redis, `docker logs` for containerized services) and so any dispatch to `qa-engineer` for the confirming test (§3.5) inherits the right knowledge pack.
+
+Steps:
+
+a) Invoke `stack-resolver` via Task tool:
+
+```
+Task(
+  subagent_type: "stack-resolver",
+  description: "Resolve stack for project at CWD",
+  prompt: "resolve stack for project at CWD"
+)
+```
+
+b) Parse the first line of `stack-resolver` output:
+
+- **`[STACK: <lang>/<framework>-<major> | PACK: loaded]`** — extract the full `STACK CONTEXT` block. Store as `STACK_CONTEXT_BLOCK` for use in §3.5 dispatch and as guidance for probe selection in §3.3.
+- **`[STACK: <lang>/<framework>-<major> | PACK: none]`** — pack missing. Dispatch `create-stack-pack` skill conversationally; once the pack is created, repeat Stage 0a.
+
+c) Use `STACK_CONTEXT_BLOCK` to:
+- inform probe selection in §3.3 (which CLI tools, which build commands, which log format are idiomatic for this stack);
+- prefix every Task dispatch to `qa-engineer` / `backend-developer` / `frontend-developer` during §3.5 fix application.
+
+If `stack-resolver` cannot determine the stack, do NOT abort the debug — log a warning and proceed with generic probes:
+
+```
+Stack indeterminada (CLAUDE.md sem `Primary stack`). Seguindo com probes genéricas; considere preencher Project Identity para futuras sessões.
+```
+
+### 3.1. Estado o sintoma — uma frase, sem interpretação
+
+> "POST /api/v1/products retorna 500. Response body: ProblemDetail com detail='null pointer'."
+> "Login funciona uma vez; segundo login no mesmo browser fica em loop de redirect."
+> "Migration V12 roda local mas falha no CI com 'relation product_category does not exist'."
+
+Regras pro sintoma:
+- **Fato observado**, não suposição.
+- **1 sintoma por loop**. Se há 2, escolha o mais reproduzível primeiro.
+- **Reprodutível?** Se não, primeira hipótese tem que ser "como reproduzir isso de forma confiável".
+
+### 3.2. Formule hipóteses com confidence
+
+Liste 2-5 hipóteses do tipo "o sintoma acontece porque X". Cada uma com:
+
+| Campo | Conteúdo |
+|---|---|
+| `id` | H1, H2, ... |
+| `claim` | "X causa o sintoma porque Y" |
+| `confidence` | low / medium / high |
+| `evidence_required` | qual probe específica confirma ou descarta |
+| `cost_to_probe` | trivial (1 comando) / cheap (5min) / medium (30min) / expensive (>1h) |
+
+Exemplo:
+
+```
+H1: NullPointerException no controller porque o produto não tem categoria associada
+    confidence: medium
+    evidence_required: curl com produto sem categoria + log do stack trace na linha exata
+    cost_to_probe: trivial
+
+H2: Bean Validation @NotNull não está sendo aplicada porque o controller ignora @Valid
+    confidence: low
+    evidence_required: grep do controller — tem @Valid no parâmetro?
+    cost_to_probe: trivial
+
+H3: O mapper DTO -> entity está retornando null em caso de campo opcional
+    confidence: medium
+    evidence_required: teste unitário do mapper com input parcial
+    cost_to_probe: cheap (~5min)
+```
+
+**Regra inviolável**: nunca ataque a hipótese com `confidence: high` direto — pode estar enviesado. Probe a com `confidence: medium` primeiro pra calibrar.
+
+### 3.3. Escolha UMA probe — a mais barata por confidence
+
+Trade-off:
+- **Trivial probe** → tente primeiro mesmo se confidence é low; o custo de descartar é zero.
+- **Cheap probe** → se confidence ≥ medium.
+- **Medium/Expensive** → só se confidence é high E nenhuma probe mais barata atinge.
+
+**Stack-aware probe selection**: o `STACK_CONTEXT_BLOCK` carregado em Stage 0 indica quais probes são idiomáticas para a stack do projeto:
+- Postgres → `psql`, `EXPLAIN`, `pg_stat_statements`.
+- MongoDB → `mongosh`, `db.collection.find().explain()`.
+- Redis → `redis-cli`, `MONITOR`.
+- Java/Spring Boot → `./mvnw test`, JaCoCo report, Actuator endpoints.
+- Angular → Chrome MCP console, `ng test --watch=false`, Lighthouse.
+- React Native → `npx expo start`, Metro logs, Flipper.
+
+Use o pack como referência; não invente comandos que não existem na stack do projeto.
+
+Tipos de probe (com a tool relevante):
+
+| Probe | Tool | Quando |
+|---|---|---|
+| Curl no endpoint suspeito | `Bash(curl:*)` | Reproduzir 4xx/5xx, ver response body completo |
+| Tail de log estruturado | `Bash(tail:*)`, `Bash(grep:*)` | Capturar stack trace em produção/staging |
+| `git log` no arquivo suspeito | `Bash(git log:*)`, `Bash(git blame:*)` | Quando o bug apareceu, quem mudou |
+| `git diff` entre tag boa e atual | `Bash(git diff:*)` | Bisect manual quando "antes funcionava" |
+| `psql` SELECT no banco | `Bash(psql:*)` | Estado dos dados, FK órfã, índice faltando |
+| `docker logs` | `Bash(docker logs:*)` | Container errors, restart loops, OOM |
+| Browser console via Chrome MCP | (no calling session) | Console.error, network failures no front |
+| Grep do código | `Grep`, `Glob` | Buscar uso real do método, decorators ausentes |
+| Teste unitário focado | `Write` + `Bash` | Isolar uma função do contexto |
+
+### 3.4. Execute a probe e classifique o resultado
+
+A evidência confirma ou rejeita a hipótese de forma binária:
+
+- **Confirma**: a probe mostrou exatamente o que H_i previa. Hipótese ACEITA. Vá pro fix (§3.5).
+- **Rejeita**: a probe mostrou o oposto. Hipótese REJEITADA. Riscar da lista, voltar pro §3.2 com as restantes.
+- **Inconclusiva**: a probe não capturou o que precisava. Escolha probe mais específica. Não pule pra outra hipótese ainda — o sinal está vindo, só não é claro.
+
+**Regra**: SE 3 probes consecutivas retornarem inconclusivo, RECUE pro §3.1 — o sintoma pode estar mal formulado.
+
+### 3.5. Quando uma hipótese é confirmada — fix mínimo
+
+- Aplique o **menor fix possível** que ataca exatamente a causa.
+- **NUNCA** "aproveite e refatore" enquanto debuga. Refactor é tarefa separada — confunde análise.
+- **NUNCA** comente, delete ou disable o teste que está pegando o bug (`block-test-deletion.sh` impede isso no hook).
+- Adicione **um teste novo** que reproduz o bug + valida o fix. Se você só consertou e seguiu, o bug volta.
+- Reruna a probe original — agora ela deve mostrar comportamento correto.
+
+**Dispatch para `qa-engineer` (escrever o teste de confirmação) — sempre com `STACK_CONTEXT_BLOCK` prefixado:**
+
+```
+Task(
+  subagent_type: "qa-engineer",
+  description: "Write confirming test for bug <slug>",
+  prompt: """<STACK_CONTEXT_BLOCK from Stage 0>
+
+caller: pair-debug
+bug_symptom: <frase do §3.1>
+confirmed_hypothesis: <claim de H_i confirmada em §3.4>
+fix_location: <arquivo:linhas do §3.5>
+
+Write a single failing test that reproduces the bug verbatim (Given the same input that triggered the symptom, When the operation runs, Then the expected correct behavior is asserted). Test must fail on the pre-fix code and pass on the post-fix code. Use the testing tools and naming conventions described in the STACK CONTEXT above."""
+)
+```
+
+Para dispatch a `backend-developer` / `frontend-developer` aplicando o fix mínimo (quando a complexidade do patch justifica delegação), prefixe da mesma forma com `STACK_CONTEXT_BLOCK`.
+
+### 3.6. Loop fechado — relate
+
+Após o ciclo, emita o relatório (formato no §6).
+
+## 4. Anti-patterns proibidos (NUNCA)
+
+1. **"Vou tentar mudar X e ver se funciona"** — change blind. Sem hipótese, não há aprendizado. Recusa.
+2. **Comentar/deletar/disable o teste vermelho** — bypass do gate, registrado no hook `block-test-deletion.sh`.
+3. **Adicionar log e fazer commit** sem entender. Logs sem hipótese viram lixo. Coloca log → reproduce → analisa → REMOVE o log antes do commit OU justifica como observability permanente.
+4. **`catch (Exception e) {}`** ou `@SuppressWarnings` pra fazer compilar/parar de quebrar. Esconder o sintoma piora o débito.
+5. **Pular pra "deve ser não-determinismo"** sem 3+ rodadas que provam. Não-determinismo é uma das hipóteses, não uma carta de saída.
+6. **Mudar 5 coisas e ver qual funcionou** — diff irreversível. Mude uma coisa por vez.
+7. **Pular Stage 0** — sem stack resolvida, probes viram chute e dispatches a `qa-engineer` saem sem pack. Bloqueado.
+
+## 5. Interface com outras skills/agents
+
+| Skill / Agent | Quando chamar |
+|---|---|
+| `stack-resolver` | Stage 0 (sempre, antes de §3.1). Resolve stack e carrega knowledge pack (ADR-026 Layer 1). |
+| `create-stack-pack` | Quando Stage 0 retorna `PACK: none`. Gera o pack faltante conversacionalmente. |
+| `qa-engineer` | Pra escrever o teste que reproduz o bug confirmado (§3.5). Dispatch SEMPRE com `STACK_CONTEXT_BLOCK` prefixado. |
+| `backend-developer` / `frontend-developer` | Implementar o fix mínimo após hipótese confirmada. Dispatch SEMPRE com `STACK_CONTEXT_BLOCK` prefixado. |
+| `api-integration-test` | Curl + Chrome MCP em ambiente real — se a probe precisa do front + back rodando |
+| `dba` | Quando a hipótese envolve schema/index/query plan no PostgreSQL |
+| `security-engineer` | Se o bug é vulnerabilidade (XSS, SQL injection, IDOR) — VETO TÉCNICO pode disparar |
+| `tech-lead` | Se 5+ hipóteses falharam OU o fix vai mudar contrato público — escala como exceção |
+
+## 6. Output report (sempre emite)
+
+```markdown
+## Pair-debug — <título do bug>
+
+### Stack resolvida (Stage 0)
+<linha [STACK: ... | PACK: ...] retornada pelo stack-resolver>
+
+### Sintoma
+<frase única do §3.1>
+
+### Hipóteses testadas
+| ID | Claim | Confidence | Probe | Verdict |
+|----|-------|------------|-------|---------|
+| H1 | ... | medium | curl + log | rejeitada (response 200 ao invés de 500) |
+| H2 | ... | low | grep do controller | rejeitada (tem @Valid sim) |
+| H3 | ... | medium | unit test do mapper | **CONFIRMADA** (mapper retornou null) |
+
+### Causa raiz
+<frase única explicando o que estava errado>
+
+### Fix mínimo aplicado
+- Arquivo: `path/to/file.java`
+- Linhas: `42-45`
+- Antes: <diff -A>
+- Depois: <diff -B>
+
+### Teste novo que cobre
+- Arquivo: `path/to/FileTest.java`
+- Método: `shouldXxxWhenYyy`
+- Reproduz o bug original; passa após o fix.
+
+### Status
+- ✓ Probe original (§3.1) agora retorna comportamento correto.
+- ✓ Suite verde após o fix (rode `auto-test-guard`).
+- ✓ Cause documented; closing the loop.
+
+### Tempo gasto
+- <minutos do início do loop até confirmar causa raiz>
+```
+
+## 7. Inviolable rules
+
+1. **Stage 0 antes de §3.1.** Sem stack resolvida via `stack-resolver`, não começa o loop (per ADR-026 Layer 1).
+2. **Hipótese antes de probe, probe antes de fix.** Nunca fure essa ordem.
+3. **Uma mudança por loop.** Múltiplas mudanças simultâneas tornam impossível atribuir causa.
+4. **Cada bug deixa um teste pra trás.** Se você confirmou e fix sem teste, o bug volta — você só comprou tempo.
+5. **Comentar/disable teste = NON-NEGOTIABLE bloqueado.** Hook `block-test-deletion.sh` impede no PreToolUse; redundância proposital aqui.
+6. **Probe inconclusiva 3x = volta ao §3.1.** Sintoma está mal formulado.
+7. **Refactor não acontece durante debug.** Lista débito, faz depois.
+8. **Logs temporários SAEM antes do commit** OU viram observability formal com justificativa.
+9. **Dispatch a qa-engineer / developer SEMPRE com STACK_CONTEXT_BLOCK prefixado.** Sem pack inline, o agent receptor pode emitir código fora da stack do projeto.
+
+## 8. Example interaction
+
+**Bug reportado** (api-integration-test): "POST /api/v1/orders retorna 500 quando o cliente tem CPF terminado em zero. Erro: `ProblemDetail{detail='invalid CPF format'}`."
+
+**Loop**:
+
+Stage 0: `stack-resolver` retornou `[STACK: java/spring-boot-4 | PACK: loaded]`. Pack `.claude/stacks/java/spring-boot-4.md` carregado (Bean Validation jakarta, JUnit 5, Maven build).
+
+§3.1 Sintoma: "Endpoint retorna 500 com 'invalid CPF format' quando CPF termina em zero."
+
+§3.2 Hipóteses:
+- H1: validator de CPF trata zero à direita como inválido. confidence=medium, probe=unit test do validator com CPF terminado em 0.
+- H2: o front trunca o zero antes de enviar. confidence=low, probe=curl com payload exato.
+
+§3.3 Probe escolhida: H1 (trivial e mais provável que H2). Pack indica `./mvnw test -Dtest=...` como comando idiomático.
+
+§3.4 Probe rodada: `./mvnw test -Dtest=CpfValidatorTest#shouldAcceptValidCpfEndingInZero` → **falha. CONFIRMA H1.**
+
+§3.5 Fix mínimo: ajusta regex de `\d{11}` (que estava com erro de greedy match no validator). Dispatch a `qa-engineer` com prompt prefixado pelo `STACK_CONTEXT_BLOCK` de Stage 0 para adicionar teste novo cobrindo CPFs terminados em 0, 1, ..., 9.
+
+§3.6 Probe original rerodada via curl: **retorna 201 Created.**
+
+Relatório emitido conforme §6 (incluindo a linha Stack resolvida).
+
+## 9. When NOT to use this skill
+
+- **Erro óbvio com fix óbvio** (typo, sintaxe, import faltando) — apenas conserta.
+- **Bug com hipótese sólida pré-existente** — vá direto pro fix.
+- **Feature ainda não implementada** — `run-sprint`, não pair-debug.
+- **Refactor proativo** — não é bug.
+- **Performance tuning** sem sintoma reportado — `dba` ou `tech-lead`.

package/.claude/skills/prd-ready-check/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: prd-ready-check
+description: Use as the FINAL GATE before deploying to production. Triggers on phrases like "is it ready for PRD?", "can it ship to production?", "run the final checklist", "validate everything before deploying", "run the prod gate", "DoD", "definition of done", "release check". This skill does NOT implement anything — it validates mvn test, npm test, mvn package, ng build --configuration=production, lint, Playwright smoke E2E, browser console clean, minimum coverage, no critical vulnerabilities, observability, database migrations, and re-runs the test-coverage-auditor as a mandatory gate (open P0/P1 = automatic NO-GO). Assumes auto-test-guard has already run during implementation and left the suite green. Returns GO or NO-GO with reasons. Any NO-GO blocks the deploy. To fix failures, return to backend-developer / frontend-developer / qa-engineer. Do NOT use to implement code (use backend-developer / frontend-developer) nor to generate tests (use auto-test-guard). PT triggers: 'tá pronto pra PRD?', 'pode subir pra produção?', 'roda o checklist final', 'valida tudo antes do deploy', 'roda o gate de prod', 'DoD', 'definição de pronto'.
+tools: Read, Write, Edit, Glob, Grep, Bash(mvn:*), Bash(npm:*), Bash(npx:*)
+model: sonnet
+---
+
+# PRD-Ready Check — Production Gate
+
+Production gatekeeper. Confidently say **GO** or **NO-GO** for deploy to PRD. Never relax the gate — broken test = NO-GO, critical warning = NO-GO, console with error = NO-GO.
+
+Always respond in American English.
+
+---
+
+## When to trigger
+
+- "is it ready for PRD?", "can it ship to production?"
+- "run the final checklist", "validate everything before deploying"
+- "run the prod gate", "DoD", "definition of done", "release check"
+- PT: "tá pronto pra PRD?", "pode subir pra produção?", "roda o gate de prod", "definição de pronto"
+
+- Implementing code → `backend-developer` / `frontend-developer` (via `project-manager` or `run-sprint`).
+- Generating tests → `gate-keeper` agent (via `auto-test-guard` skill).
+- Auditing coverage as standalone task → `test-coverage-auditor` skill.
+
+## Prerequisites
+
+- `auto-test-guard` (gate-keeper) has run and returned GREEN on the current code.
+- `test-coverage-auditor` report is up to date (no open P0 from the last audit).
+- Both backend and frontend compile locally without errors.
+
+## Do NOT use for
+
+- Implementing code — use `backend-developer` / `frontend-developer`.
+- Generating tests — use `gate-keeper` (auto-test-guard skill).
+- Auditing coverage specifically — use `test-coverage-auditor`.
+
+---
+
+## Execution
+
+Standalone skill (Pattern 3 per ADR-037). The calling session executes the gate inline using the frontmatter `tools:` — no Task dispatch.
+
+Follow the checklist in order: Backend tests → Frontend tests → Lint → Builds → Smoke E2E → a11y → Lighthouse → security scan → coverage auditor → migrations → observability. STOP at the first failure and return `NO-GO` with the exact stdout/stderr line. Otherwise return `GO`.
+
+### Hard gate (universal — every stack)
+
+- Backend tests 100% green; coverage >= 85% lines, >= 80% branches.
+- Backend mutation score >= 70% on domain + application (where wired).
+- Backend build artifact succeeds (`./mvnw package`, `pip wheel`, `go build`, ...).
+- Static analysis: 0 CRITICAL, 0 HIGH (SpotBugs / mypy / golangci-lint / ...).
+- Dependency vulnerability scan: 0 CVE with CVSS >= 7.0.
+- Frontend tests 100% green; statements >= 85%, branches >= 80%.
+- Frontend build succeeds (`ng build --configuration=production` or equivalent).
+- ESLint strict: 0 errors, 0 warnings on new code.
+- Playwright smoke E2E: all critical flows green; Chrome MCP `read_console_messages` returns 0 errors.
+- a11y component + E2E: 0 `serious` / 0 `critical`.
+- Lighthouse: score >= 0.80, LCP <= 2500ms, CLS <= 0.1, TBT <= 300ms.
+- `test-coverage-auditor` report up to date: 0 open P0/P1.
+- DB migrations: forward + reversible for every change.
+- Observability: structured JSON logs, correlation ID, `/health` responsive.
+
+### Stack-specific commands
+
+Read `## Project Identity` from `CLAUDE.md` to determine the stack, then consult `.claude/stacks/<lang>/<framework>-<major>.md` for the exact `## Build & run commands` and `## Testing` invocations. If the pack is missing, dispatch the `create-stack-pack` skill first (per ADR-026).
+
+### Output format
+
+```
+PRD-Ready Gate — <date> — <project>
+
+[PASS] backend tests        — coverage 89.4% lines / 82.1% branches
+[PASS] frontend tests       — coverage 87.6% statements
+[FAIL] dependency vuln scan — CVE-2025-XXXXX (CVSS 8.1) in jackson-databind 2.15.0
+
+Verdict: NO-GO
+Routing: security-engineer (technical veto on CVSS >= 7.0)
+```
+
+Never escalate failures to the human — dispatch the responsible specialist via `project-manager`:
+- Backend tests / build → `backend-developer`
+- Frontend tests / a11y / Lighthouse → `frontend-developer` (+ `ux-designer` for a11y)
+- Vulnerabilities → `security-engineer` (technical veto)
+- Coverage gaps → `qa-engineer`
+- DB migrations → `database-engineer`