@luanpdd/kit-mcp 1.8.1 → 1.9.0

package/kit/commands/investigar-producao.md

@@ -0,0 +1,162 @@
+---
+name: investigar-producao
+description: Lança Core Analysis Loop guiado em incidente real — agente incident-investigator usa MCP Supabase, mantém estado em .planning/investigations/, retoma entre resets de contexto.
+argument-hint: "<sintoma em texto livre> [--id <investigation_id>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Lança o agente [`incident-investigator`](../agents/incident-investigator.md) para aplicar o [Core Analysis Loop](../skills/core-analysis-loop/SKILL.md) sobre um incidente. Estado iterativo de hipóteses fica em `.planning/investigations/<id>.md` — permite retomar entre resets de contexto (precedente: `/depurar`).
+
+**Cria/Atualiza:**
+- `.planning/investigations/<investigation_id>.md` — trilha de hipóteses validadas/refutadas
+
+**Após:** root cause documentado + action items + estado salvo para próxima sessão.
+</objective>
+
+<context>
+**Argumentos:** `$ARGUMENTS` — texto livre do sintoma + flags opcionais.
+
+**Flags:**
+- `--id <investigation_id>` — retoma investigação existente (pula criação de novo arquivo)
+- `--time-window <Nh|Nd>` — janela de busca (default: 1h)
+
+**Exemplos:**
+```
+/investigar-producao "checkout SLO burn rate = 8 às 14:32"
+/investigar-producao --id incident-2026-05-06-1432-checkout-burn  # retomar
+/investigar-producao "tenant acme reportou erros 5xx" --time-window 6h
+```
+
+**Pré-requisito (Full mode):** projeto Supabase configurado, `mcp__supabase__*` disponível.
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+INV_ID=$(echo "$ARGUMENTS" | grep -oE -- '--id [^ ]+' | awk '{print $2}')
+TIME_WINDOW=$(echo "$ARGUMENTS" | grep -oE -- '--time-window [^ ]+' | awk '{print $2}')
+SYMPTOM=$(echo "$ARGUMENTS" | sed -E 's/--(id|time-window) [^ ]+//g' | xargs)
+
+[ -z "$TIME_WINDOW" ] && TIME_WINDOW="1h"
+```
+
+## 2. Validar pré-requisitos
+
+```bash
+mkdir -p .planning/investigations
+
+# PT-BR: se --id fornecido, validar arquivo existe
+if [ -n "$INV_ID" ]; then
+  INV_FILE=".planning/investigations/${INV_ID}.md"
+  if [ ! -f "$INV_FILE" ]; then
+    echo "Investigation $INV_ID não existe. Liste com: ls .planning/investigations/"
+    exit 1
+  fi
+  echo "Retomando investigação: $INV_ID"
+fi
+
+# PT-BR: se SYMPTOM vazio + sem --id → erro
+if [ -z "$SYMPTOM" ] && [ -z "$INV_ID" ]; then
+  echo "Erro: forneça sintoma OU --id <investigation_id>"
+  echo "Exemplos:"
+  echo "  /investigar-producao \"checkout SLO burn rate = 8\""
+  echo "  /investigar-producao --id incident-2026-05-06-1432-foo"
+  exit 1
+fi
+```
+
+## 3. Detectar `supabase/config.toml`
+
+```bash
+PROJECT_ID=""
+if [ -f supabase/config.toml ]; then
+  PROJECT_ID=$(grep -E '^project_id\s*=' supabase/config.toml | sed 's/.*= *"\(.*\)".*/\1/' | head -1)
+fi
+```
+
+## 4. Listar investigações em aberto (UX)
+
+Antes de lançar agente, mostrar contexto de investigações ativas:
+
+```bash
+ls -t .planning/investigations/*.md 2>/dev/null | head -5 | while read f; do
+  ID=$(basename "$f" .md)
+  STARTED=$(grep '**Started:**' "$f" | head -1 | sed 's/.*Started:\*\* //')
+  STATUS=$(grep -E '^## (Root Cause|Status:)' "$f" | head -1)
+  printf "  %s — %s — %s\n" "$ID" "$STARTED" "$STATUS"
+done
+```
+
+## 5. Dispatch para `incident-investigator`
+
+```text
+Task(
+  subagent_type="incident-investigator",
+  prompt="
+${SYMPTOM:-(retomando $INV_ID)}
+
+${INV_ID:+investigation_id: $INV_ID}
+${PROJECT_ID:+project_id: $PROJECT_ID}
+time_window: ${TIME_WINDOW}
+
+Aplicar Core Analysis Loop até root cause OU lacuna intransponível.
+Salvar estado iterativo em .planning/investigations/{id}.md.
+Documentar todas as hipóteses (validated/refuted/inconclusive) com query + resultado citado.
+"
+)
+```
+
+## 6. Após retorno do agente
+
+Apresentar resumo curto + caminho do arquivo de estado:
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► INVESTIGAR-PRODUCAO ▸ ${INV_ID}
+═══════════════════════════════════════════════════════════
+
+[output do agente — ver agente incident-investigator Step 7]
+
+## Estado salvo
+.planning/investigations/${INV_ID}.md
+
+## Próximos passos
+- Action items listados no Root Cause acima
+- Para abrir loop separado (ex.: "por que tenant acelerou?"):
+  /investigar-producao "<novo sintoma>"
+- Para retomar mais tarde:
+  /investigar-producao --id ${INV_ID}
+```
+
+## 7. Pause AskUserQuestion (opcional)
+
+Se agente reportou status `INCONCLUSIVE` ou `gaps_found`, perguntar via AskUserQuestion:
+
+- header: "Próximo?"
+- question: "Investigation incompleta. O que fazer?"
+- options:
+  - "Continuar com hipótese específica" — pede texto livre da hipótese
+  - "Pausar — retomar depois" — sai mantendo state
+  - "Fechar como inconclusiva" — marca arquivo como `## Status: INCONCLUSIVE` e sai
+
+</process>
+
+<success_criteria>
+- [ ] Sintoma + investigation_id (novo ou existente) parseados corretamente
+- [ ] Arquivo `.planning/investigations/<id>.md` criado/atualizado
+- [ ] `mcp__supabase__*` invocados em ≥ 1 hipótese (Full mode); ou modo offline declarado
+- [ ] Cada hipótese documentada com Query + Resultado citado
+- [ ] Root cause tem 4 dimensões (WHO/WHERE/WHEN/WHAT) OU status INCONCLUSIVE explícito
+- [ ] Action items concretos listados
+- [ ] Estado retomável: `/investigar-producao --id <id>` recarrega trilha
+</success_criteria>

package/kit/commands/observabilidade.md

@@ -0,0 +1,116 @@
+---
+name: observabilidade
+description: Orquestrador da Suíte Observabilidade — dispatch para agents (instrumenter, investigator, slo-engineer, burn-rate-forecaster, omm-auditor) com sinônimos PT/EN.
+argument-hint: "<subcomando> [args...]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Orquestrador único da Suíte Observabilidade (v1.9). Recebe subcomando e args, faz dispatch via `Task(subagent_type=...)` para o agent especializado correto. **Único ponto de chain de agents observability** (precedente: `/supabase` em v1.8 — anti-pitfall A10 mantido).
+
+**Cria/Atualiza:** o que cada agent invocado cria.
+
+**Após:** o usuário tem o output do agent (patches, SLO.md, snapshot OMM, investigation trail, etc.).
+</objective>
+
+<execution_context>
+Skills consultadas pelos agents: `kit/skills/_shared-observability/glossary.md` (Phase 29) + `kit/skills/observability-*/SKILL.md` + `kit/skills/structured-events/SKILL.md` + `kit/skills/distributed-tracing/SKILL.md` + `kit/skills/opentelemetry-standard/SKILL.md` + `kit/skills/core-analysis-loop/SKILL.md` + `kit/skills/event-based-slos/SKILL.md` + `kit/skills/burn-rate-alerting/SKILL.md` + `kit/skills/telemetry-sampling/SKILL.md` + `kit/skills/telemetry-pipelines/SKILL.md`.
+
+Agents disponíveis: `kit/agents/observability-instrumenter.md` (Phase 30), `kit/agents/incident-investigator.md` (Phase 30), `kit/agents/slo-engineer.md` (Phase 32), `kit/agents/burn-rate-forecaster.md` (Phase 32), `kit/agents/omm-auditor.md` (Phase 34).
+</execution_context>
+
+<context>
+**Argumentos:** `$ARGUMENTS` — primeiro token é o subcomando; restante é passado para o agent como prompt.
+
+**Subcomandos suportados (sinônimos PT-BR/EN):**
+
+| Subcomando | Sinônimos | Agent dispatched |
+|---|---|---|
+| `instrumentar` | `instrument`, `inst` | `observability-instrumenter` |
+| `investigar` | `investigate`, `incident` | `incident-investigator` |
+| `slo` | `definir-slo`, `slo-engineer` | `slo-engineer` |
+| `burn-rate` | `burn`, `burn-rate-forecaster`, `forecast` | `burn-rate-forecaster` |
+| `omm` | `auditar`, `audit`, `maturity` | `omm-auditor` |
+| `help` | `ajuda`, `?` | exibe esta tabela inline |
+</context>
+
+<process>
+
+## 1. Parsear subcomando
+
+```bash
+SUBCMD=$(echo "$ARGUMENTS" | awk '{print $1}')
+ARGS=$(echo "$ARGUMENTS" | cut -d' ' -f2-)
+```
+
+**Se `$ARGUMENTS` for vazio ou `SUBCMD` for `help`/`ajuda`/`?`:** exibir tabela de subcomandos inline + exemplo. Sair.
+
+## 2. Resolver sinônimos
+
+```text
+instrumentar, instrument, inst                      → observability-instrumenter
+investigar, investigate, incident                   → incident-investigator
+slo, definir-slo, slo-engineer                      → slo-engineer
+burn-rate, burn, burn-rate-forecaster, forecast     → burn-rate-forecaster
+omm, auditar, audit, maturity                       → omm-auditor
+```
+
+**Se subcomando não resolve:** exibir erro inline com lista de subcomandos válidos. Sair.
+
+```
+✗ Subcomando desconhecido: '<SUBCMD>'
+
+Subcomandos válidos:
+  instrumentar / instrument        → instrumentar código com OTel + atributos canônicos
+  investigar / investigate         → Core Analysis Loop em incident
+  slo / definir-slo                → criar SLO.md + SQL materializar SLI
+  burn-rate / forecast             → calcular burn rate atual + ETA exhaustão
+  omm / auditar                    → OMM scored 5 capacidades
+
+Uso: /observabilidade <subcomando> <args...>
+Exemplo: /observabilidade investigar "checkout SLO burn rate = 8 às 14:32"
+```
+
+## 3. Detectar `supabase/config.toml` (para agents que usam MCP Supabase)
+
+```bash
+PROJECT_ID=""
+if [ -f supabase/config.toml ]; then
+  PROJECT_ID=$(grep -E '^project_id\s*=' supabase/config.toml | sed 's/.*= *"\(.*\)".*/\1/' | head -1)
+fi
+```
+
+## 4. Dispatch
+
+Invocar `Task(subagent_type=<agent_name>, prompt=<built_prompt>)`.
+
+**Prompt construído:**
+
+```
+{ARGS}
+
+{Se project_id detectado:}
+project_id: {PROJECT_ID}
+```
+
+## 5. Output
+
+Output do agent é o output do command. Sem post-processing — agent já formata estruturado.
+
+</process>
+
+<success_criteria>
+- [ ] Subcomando resolvido para agent canônico (5 subcomandos × seus sinônimos)
+- [ ] `project_id` extraído de `supabase/config.toml` se presente
+- [ ] Dispatch via `Task(subagent_type=...)` — único ponto de chain
+- [ ] Subcomando inválido → mensagem clara com lista
+- [ ] Subcomando `help`/`ajuda`/`?` → exibe tabela inline
+- [ ] Args após subcomando passam transparentemente para o agent
+</success_criteria>

package/kit/commands/planejar-fase.md

@@ -45,3 +45,23 @@ Normalizar entrada da fase no passo 2 antes de qualquer pesquisa de diretório.
 Execute o workflow plan-phase de @./.claude/framework/workflows/plan-phase.md do início ao fim.
 Preserve todos os checkpoints do workflow (validação, pesquisa, planejamento, loop de verificação, roteamento).
 </process>
+
+<observability_integration>
+**Integração com ODD plan-checker gate (v1.9):**
+
+Quando `workflow.observability_plan_gate = true` (default para fases voltadas ao usuário), o `plan-checker` invocado neste workflow inclui uma checagem extra:
+
+1. Lê `<observability>` section do CONTEXT.md (criado por `/discutir-fase` ou `/instrumentar-fase`)
+2. Verifica que as 4 perguntas pré-PR estão respondidas (consulta skill [`observability-driven-development`](../skills/observability-driven-development/SKILL.md)):
+   - Faz o que esperei? → INSTRUMENTATION.md tem `result.success` documentado?
+   - Compara à versão anterior? → `build_id` em todo span planejado?
+   - Usuários estão usando? → identidade (`user.id`/`tenant_id`/`customer.tier`) presente?
+   - Anomalias emergem? → `error.type` enum + `branch_taken` planejados?
+3. Se alguma pergunta ausente: VERIFICATION.md status = `gaps_found`, sugerindo invocar `/instrumentar-fase` para gerar INSTRUMENTATION.md.
+
+**Fases de infraestrutura pura** (skip discuss already detectou): pula gate silenciosamente.
+
+**Quando há observability gate enabled e gap encontrado:** o user pode (a) `/instrumentar-fase` antes de prosseguir; ou (b) editar manualmente CONTEXT.md `<observability>` section; ou (c) override via `--skip-observability-gate`.
+
+**REQ:** INT-FW-02.
+</observability_integration>

package/kit/commands/verificar-trabalho.md

@@ -36,3 +36,29 @@ Arquivos de contexto são resolvidos dentro do workflow (`init verify-work`) e d
 Execute o workflow verify-work de @./.claude/framework/workflows/verify-work.md do início ao fim.
 Preserve todos os gates do workflow (gerenciamento de sessão, apresentação de testes, diagnóstico, planejamento de correções, roteamento).
 </process>
+
+<observability_integration>
+**Integração com Core Analysis Loop em logs reais (v1.9):**
+
+Quando `workflow.observability_uat_validation = true` (default) e o projeto tem MCP Supabase disponível, o workflow inclui passo de validação observacional após UAT conversacional:
+
+1. Para cada test passing no UAT, invocar o agente [`incident-investigator`](../agents/incident-investigator.md) em modo "validation":
+   ```
+   Task(subagent_type="incident-investigator", prompt="
+     mode: validation
+     symptom: validar que feature de Phase {N} efetivamente emitiu spans/eventos esperados
+     time_window: última 1h
+     expected_attributes: {result.success: true, build_id: {current_build}}
+   ")
+   ```
+2. O agente queryará via `mcp__supabase__get_logs` ou `mcp__supabase__execute_sql` para confirmar:
+   - Spans com nome esperado existem
+   - Atributos canônicos foram emitidos (não só código existe — comportamento real)
+   - `result.success` baseline está dentro do esperado
+3. Se confirmado: UAT.md inclui evidência observacional (não só "funciona em UI"). Status `passed` ✓.
+4. Se ausente: UAT.md flag `human_needed` com sugestão "verificar instrumentação não está pegando".
+
+**Skill consultada:** [`core-analysis-loop`](../skills/core-analysis-loop/SKILL.md) — para o caso de UAT falhar e precisar investigar.
+
+**REQ:** INT-FW-03.
+</observability_integration>