@luanpdd/kit-mcp 1.9.0 → 1.11.0

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>

package/kit/commands/prr.md

@@ -0,0 +1,205 @@
+---
+name: prr
+description: Invoca prr-conductor — Production Readiness Review scored em 6 axes (cap 32); modos --service <name> ou --feature <desc>; offline fallback se MCP ausente.
+argument-hint: "(--service <name> | --feature \"<desc>\") [--engagement simple|early|platform] [--reviewer @sre]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Conduzir **Production Readiness Review** (PRR — cap 32 do livro Google SRE) para serviço/feature antes de production. Invoca o agente [`prr-conductor`](../agents/prr-conductor.md) que aplica a skill [`production-readiness-review`](../skills/production-readiness-review/SKILL.md) — checklist canônico **6 axes** + **3 engagement models** + handoff dev→SRE.
+
+**6 axes obrigatórios** (pular um = aprovação inválida):
+1. System Architecture — design, dependencies, blast radius, isolation
+2. Instrumentation/Metrics/Monitoring — 4 golden signals, SLOs, alerting
+3. Emergency Response — runbooks, on-call, rollback, communication
+4. Capacity Planning — load testing, scaling, headroom
+5. Change Management — canary, feature flags, rollback < 60s
+6. Performance — latency budgets, throughput, optimization
+
+**Cria/Atualiza:**
+- `.planning/prr/<service>.md` (Modo A) OR `.planning/prr/feature-<slug>.md` (Modo B) — PRR-REPORT.md scored
+
+**Após:** o user tem decisão `Approved` / `Approved with conditions` / `Blocked` + lista canônica de P0 items por axe + reviewer signature. Phase 40 INT-FW-V2-02 integra `/concluir-marco` com gate PRR opcional.
+</objective>
+
+<context>
+**Argumentos:** `$ARGUMENTS` — comando suporta **2 modos mutuamente exclusivos**.
+
+**Modo A: `--service <name>` (audit de serviço existente)**
+
+Para serviços já em production OU prestes a entrar — agent lê schema (Supabase MCP), Edge Functions code, SLOs definidos (`.planning/slos/`), advisors. Output: `.planning/prr/<service>.md`.
+
+**Modo B: `--feature <description>` (audit pré-launch)**
+
+Para feature em design/dev — agent lê design docs, SLOs propostos, código WIP. Output: `.planning/prr/feature-<slug>.md`.
+
+**Engagement models (cap 32):**
+- `simple` — outage cost < $1k/min OR internal tool — 4-8h, 1 sessão
+- `early` — outage cost $1k-100k/min OR customer-facing — semanas, SRE no design
+- `platform` — outage cost > $100k/min OR built on Frameworks/SRE Platform — PRR é confirmação
+
+**Flags:**
+- `--engagement <simple|early|platform>` — engagement model (default: AskUserQuestion baseado em outage cost)
+- `--reviewer <@handle>` — handle do reviewer SRE (default: AskUserQuestion — **NUNCA pode ser team dev**, anti-pattern auto-PRR)
+- `--outage-cost <usd>` — custo de outage por minuto (default: AskUserQuestion para escolher engagement)
+- `--output <path>` — caminho do output (override de default canônico)
+
+**Exemplos:**
+```
+/prr --service orders-api                                          # Modo A — defaults
+/prr --service orders-api --engagement early --reviewer @ops-lead  # Modo A com config
+/prr --feature "RAG sobre documentos privados" --reviewer @sre     # Modo B
+/prr --service edge-process-emails --engagement simple             # Edge Function simples
+```
+
+**Pré-requisito (Full mode):** projeto Supabase configurado, `mcp__supabase__*` disponível. Modo offline funciona com fallback graceful (filesystem only — itens MCP-dependentes ficam `EVIDENCE_PENDING_MCP`).
+</context>
+
+<process>
+
+## 1. Parsear argumentos (2 modos)
+
+```bash
+SERVICE=$(echo "$ARGUMENTS" | grep -oE -- '--service [^ ]+' | awk '{print $2}')
+FEATURE=$(echo "$ARGUMENTS" | grep -oE -- '--feature "[^"]+"' | sed 's/--feature //; s/^"//; s/"$//')
+ENGAGEMENT=$(echo "$ARGUMENTS" | grep -oE -- '--engagement [^ ]+' | awk '{print $2}')
+REVIEWER=$(echo "$ARGUMENTS" | grep -oE -- '--reviewer [^ ]+' | awk '{print $2}')
+OUTAGE_COST=$(echo "$ARGUMENTS" | grep -oE -- '--outage-cost [^ ]+' | awk '{print $2}')
+OUTPUT_PATH=$(echo "$ARGUMENTS" | grep -oE -- '--output [^ ]+' | awk '{print $2}')
+
+# PT-BR: validar mutuamente exclusivos
+if [ -n "$SERVICE" ] && [ -n "$FEATURE" ]; then
+  echo "✗ Erro: --service e --feature são mutuamente exclusivos. Escolha um."
+  exit 1
+fi
+
+# PT-BR: nenhum dos 2 → erro com sugestão
+if [ -z "$SERVICE" ] && [ -z "$FEATURE" ]; then
+  echo "✗ Forneça --service <name> OU --feature \"<descrição>\""
+  echo "  Exemplos:"
+  echo "    /prr --service orders-api"
+  echo "    /prr --feature \"RAG sobre documentos privados\""
+  exit 1
+fi
+```
+
+## 2. Resolver output_path + idempotência
+
+```bash
+if [ -n "$SERVICE" ]; then
+  [ -z "$OUTPUT_PATH" ] && OUTPUT_PATH=".planning/prr/${SERVICE}.md"
+else
+  SLUG=$(echo "$FEATURE" | tr ' ' '-' | tr -cd 'a-zA-Z0-9-' | head -c 30 | sed 's/-$//')
+  [ -z "$OUTPUT_PATH" ] && OUTPUT_PATH=".planning/prr/feature-${SLUG}.md"
+fi
+mkdir -p "$(dirname "$OUTPUT_PATH")"
+
+# PT-BR: PRR pode ser re-PRR (após mudança grande) — informar mas permitir
+if [ -f "$OUTPUT_PATH" ]; then
+  LAST_DATE=$(grep -m1 '**Date:**' "$OUTPUT_PATH" 2>/dev/null | sed 's/.*Date:\*\* //' || echo "?")
+  echo "ℹ PRR-REPORT.md anterior detectado ($LAST_DATE) em $OUTPUT_PATH."
+  echo "  Re-PRR válido (após mudança grande, incident, ou anual). Continuando — vai sobrescrever."
+fi
+```
+
+## 3. Detectar `supabase/config.toml` (Full mode)
+
+```bash
+PROJECT_ID=""
+if [ -f supabase/config.toml ]; then
+  PROJECT_ID=$(grep -E '^project_id\s*=' supabase/config.toml | sed 's/.*= *"\(.*\)".*/\1/' | head -1)
+  echo "✓ project_id detectado: $PROJECT_ID (Full mode com MCP Supabase)"
+else
+  echo "ℹ Sem supabase/config.toml — agent pode rodar em modo offline (fallback graceful)"
+fi
+```
+
+## 4. AskUserQuestion — engagement model + reviewer
+
+Se `--engagement` não fornecido E `--outage-cost` ausente:
+
+> **AskUserQuestion**
+> header: "PRR Engagement Model"
+> question: "Qual custo estimado de outage para este target?"
+> options:
+> - "< $1k/min OR internal tool → Simple PRR (4-8h, 1 sessão)"
+> - "$1k-100k/min OR customer-facing → Early Engagement (semanas, SRE no design)"
+> - "> $100k/min OR built on platform → Frameworks/Platform (PRR é confirmação)"
+
+Se `--reviewer` não fornecido (anti-pattern auto-PRR):
+
+> **AskUserQuestion**
+> header: "PRR Reviewer (anti auto-PRR)"
+> question: "Quem é o reviewer? Reviewer DEVE ser SRE OU par externo ao time dev (anti-pattern: time dev faz auto-PRR — confirmation bias)."
+> options: (texto livre — handle/email)
+
+## 5. Dispatch para `prr-conductor`
+
+```text
+Task(
+  subagent_type="prr-conductor",
+  prompt="
+${SERVICE:+service_name: ${SERVICE}}
+${FEATURE:+feature_description: ${FEATURE}}
+output_path: ${OUTPUT_PATH}
+${ENGAGEMENT:+engagement_model: ${ENGAGEMENT}}
+${REVIEWER:+reviewer: ${REVIEWER}}
+${OUTAGE_COST:+outage_cost_per_min: ${OUTAGE_COST}}
+${PROJECT_ID:+project_id: ${PROJECT_ID}}
+
+Aplicar skill production-readiness-review. Audit em 6 axes (todos obrigatórios — pular = inválido):
+1. System Architecture — design, dependencies, blast radius, isolation, single points of failure
+2. Instrumentation/Metrics/Monitoring — 4 golden signals, SLOs definidos, alerting com burn rates
+3. Emergency Response — runbooks atualizados, on-call rotation, rollback < 60s, communication plan
+4. Capacity Planning — load testing recente, scaling docs, headroom % atual vs peak
+5. Change Management — canary deployment, feature flags, rollback drills
+6. Performance — latency p50/p95/p99 vs budget, throughput vs target, optimization headroom
+
+Padrão obrigatório: cada item evidence-based (NÃO 'acreditamos que está pronto' — exigir query/log/runbook/test).
+Modo offline: se MCP ausente, declarar [MODO OFFLINE] e marcar items MCP-dependentes EVIDENCE_PENDING_MCP.
+Output: PRR-REPORT.md com scoring 0-5 por axe + status Pass/Pass with gaps/Fail + decisão Approved/Approved with conditions/Blocked + reviewer signature + Re-PRR triggers.
+"
+)
+```
+
+## 6. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► PRR ▸ ${SERVICE:-feature-${SLUG}}
+═══════════════════════════════════════════════════════════
+
+[output do prr-conductor — ver Step 3 do agent]
+
+## Estado salvo
+${OUTPUT_PATH}
+
+## Próximos passos
+1. Reviewer (`${REVIEWER}`) precisa assinar — anti-pattern: rubber stamp sem ler evidence
+2. P0 items são bloqueadores; P1 items são conditions; P2 items são monitoramento
+3. Re-PRR triggers (anual, mudança arquitetural grande, incident SEV1+) — agendar
+4. Se status `Approved` → liberar para production; se `Blocked` → fechar P0s antes de re-submit
+5. Cross-ref OMM: PRR alimenta Capacidade 4 (Production Readiness) — `/observabilidade omm`
+6. Phase 40 INT-FW-V2-02: `/concluir-marco` pode exigir PRR `Approved` se `workflow.complete_milestone_prr_gate=true`
+```
+
+</process>
+
+<success_criteria>
+- [ ] `--service <name>` E `--feature "<desc>"` parseados (mutuamente exclusivos)
+- [ ] Modo A: output canônico `.planning/prr/<service>.md` (override via `--output`)
+- [ ] Modo B: output canônico `.planning/prr/feature-<slug>.md` (slug auto-gerado)
+- [ ] Re-PRR não-bloqueante (informa mas permite — re-PRR é válido após mudança grande)
+- [ ] `supabase/config.toml` detectado para passar `project_id` (Full mode)
+- [ ] AskUserQuestion para engagement model (se ausente) E reviewer (se ausente — anti auto-PRR)
+- [ ] `prr-conductor` invocado via `Task(subagent_type=...)` com prompt completo (6 axes literalmente + modo offline)
+- [ ] Output forwarded transparentemente do agent
+- [ ] Próximos passos sugerem cross-ref para `/observabilidade omm`, `/concluir-marco`, P0/P1/P2 priorização
+</success_criteria>