@luanpdd/kit-mcp 1.8.1 → 1.10.0

package/kit/commands/instrumentar-fase.md

@@ -0,0 +1,200 @@
+---
+name: instrumentar-fase
+description: Após /planejar-fase, gera INSTRUMENTATION.md por plano (spans, atributos canônicos, eventos, validação ODD). Aplica skill observability-driven-development.
+argument-hint: "[fase] [plano]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Task
+---
+
+<objective>
+Após `/planejar-fase` produzir PLAN.md, este comando gera `INSTRUMENTATION.md` para cada plano da fase. Aplica a skill [observability-driven-development](../skills/observability-driven-development/SKILL.md) — bundle telemetria com a feature, valide as 4 perguntas pré-PR.
+
+**Cria/Atualiza:**
+- `.planning/phases/<N>/<padded>-PLAN-<NN>-INSTRUMENTATION.md` por plano
+
+**Após:** o user tem o contrato de instrumentação que o `executor` (e o `observability-instrumenter`) devem cumprir durante `/executar-fase`.
+</objective>
+
+<context>
+**Argumentos:** `$ARGUMENTS` — primeiro token é número da fase (ex.: `30`); segundo opcional é número do plano (ex.: `01`); se omitido, processa todos os planos da fase.
+
+**Pré-requisito:** `/planejar-fase <N>` já rodou. Existem `<padded>-PLAN-<NN>-*.md` em `.planning/phases/<N>/`.
+
+**Skill consultada:** [`observability-driven-development`](../skills/observability-driven-development/SKILL.md) — 4 perguntas pré-PR canônicas.
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+PHASE_NUM=$(echo "$ARGUMENTS" | awk '{print $1}')
+PLAN_NUM=$(echo "$ARGUMENTS" | awk '{print $2}')
+
+if [ -z "$PHASE_NUM" ]; then
+  echo "Uso: /instrumentar-fase <N> [<NN>]"
+  echo "Ex.: /instrumentar-fase 30        # todos os planos da Phase 30"
+  echo "Ex.: /instrumentar-fase 30 01     # só Plano 01 da Phase 30"
+  exit 1
+fi
+```
+
+## 2. Detectar phase_dir + planos
+
+```bash
+PHASE_STATE=$(node "./.claude/framework/bin/tools.cjs" init phase-op "$PHASE_NUM")
+PHASE_DIR=$(echo "$PHASE_STATE" | jq -r .phase_dir)
+
+if [ "$PHASE_DIR" = "null" ] || [ ! -d "$PHASE_DIR" ]; then
+  echo "Fase $PHASE_NUM ainda não foi planejada. Rode /planejar-fase $PHASE_NUM primeiro."
+  exit 1
+fi
+
+# PT-BR: descobrir PLAN.md(s) — exclui já-instrumentados
+if [ -n "$PLAN_NUM" ]; then
+  PLANS=("$PHASE_DIR"/*-PLAN-${PLAN_NUM}-*.md)
+else
+  PLANS=("$PHASE_DIR"/*-PLAN-*.md)
+fi
+```
+
+## 3. Para cada plano, gerar INSTRUMENTATION.md
+
+Para cada `PLAN_FILE`:
+
+```bash
+PADDED=$(basename "$PLAN_FILE" | grep -oE '^[0-9]+')
+NN=$(basename "$PLAN_FILE" | grep -oE 'PLAN-[0-9]+' | grep -oE '[0-9]+')
+OUT_FILE="$PHASE_DIR/${PADDED}-PLAN-${NN}-INSTRUMENTATION.md"
+
+# PT-BR: não sobrescrever se já existe
+if [ -f "$OUT_FILE" ]; then
+  echo "Já existe: $OUT_FILE — pulando"
+  continue
+fi
+```
+
+Ler `PLAN_FILE` para extrair:
+- Goal/objetivo
+- Tarefas (especialmente as que adicionam novos handlers/funções/endpoints)
+- Componentes/serviços tocados
+
+Gerar `INSTRUMENTATION.md` com seções canônicas (consultar [`observability-driven-development`](../skills/observability-driven-development/SKILL.md)):
+
+```markdown
+---
+phase: {N}
+plan: {NN}
+title: Instrumentation Plan for Plan {NN}
+status: pending
+---
+
+# Instrumentation Plan — Phase {N}, Plan {NN}: {plan_title}
+
+## Spans
+
+Spans a adicionar em arquivos modificados/criados pelo plano.
+
+| Name | Kind | Service | Atributos canônicos | Notas |
+|------|------|---------|---------------------|-------|
+| `{handler_name}` | SERVER | `{service}` | `user.id`, `tenant_id`, `request.id`, `endpoint`, `http.method`, `result.success`, `error.type`, `build_id` | inbound HTTP |
+
+## Eventos críticos
+
+Eventos com semantic significance que merecem `result.success` discreto.
+
+| Event | Quando emitir | result.success | error.type enum (catch) |
+|-------|---------------|----------------|--------------------------|
+| `{event_name}` | {momento} | true se {happy path} | `validation` \| `auth` \| `rate_limit` \| `timeout` \| `unknown` |
+
+## Métricas (opcional, se há valores numéricos críticos)
+
+| Name | Type | Unit | Labels |
+|------|------|------|--------|
+| `{metric_name}` | counter \| histogram | `ms` \| `bytes` \| `count` | `tenant_id`, `endpoint` |
+
+## Validação ODD — 4 perguntas pré-PR
+
+| # | Pergunta | Como verificar |
+|---|----------|----------------|
+| 1 | **Faz o que esperei?** | Span tem `result.success = true` no happy path. Smoke: enviar request, query `WHERE result_success = true` retorna |
+| 2 | **Compara à versão anterior?** | `build_id` setado em todo span. Query: `SELECT build_id, ..., AVG(duration_ms) GROUP BY build_id` |
+| 3 | **Usuários estão usando?** | `user.id` ou `tenant_id` ou `customer.tier` em todo span. Query: `SELECT customer.tier, COUNT(*) GROUP BY 1` |
+| 4 | **Anomalias emergem?** | Cada `catch` emite `error.type` enum (não message livre). Cada if/else significativo emite `branch_taken`. Query: `SELECT error.type, COUNT(*) GROUP BY 1` |
+
+## Sampling (head-based, default)
+
+```ts
+// PT-BR: errors sempre, success sample 10% — ajuste conforme volume
+const shouldSample = (event: SpanLike): boolean => {
+  if (event.attributes['result.success'] === false) return true   // 100% errors
+  if (event.attributes['customer.tier'] === 'enterprise') return true  // 100% enterprise
+  return Math.random() < 0.1   // 10% baseline
+}
+```
+
+## Referências cruzadas
+
+- Skill [`structured-events`](../../../../kit/skills/structured-events/SKILL.md) — campos canônicos
+- Skill [`distributed-tracing`](../../../../kit/skills/distributed-tracing/SKILL.md) — propagação cross-service
+- Skill [`opentelemetry-standard`](../../../../kit/skills/opentelemetry-standard/SKILL.md) — SDK setup
+- Skill [`observability-driven-development`](../../../../kit/skills/observability-driven-development/SKILL.md) — 4 perguntas
+- Agente [`observability-instrumenter`](../../../../kit/agents/observability-instrumenter.md) — gera os patches durante `/executar-fase`
+
+## Aceitação
+
+- [ ] Cada handler do plano tem span com 8 atributos canônicos mínimos
+- [ ] Cada `catch` emite `error.type` enum
+- [ ] Cada branch significativo emite `branch_taken`
+- [ ] Outbound calls propagam contexto via `propagation.inject`
+- [ ] Smoke: 100 requests sintéticos → spans queryables com filtragem por `tenant_id`/`user.id`
+```
+
+## 4. Plan-checker hook
+
+Se `plan-checker` está ativo no fluxo, este comando atualiza checkpoint do plan-checker:
+
+```bash
+# PT-BR: registrar que plano agora tem ODD-spec acoplada
+echo "instrumentation:$NN:ready" >> "$PHASE_DIR/.plan-checker-state"
+```
+
+## 5. Output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► INSTRUMENTAR-FASE ▸ Phase {N}
+═══════════════════════════════════════════════════════════
+
+Planos processados: {count}
+INSTRUMENTATION.md gerados:
+  - {padded}-PLAN-01-INSTRUMENTATION.md
+  - {padded}-PLAN-02-INSTRUMENTATION.md
+  ...
+
+Próximo passo:
+  - `/executar-fase {N}` — executor invocará observability-instrumenter automaticamente para aplicar os spans descritos
+  - `/auditar-uat` antes do PR — valida que as 4 perguntas ODD têm resposta executável
+```
+
+## 6. Commit
+
+```bash
+node "./.claude/framework/bin/tools.cjs" commit "docs(${PHASE_NUM}): instrumentation plans" --files "${PHASE_DIR}"/*-INSTRUMENTATION.md
+```
+
+</process>
+
+<success_criteria>
+- [ ] Para cada `PLAN-NN-*.md` da fase, existe `PLAN-NN-INSTRUMENTATION.md`
+- [ ] INSTRUMENTATION.md tem 4 seções: Spans, Eventos críticos, Métricas, Validação ODD
+- [ ] Validação ODD com 4 perguntas explicitamente respondidas
+- [ ] Cross-references para skills `structured-events`, `distributed-tracing`, `opentelemetry-standard`, `observability-driven-development`
+- [ ] Não sobrescreve INSTRUMENTATION.md já existente (idempotente)
+- [ ] Commit atômico após geração
+</success_criteria>

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/postmortem.md

@@ -0,0 +1,179 @@
+---
+name: postmortem
+description: Invoca postmortem-writer — modo --from-investigation <id> (lê v1.9 trail) ou --incident "<descrição>" standalone; produz postmortem blameless 9 seções.
+argument-hint: "(--from-investigation <id> | --incident \"<descrição>\") [--severity SEV1|SEV2|SEV3]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Gerar **postmortem blameless** de 9 seções (cap 15 do livro Google SRE) — Summary, Impact, Root Causes, Trigger, Resolution, Detection, Action Items, Lessons Learned, Timeline UTC. Invoca o agente [`postmortem-writer`](../agents/postmortem-writer.md) que aplica a skill [`blameless-postmortems`](../skills/blameless-postmortems/SKILL.md) — cultura blameless ("foco em sistema/processo, NÃO em pessoas"), action items SMART, "no postmortem left unreviewed".
+
+**Cria/Atualiza:**
+- `.planning/postmortems/<id>.md` — postmortem blameless completo
+
+**Após:** o user tem postmortem revisável + action items concretos. Phase 40 INT-FW-V2-01 chained do `/forense` automaticamente após Core Analysis Loop fechar.
+</objective>
+
+<context>
+**Argumentos:** `$ARGUMENTS` — comando suporta **2 modos mutuamente exclusivos**.
+
+**Modo A: `--from-investigation <id>` (preferido — continuação de v1.9)**
+
+Lê `.planning/investigations/<id>.md` produzido pelo [`incident-investigator`](../agents/incident-investigator.md) (v1.9 — Core Analysis Loop). Extrai automaticamente: trigger, root cause, hipóteses validadas, action items. Campos faltantes (impact quantificado, severity, autores) são perguntados via `AskUserQuestion`.
+
+**Modo B: `--incident "<descrição>"` (standalone)**
+
+Para postmortem sem investigation prévia (incident menor, near-miss, lições retrospectivas). Agent gera template e usa `AskUserQuestion` para 9 perguntas guiadas — uma por seção canônica.
+
+**Flags adicionais:**
+- `--severity <SEV1|SEV2|SEV3>` — severity do incident (default: AskUserQuestion)
+- `--output <path>` — caminho do postmortem (default: `.planning/postmortems/<id>.md` — id auto-gerado)
+
+**Exemplos:**
+```
+/postmortem --from-investigation incident-2026-05-06-1432-checkout-burn   # Modo A
+/postmortem --incident "checkout SLO burn às 14:32 — RCA N+1 query orders" --severity SEV2  # Modo B
+/postmortem --incident "near-miss: deploy bloqueou 2min antes do PR-1234"                    # near-miss
+```
+
+**Pré-requisito (Modo A):** arquivo `.planning/investigations/<id>.md` existe (criado por `/investigar-producao` ou `/forense`).
+</context>
+
+<process>
+
+## 1. Parsear argumentos (2 modos)
+
+```bash
+INV_ID=$(echo "$ARGUMENTS" | grep -oE -- '--from-investigation [^ ]+' | awk '{print $2}')
+INCIDENT=$(echo "$ARGUMENTS" | grep -oE -- '--incident "[^"]+"' | sed 's/--incident //; s/^"//; s/"$//')
+SEVERITY=$(echo "$ARGUMENTS" | grep -oE -- '--severity [^ ]+' | awk '{print $2}')
+OUTPUT_PATH=$(echo "$ARGUMENTS" | grep -oE -- '--output [^ ]+' | awk '{print $2}')
+
+# PT-BR: validar mutuamente exclusivos
+if [ -n "$INV_ID" ] && [ -n "$INCIDENT" ]; then
+  echo "✗ Erro: --from-investigation e --incident são mutuamente exclusivos. Escolha um."
+  exit 1
+fi
+
+# PT-BR: se nenhum dos 2 → AskUserQuestion (Modo C — interativo)
+if [ -z "$INV_ID" ] && [ -z "$INCIDENT" ]; then
+  # Listar investigations recentes para sugestão
+  RECENT_INVS=$(ls -t .planning/investigations/*.md 2>/dev/null | head -5 | while read f; do basename "$f" .md; done | tr '\n' ',')
+  # AskUserQuestion: "Modo? Continuar de investigation existente OU postmortem standalone?"
+  # Opções: Continuar de <ID> (uma por investigation recente) | Standalone (texto livre)
+  echo "ℹ Sem flag explícita. Use --from-investigation <id> ou --incident \"<descrição>\"."
+  [ -n "$RECENT_INVS" ] && echo "  Investigations recentes: $RECENT_INVS"
+  exit 1
+fi
+```
+
+## 2. Validar pré-requisitos por modo
+
+```bash
+mkdir -p .planning/postmortems
+
+# PT-BR: Modo A — investigation file precisa existir
+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/"
+    echo "  Para postmortem standalone: /postmortem --incident \"<descrição>\""
+    exit 1
+  fi
+  # PT-BR: derivar postmortem id do investigation_id
+  POSTMORTEM_ID="$INV_ID"
+fi
+
+# PT-BR: Modo B — gerar postmortem id automaticamente
+if [ -n "$INCIDENT" ]; then
+  DATE=$(date -u +%Y-%m-%d-%H%M)
+  SLUG=$(echo "$INCIDENT" | tr ' ' '-' | tr -cd 'a-zA-Z0-9-' | head -c 30 | sed 's/-$//')
+  POSTMORTEM_ID="postmortem-${DATE}-${SLUG}"
+fi
+
+# PT-BR: default output_path (override via --output)
+[ -z "$OUTPUT_PATH" ] && OUTPUT_PATH=".planning/postmortems/${POSTMORTEM_ID}.md"
+
+# PT-BR: idempotência — não sobrescrever postmortem existente sem confirmar
+if [ -f "$OUTPUT_PATH" ]; then
+  echo "⚠ Postmortem $OUTPUT_PATH já existe."
+  echo "  Use --output <novo-path> ou rm $OUTPUT_PATH antes de re-rodar."
+  exit 1
+fi
+```
+
+## 3. Listar postmortems recentes (UX)
+
+```bash
+# PT-BR: contexto — postmortems anteriores para correlacionar lessons learned
+ls -t .planning/postmortems/*.md 2>/dev/null | head -3 | while read f; do
+  ID=$(basename "$f" .md)
+  DATE=$(grep -m1 '\*\*Date:\*\*' "$f" 2>/dev/null | sed 's/.*Date:\*\* //' || echo "?")
+  printf "  %s — %s\n" "$ID" "$DATE"
+done
+```
+
+## 4. Dispatch para `postmortem-writer`
+
+```text
+Task(
+  subagent_type="postmortem-writer",
+  prompt="
+${INV_ID:+investigation_id: ${INV_ID}}
+${INCIDENT:+incident_description: ${INCIDENT}}
+${SEVERITY:+severity: ${SEVERITY}}
+output_path: ${OUTPUT_PATH}
+postmortem_id: ${POSTMORTEM_ID}
+
+Aplicar skill blameless-postmortems. Modo:
+${INV_ID:+- Modo A: ler .planning/investigations/${INV_ID}.md, extrair trigger/root_cause/hipóteses/action_items automaticamente; perguntar via AskUserQuestion apenas campos faltantes (impact quantificado, severity, autores).}
+${INCIDENT:+- Modo B: gerar template; perguntar via AskUserQuestion 9 questões guiadas — uma por seção canônica (Summary, Impact, Root Causes, Trigger, Resolution, Detection, Action Items, Lessons Learned, Timeline).}
+
+Padrões obrigatórios:
+- Foco em sistema/processo (NUNCA em pessoas) — anti-pattern blame culture
+- Action items SMART (Specific, Measurable, Assignable, Realistic, Time-bound)
+- Timeline em UTC sempre
+- Impact quantificado (# usuários, duração, SLO budget consumido, revenue se aplicável)
+- 9 seções canônicas obrigatórias (skip = inválido)
+"
+)
+```
+
+## 5. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► POSTMORTEM ▸ ${POSTMORTEM_ID}
+═══════════════════════════════════════════════════════════
+
+[output do postmortem-writer — ver Step 6 do agent]
+
+## Estado salvo
+.planning/postmortems/${POSTMORTEM_ID}.md
+
+## Próximos passos
+1. Revisar o postmortem com o time — "no postmortem left unreviewed"
+2. Distribuir para reviewer SRE OU par externo (anti-pattern: auto-review)
+3. Action items entram no roadmap (`/adicionar-tarefa` ou `/adicionar-fase`)
+4. Se PRR for próximo passo de production-readiness: `/prr --service <name>`
+5. Cross-ref OMM: postmortems alimentam Capacidade 5 (Incident Response) — `/observabilidade omm`
+```
+
+</process>
+
+<success_criteria>
+- [ ] `--from-investigation <id>` E `--incident "<text>"` parseados (mutuamente exclusivos)
+- [ ] Modo A: arquivo `.planning/investigations/<id>.md` validado existe antes de dispatch
+- [ ] Modo B: postmortem_id auto-gerado a partir de date + slug
+- [ ] Idempotência: não sobrescreve postmortem existente sem `--output` explícito
+- [ ] `postmortem-writer` invocado via `Task(subagent_type=...)` com prompt completo (modo + 9 seções + padrões)
+- [ ] `.planning/postmortems/<id>.md` criado pelo agent
+- [ ] Próximos passos sugerem cross-ref para `/prr`, `/observabilidade omm`, `/adicionar-tarefa`
+</success_criteria>