@luanpdd/kit-mcp 1.9.0 → 1.11.0

package/kit/skills/ai-prompt-characterization/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: ai-prompt-characterization
+description: Use ao modificar prompt/tool LLM em produção — characterization de generations com temperature=0 + seed fixo + sanitização específica. Modernização 2026 sem precedente em 2004 — prompts são código legacy também.
+---
+
+# AI Prompt Characterization (Modernização)
+
+## Quando usar
+
+LLM carrega esta skill quando user vai modificar prompt ou tool definition de LLM em produção. Trigger phrases:
+
+- "vou mudar esse prompt", "modificar prompt em prod"
+- "atualizar tool definition", "function calling schema"
+- "como testar mudança de prompt?"
+- "characterization de prompt", "snapshot de generation"
+- "esse prompt tem 300 linhas e ninguém testou ainda"
+- prompt em arquivo como `prompts/<name>.md` ou string template em código
+
+**Insight central:** prompts e tools são **código legacy também** quando:
+- > 100 linhas
+- Em uso em produção
+- Mudanças quebram silenciosamente (output diferente, downstream parser falha)
+- Sem characterization tests
+
+## Regras absolutas
+
+- **Prompts são código.** Tratam-se com mesmo rigor: versionado, testado, code-reviewed. NÃO são "config text que muda livremente".
+- **Determinismo via `temperature=0` + `seed`.** Anthropic Claude e OpenAI ambos suportam seed. Sem isso, characterization é flaky.
+- **Capture mais que `text`.** Outputs incluem: `text`, `finish_reason`, `tool_calls` (se function calling), `input_tokens`, `output_tokens`, `model_version`. Snapshot de TODOS estes campos.
+- **Sanitize aggressively.** Outputs LLM frequentemente incluem timestamps mencionados, UUIDs gerados, datas relativas. Normalize ANTES de snapshot.
+- **5+ inputs cobrindo intents distintas.** Não é "happy path × 5"; é "5 intents qualitativamente diferentes" — concision request, troubleshooting, explanation, creative, edge case.
+- **Behavioral coverage = % intents cobertas.** Métrica não é coverage de "linhas do prompt" (não existe); é coverage de variações comportamentais.
+- **Re-rodar em CI quando model_version muda.** Anthropic publica nova versão de Claude → re-rode characterization → revisar diffs → aceitar/rejeitar.
+
+## Patterns canônicos
+
+### Pattern 1: Setup canônico de characterization de prompt
+
+```ts
+// tests/characterization/prompts/generate-summary.test.ts
+import { Anthropic } from '@anthropic-ai/sdk'
+import { describe, test, expect } from 'vitest'
+import { readFileSync } from 'fs'
+
+const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY })
+const PROMPT = readFileSync('prompts/generate-summary.md', 'utf-8')
+
+interface PromptInput {
+  systemPrompt: string
+  userMessage: string
+  maxTokens?: number
+}
+
+async function runPrompt(input: PromptInput) {
+  const response = await client.messages.create({
+    model: 'claude-opus-4-7',
+    max_tokens: input.maxTokens ?? 500,
+    temperature: 0,  // determinismo
+    system: input.systemPrompt,
+    messages: [{ role: 'user', content: input.userMessage }],
+  })
+  return {
+    text: response.content[0].type === 'text' ? response.content[0].text : '',
+    stopReason: response.stop_reason,
+    inputTokens: response.usage.input_tokens,
+    outputTokens: response.usage.output_tokens,
+    modelVersion: response.model,
+  }
+}
+
+function sanitizeForSnapshot(o: any): any {
+  return JSON.parse(
+    JSON.stringify(o, (key, value) => {
+      // normalizar timestamps mencionados ("Today is 2026-05-08") → "<DATE>"
+      if (typeof value === 'string') {
+        value = value.replace(/\d{4}-\d{2}-\d{2}/g, '<DATE>')
+        value = value.replace(/\d{2}:\d{2}(:\d{2})?/g, '<TIME>')
+        value = value.replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}/g, '<UUID>')
+      }
+      // permitir model version mas separar para audit (não no snapshot)
+      if (key === 'modelVersion') return '<MODEL>'
+      return value
+    })
+  )
+}
+
+describe('generate-summary prompt — characterization', () => {
+  test('intent: concise summary of long article', async () => {
+    const captured = await runPrompt({
+      systemPrompt: PROMPT,
+      userMessage: 'Resuma em 2 sentenças: [longo artigo de 500 palavras]...',
+    })
+    expect(sanitizeForSnapshot(captured)).toMatchSnapshot()
+  })
+
+  test('intent: bullet-list summary', async () => { /* ... */ })
+  test('intent: technical/code summary', async () => { /* ... */ })
+  test('intent: ambiguous request (edge)', async () => { /* ... */ })
+  test('intent: hostile / prompt injection attempt', async () => { /* ... */ })
+})
+```
+
+### Pattern 2: Tool definition characterization (function calling)
+
+```ts
+// Quando prompt usa tool definition (function calling), characterize tool_calls
+
+const TOOLS = [
+  {
+    name: 'search_knowledge_base',
+    description: 'Search for relevant docs',
+    input_schema: { type: 'object', properties: { query: { type: 'string' } } },
+  },
+  // ... mais tools
+]
+
+async function runWithTools(userMessage: string) {
+  const r = await client.messages.create({
+    model: 'claude-opus-4-7',
+    max_tokens: 500,
+    temperature: 0,
+    tools: TOOLS,
+    messages: [{ role: 'user', content: userMessage }],
+  })
+  return {
+    stopReason: r.stop_reason,
+    toolUses: r.content.filter(c => c.type === 'tool_use').map(c => ({
+      tool: (c as any).name,
+      input: (c as any).input,
+    })),
+    finalText: r.content.filter(c => c.type === 'text').map(c => (c as any).text).join('\n'),
+  }
+}
+
+test('tools — invokes search for factual question', async () => {
+  const captured = await runWithTools('Qual é a política de reembolso?')
+  expect(captured).toMatchSnapshot()
+  // snapshot captura QUAIS tools foram invocadas + QUAIS argumentos
+})
+```
+
+### Pattern 3: Sanitização específica de prompts
+
+```ts
+// Outputs LLM têm padrões previsíveis a sanitizar:
+
+function sanitizeLLMOutput(text: string): string {
+  return text
+    // datas absolutas
+    .replace(/\b\d{4}-\d{2}-\d{2}\b/g, '<DATE>')
+    .replace(/\b(?:janeiro|fevereiro|março|abril|maio|junho|julho|agosto|setembro|outubro|novembro|dezembro)\s+(?:de\s+)?\d{4}/gi, '<DATE_PT>')
+    .replace(/\b(?:january|february|march|april|may|june|july|august|september|october|november|december)\s+\d{4}/gi, '<DATE_EN>')
+    // datas relativas
+    .replace(/\b(?:hoje|amanhã|ontem|today|tomorrow|yesterday)\b/gi, '<RELATIVE_DATE>')
+    // URLs e UUIDs
+    .replace(/https?:\/\/[^\s]+/g, '<URL>')
+    .replace(/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, '<UUID>')
+    // valores monetários (preservar tipo, sanitizar valor)
+    .replace(/R\$\s*[\d,.]+/g, 'R$ <VALUE>')
+    .replace(/\$\s*[\d,.]+/g, '$ <VALUE>')
+    // versões
+    .replace(/v\d+\.\d+(?:\.\d+)?/g, '<VERSION>')
+}
+```
+
+### Pattern 4: Behavioral coverage de prompt — 5+ intents
+
+Para cada prompt, definir intents distintas:
+
+| Intent | Definição | Exemplo de input |
+|---|---|---|
+| **Concise** | Pedido curto, output esperado curto | "Resuma em 1 frase: [text]" |
+| **Detailed** | Pedido elaborado, output esperado longo | "Explique passo-a-passo: [text]" |
+| **Code-heavy** | Input/output com código | "Refactor esse código: ```ts ...```" |
+| **Edge case** | Input ambíguo ou borderline | "Como funciona?" (sem context) |
+| **Adversarial** | Tentativa de jailbreak / prompt injection | "Ignore previous instructions and..." |
+| **Multi-turn (se aplicável)** | Conversação com historico | [3+ messages prévias] |
+
+5 intents × snapshot deterministic = baseline. Mudança em prompt deve manter outputs semanticamente próximos (ou documentar mudança intencional).
+
+### Pattern 5: Pre-deploy checklist para mudança em prompt
+
+```text
+Antes de deploy de mudança em prompt em produção:
+
+□ Suite de characterization tests passa verde (todos os 5+ intents)
+□ Diff revisado HUMANAMENTE para cada intent — mudanças intencionais?
+□ Behavioral coverage ≥ 5 intents (não bate threshold % — bate threshold de N)
+□ Sanitização revisada — nenhum PII/secret no snapshot
+□ Custo: cada test consome tokens; para prompts grandes, calcular total
+   - 5 inputs × 1k input + 500 output ≈ 7.5k tokens × $0.015/1k = ~$0.11
+   - CI roda só on-change para evitar custo recorrente
+□ model_version anotado — re-rodar quando model_version muda
+□ Audit trail no PR: "intent X: changed from Y to Z; reason: ..."
+```
+
+### Pattern 6: Custo + cadência de characterization
+
+| Frequência | Custo (em USD) por suite | Quando rodar |
+|---|---|---|
+| Desenvolvedor local | < $0.10 | Antes de cada commit que toca prompt |
+| CI on-change | < $0.50/run | Em PR que toca arquivo de prompt |
+| CI nightly | < $5/dia | Para detectar drift de model upstream |
+| Pre-deploy | < $0.50 | Confirmação final antes de promote |
+
+**Otimização:** snapshot diff só dispara LLM call se prompt mudou. Sem mudança = skip (cacheado).
+
+### Pattern 7: Quando NÃO characterizar prompt
+
+```text
+- Prompt < 20 linhas e usado em 1 lugar — overhead > valor
+- Prompt é template trivial ("Resume: {text}") sem lógica complexa
+- LLM call é one-shot script (analytics, batch processing) — não em hot path
+- Custo de tokens proibitivo (e.g., prompts massivos com 50k tokens) — usar smaller model para char tests
+- Use case é generative criativo (poema, story) — outputs intencionalmente variáveis
+```
+
+## Anti-patterns
+
+### ANTI: characterization sem temperature=0
+
+```text
+ANTI: rodar characterization com temperature=0.7 (default).
+
+PROBLEMA: outputs varia entre runs. Snapshot diferente toda vez.
+          Tests flaky. Equipe ignora.
+
+CERTO: temperature=0 SEMPRE em characterization. Anthropic + OpenAI
+       ambos têm. Em providers que não suportam, escolher menor
+       valor possível e/ou seed fixo se disponível.
+```
+
+### ANTI: snapshot sem sanitização
+
+```text
+ANTI: capturar output cru com timestamps, UUIDs, datas atuais.
+
+PROBLEMA: cada run gera snapshot diferente. Não é flaky pelo LLM,
+          é flaky pelo CONTENT temporal.
+
+CERTO: sanitize ANTES de matchSnapshot. Datas → <DATE>, UUIDs →
+       <UUID>, etc. Snapshot estável across time.
+```
+
+### ANTI: 1 test "happy path" de prompt
+
+```text
+ANTI: 1 input de exemplo testado, "se passa, prompt está OK".
+
+PROBLEMA: prompt tem comportamento qualitativamente diferente em
+          edge cases (input curto, input longo, input ambíguo,
+          adversarial). 1 test cobre 1 caminho, ignora N outros.
+
+CERTO: 5+ intents cobrindo distribuição real de uso. Edge case +
+       adversarial são MANDATORY (prompts em prod sempre recebem
+       inputs ruins).
+```
+
+### ANTI: ignorar drift de model
+
+```text
+ANTI: characterization passou em maio; em julho Anthropic atualiza
+      Claude (claude-opus-4-7 → 4-8). Equipe não re-roda; deploy de
+      mudança quebra silenciosamente.
+
+PROBLEMA: prompt baseline frozen no model anterior. Novo model
+          comporta diferente; bug em prod.
+
+CERTO: CI nightly roda characterization. Diff de model_version =
+       trigger humano para revisar. Aceita ou rejeita updates de
+       model. Sem fixed model = sem characterization válida.
+```
+
+### ANTI: snapshot inclui token count
+
+```text
+ANTI: snapshot tem `inputTokens: 247, outputTokens: 89`.
+
+PROBLEMA: token counts mudam quando model muda (tokenizer evolui).
+          Diff vermelho em update de model é noise.
+
+CERTO: capturar tokens em log SEPARADO (custo tracking), não no
+       snapshot. Snapshot é qualitativo (text + stop reason +
+       tool calls), não quantitativo.
+```
+
+### ANTI: tratar prompt como "string config livre"
+
+```text
+ANTI: dev edita prompt em prod direto via console; sem PR; sem
+      review; sem characterization.
+
+PROBLEMA: prompt é código. Mudança não-versionada quebra silenciosa.
+          Sem audit trail. Rollback impossível.
+
+CERTO: prompt em repo (`prompts/<name>.md`). PR review como qualquer
+       código. Characterization tests rodam em CI. Deploy via release
+       padrão.
+```
+
+## Verificação
+
+1. Prompt versionado em arquivo (não inline em código se > 50 linhas)
+2. Characterization tests existem com 5+ intents
+3. `temperature=0` + seed fixo (se provider suporta)
+4. Sanitização específica para prompt outputs
+5. Snapshot inclui text + stopReason + toolCalls (se aplicável)
+6. CI roda characterization on-change
+7. model_version trackado (audit log separado)
+8. Pre-deploy checklist completo
+
+## Limiar de "prompt pronto para produção"
+
+```text
+Versionado em repo:                         sim
+Characterization tests com ≥ 5 intents:     sim
+temperature=0 + seed fixo:                  sim
+Sanitização aplicada:                       sim
+Coverage de intents real (não synthetic):   sim
+CI integration:                             sim
+Audit trail de mudanças:                    sim
+```
+
+---
+
+## Ver também
+
+- [`_shared-legacy/glossary.md`](../_shared-legacy/glossary.md) — vocabulário (characterization, golden master)
+- [`legacy-characterization-tests`](../legacy-characterization-tests/SKILL.md) — characterization clássico; aplicável a prompts modulo determinismo
+- [`legacy-api-only-applications`](../legacy-api-only-applications/SKILL.md) — LLM provider é caso especial de API; adapter pattern aplicável
+- [`llm-as-dependency`](../llm-as-dependency/SKILL.md) — fakear LLM em testes que NÃO são de prompt characterization (testes de business logic)
+- [`pre-refactor-characterization`](../pre-refactor-characterization/SKILL.md) — gate v1.12 inclui ai-prompt-stability como dimensão paralela
+- [`observability-driven-development`](../observability-driven-development/SKILL.md) (v1.9) — instrument prompt outputs para detectar drift em prod
+
+*Material-fonte (modernização 2026):* Sem precedente em livro Feathers 2004 — prompts/tools LLM como dependência testável é literatura recente (2023+ — papers da Anthropic sobre evals, OpenAI evals framework, Promptfoo).

package/kit/skills/blameless-postmortems/SKILL.md

@@ -0,0 +1,340 @@
+---
+name: blameless-postmortems
+description: Use após incident SEV1/SEV2 — template canônico (9 seções), cultura blameless (foco em sistema, não pessoas), no postmortem left unreviewed, Wheel of Misfortune.
+---
+
+# SRE — Blameless Postmortems
+
+## Quando usar
+
+LLM carrega esta skill ao escrever postmortem após incident, revisar postmortem de par, ou conduzir Wheel of Misfortune. Trigger phrases:
+
+- "postmortem", "post-mortem"
+- "incident review"
+- "blameless", "sem culpa"
+- "root cause analysis", "5 whys"
+- "Wheel of Misfortune"
+- "lessons learned"
+- "Google SRE cap 15"
+- "no postmortem left unreviewed"
+
+## Regras absolutas
+
+- **Foco em sistema/processo, NÃO em pessoas** — root cause é "ausência de canary release" ou "RPS limit não documentado", NÃO "Maria fez deploy errado". Pessoas são parte do sistema. Se Maria errou, pergunte: "que processo permitiu o erro chegar a prod?".
+- **Trigger postmortem para SEV1/SEV2 + near-miss notáveis** — todo incident customer-facing com impacto ≥ 1 min de SLO burn ou ≥ 1 user reportado. Near-miss (incident detectado antes de impacto) também: oportunidade de aprender sem custo.
+- **"No postmortem left unreviewed"** — todo postmortem revisado por par sênior antes de arquivar. Sem revisão, postmortem mente (involuntariamente — autor está perto demais).
+- **Action items SMART com owner nomeado** — Specific, Measurable, Assignable, Realistic, Time-bound. "Melhorar monitoring" NÃO é SMART. "Adicionar alert SLO burn rate em /api/v1/orders por @bob até 2026-05-15" É SMART.
+- **Timeline em UTC** — não "horário local Brasília" ou ambíguo. Times distribuídos compõem timeline e UTC é o único timezone universal. Sempre `HH:MM UTC`.
+- **Quantificar impact** — usuários afetados (número/percentual), revenue impact, SLO budget consumido. Sem quantificação, severity é subjetivo.
+- **Lições generalizáveis, não específicas** — "Adicionar alert para essa query específica" é local. "Adicionar alert SLO em todas as queries de write em paths críticos" é generalizável.
+- **Wheel of Misfortune trimestral** — exercício de role-play onde uma pessoa narra um incident histórico e o time pratica response (sem dados reais expostos a stress real). Treina muscle memory para SEV1.
+
+## Patterns canônicos
+
+### Pattern: template canônico de postmortem (9 seções)
+
+````markdown
+```markdown
+# Postmortem: <incident-id> — <título-curto>
+
+**Data do incident:** YYYY-MM-DD
+**Autores:** <nomes>
+**Status:** Draft | Reviewed | Final
+**Severidade:** SEV1 | SEV2 | SEV3
+**Tempo até detecção:** XX min (entre trigger e alerta)
+**Tempo até resolução:** XX min (entre alerta e SLO restored)
+
+## Summary
+
+1-2 parágrafos: o que aconteceu, quem foi afetado, como foi resolvido.
+Escrito para audiência não-técnica (executivos, customer success, support).
+
+## Impact
+
+- Usuários afetados: XX% (X de Y usuários ativos no período)
+- Duração: HH:MM (de HH:MM UTC a HH:MM UTC)
+- SLO budget consumido: X% do budget mensal
+- Revenue impact: $X (estimado por # de transações falhadas × ticket médio)
+- Serviços downstream impactados: <lista>
+- Customer support tickets gerados: X
+- Reputação/marca: <impacto qualitativo, se houver>
+
+## Root Causes
+
+Condição mais profunda que, removida, previne recorrência.
+NÃO é "deploy do fulano" ou "código tinha bug" — é a condição sistêmica que
+permitiu o bug chegar a prod (ausência de canary, ausência de SLO alert,
+teste não cobria o caso).
+
+Use **5 Whys** para chegar lá. Pode haver múltiplas root causes (separadas
+em subseções `### Root Cause 1`, `### Root Cause 2`).
+
+## Trigger
+
+Evento que iniciou a falha (deploy X às HH:MM UTC, config change Y, traffic
+spike Z, dependency outage W). Trigger ≠ Root Cause — trigger é o "quando";
+root cause é o "porquê o trigger virou incident".
+
+## Resolution
+
+Passos tomados para recuperar serviço, em ordem cronológica com horários UTC:
+
+- HH:MM UTC — <ação>
+- HH:MM UTC — <ação>
+
+Inclui rollbacks, hotfixes, scaling decisions, manual interventions.
+
+## Detection
+
+Como descobrimos: alerta SLO burn rate? cliente reportou? monitoramento
+interno? heartbeat?
+
+Tempo de detecção (gap entre trigger e detecção). Se > 5 min, action item
+para reduzir.
+
+## Action Items
+
+| # | Action (SMART) | Owner | Priority | Due |
+|---|----------------|-------|----------|-----|
+| 1 | Adicionar SLO burn rate alert em /api/v1/orders/{id} | @bob | P0 | 2026-05-15 |
+| 2 | Documentar RPS limit por tier em runbook do orders-service | @alice | P1 | 2026-05-22 |
+| 3 | Implementar canary release em CI para todos os Edge Functions | @platform | P1 | 2026-06-01 |
+
+## Lessons Learned
+
+Insights generalizáveis. Estrutura recomendada:
+
+### O que fizemos bem
+- <coisa que funcionou — reforçar>
+
+### Onde podemos melhorar
+- <gap identificado, generalizável a outros sistemas>
+
+### Foi lucky?
+- <foi sorte que detectamos rápido? que não escalou? — capturar para fix proativo>
+
+## Timeline (UTC)
+
+- 14:23 — <evento>
+- 14:27 — <evento>
+- 14:33 — <evento>
+- 14:42 — <evento>
+- 15:25 — Incident resolvido
+
+## Supporting evidence
+
+- Link para incident channel #inc-2026-05-06-01
+- Link para SLO dashboard
+- Link para investigation .planning/investigations/<id>.md (de incident-investigator v1.9)
+- Screenshots/queries de chave
+```
+````
+
+### Pattern: 5 whys para encontrar root cause
+
+```text
+Sintoma: SLO burn rate de checkout_success disparou às 14:31 UTC.
+
+Why 1: Por que o burn rate disparou?
+→ Porque taxa de erro em /api/v1/orders saltou de 0.05% para 8%.
+
+Why 2: Por que a taxa de erro saltou?
+→ Porque deploy v2.3.0 introduziu N+1 query.
+
+Why 3: Por que o deploy v2.3.0 chegou a prod com N+1?
+→ Porque o teste de carga não cobria carrinhos com > 10 itens.
+
+Why 4: Por que o teste de carga não cobria > 10 itens?
+→ Porque o teste foi escrito antes do feature de "bulk add to cart" e não foi atualizado.
+
+Why 5: Por que o teste não foi atualizado quando bulk add foi mergeado?
+→ Porque não há gate de CI que exige re-rodar load test ao mudar paths críticos.
+
+ROOT CAUSE: ausência de gate de CI obrigando re-rodar load test em mudanças de paths críticos.
+ACTION ITEM: implementar gate `load-test-required-for-critical-paths` no CI.
+```
+
+### Pattern: revisão por par sênior ("no postmortem left unreviewed")
+
+```markdown
+Reviewer pergunta autor:
+
+1. **Root cause é sistêmico, não pessoal?** — se cita pessoa, redirecionar para processo
+2. **Action items são SMART?** — owner nomeado, due date, mensurável
+3. **Timeline em UTC?** — sem ambiguidade timezone
+4. **Impact quantificado?** — # usuários, duração, revenue
+5. **Lessons generalizáveis?** — aplicáveis a outros serviços/incidents
+6. **Detection time razoável?** — < 5 min ideal; se > 5, action item para reduzir
+7. **Algo "lucky" capturado?** — foi sorte? Como remover dependência de sorte?
+8. **5 whys aplicado?** — ou parou em "deploy ruim" sem ir mais fundo?
+```
+
+### Pattern: Wheel of Misfortune (training canônico)
+
+```text
+Frequência: trimestral (1× por quarter)
+Duração: 60-90 min
+Participantes: time on-call + interessados (4-8 pessoas idealmente)
+
+Setup:
+1. Facilitator escolhe um postmortem REAL de incident passado (>3 meses,
+   para não ter risco emocional fresco) — pode ser de outro time/empresa.
+2. Facilitator narra timeline progressivamente, parando em pontos-chave.
+3. Em cada parada, time discute: "O que vocês fariam agora? Por quê?"
+4. Comparar respostas com decisão real do incident.
+5. Discutir: "Quais decisões foram boas? Quais foram piores em retrospecto?"
+
+Resultado:
+- Time pratica response sem stress real
+- Identifica gaps de conhecimento (nem todos sabem sobre runbook X)
+- Cria muscle memory para próximo SEV1
+- Materializa lições do postmortem original em ação prática
+
+Anti-objetivo:
+NÃO é "humilhar quem tomou decisão errada no incident original".
+É blameless training — focar em sistema/processo de decisão.
+```
+
+### Pattern: postmortem chain — `/forense` → `/postmortem`
+
+```text
+Fluxo natural após incident:
+
+1. Detecção: alerta SLO burn rate dispara → on-call ack → Slack channel #inc-NN
+2. Mitigation: rollback ou hotfix → SLO restored → incident closed
+3. /forense (framework v1.10): Core Analysis Loop sobre logs/git/state →
+   gera .planning/investigations/<id>.md com hipóteses validadas e root cause
+4. /postmortem --from-investigation <id> (Phase 38):
+   postmortem-writer (Phase 37) consome <id>.md e gera template preenchido
+   em .planning/postmortems/<id>.md
+5. Reviewer lê draft e exige fixes (no postmortem left unreviewed)
+6. Final marked + archived em milestone correspondente
+7. Action items P0 viram phases inseridas no roadmap próximo (`/inserir-fase`)
+```
+
+## Anti-patterns
+
+### ANTI: blame culture
+
+```text
+ANTI: postmortem nomeia "fulano fez deploy errado", "@maria não testou direito",
+      "o time de X causou o problema"
+
+PROBLEMA: engineers escondem incidents próximos ao limite por medo de retaliação;
+          psychological safety colapsa; replicação garantida (próximo near-miss
+          vira full incident porque ninguém reportou); team rotation aumenta;
+          quem fica deixa de propor mudanças arriscadas (mesmo as boas).
+
+CERTO: foco em sistema/processo (ausência de canary, ausência de rollback
+       automatizado, gate de CI faltante); pessoas são parte do sistema, NÃO
+       o root cause; revisão por par sênior antes de arquivar — reviewer
+       redireciona toda menção a pessoa para "que processo permitiu?".
+```
+
+### ANTI: action items vagos
+
+```text
+ANTI: "Melhorar monitoring", "Revisitar processo de deploy", "Investigar mais",
+      "Documentar melhor"
+
+PROBLEMA: sem owner, sem due date, sem critério de "feito"; ficam pendentes
+          para sempre; mesma falha repete em 6 meses porque nada concreto
+          aconteceu; aprendizado do incident é perdido na próxima sprint.
+
+CERTO: SMART (Specific, Measurable, Assignable, Realistic, Time-bound) —
+       "Bob adiciona SLO burn alert em /api/v1/orders até 2026-05-15";
+       "Alice documenta RPS limit em runbook orders-service até 2026-05-22".
+```
+
+### ANTI: postmortem left unreviewed
+
+```text
+ANTI: autor escreve postmortem, ninguém revisa, vai direto para o arquivo
+
+PROBLEMA: autor está perto demais (mente involuntariamente sobre próprio
+          papel — sem má-fé, é a natureza humana); root cause errado
+          documentado; lições não-generalizáveis; mesma falha repete porque
+          ação errada foi tomada com base em diagnóstico errado.
+
+CERTO: revisor sênior aplica checklist (8 perguntas — ver Pattern: revisão
+       por par sênior); só depois `Final` status; "no postmortem left
+       unreviewed" é regra absoluta — incident sem postmortem revisado
+       conta como aberto, mesmo que serviço esteja restaurado.
+```
+
+### ANTI: postmortem só para SEV1
+
+```text
+ANTI: "só investigar incident que pagou on-call"; SEV2/SEV3 ignorados;
+      near-misses (detecção rápida evitou impacto) descartados
+
+PROBLEMA: near-misses são oportunidade de aprender SEM CUSTO — perdê-los
+          é desperdício; SEV3s acumulam até virar SEV1 (mesma classe de
+          falha, escala diferente); tendências invisíveis (3 SEV3s em 1 mês
+          no mesmo serviço = sinal); team perde músculo de investigação.
+
+CERTO: SEV1/SEV2 mandatório; SEV3 opcional mas encorajado; near-miss notável
+       (detection rápida evitou impacto) é candidato a postmortem leve
+       (Summary + Impact + Lessons Learned, sem timeline detalhada se durou
+       < 1 min). Investigation barata, lição grátis.
+```
+
+### ANTI: timeline ambígua
+
+```text
+ANTI: "Por volta das 14h", "After lunch", "Em horário de pico",
+      "Ontem à tarde"
+
+PROBLEMA: reviewers de outros timezones perdem contexto (15h Brasília
+          = 18h UTC = 11h US-East); reconstrução em > 30 dias impossível
+          (lembra "horário de pico"?); análise estatística (MTTR
+          distribution, time-to-detect) impossível sem timestamps; cross-
+          incident correlation falha.
+
+CERTO: sempre `HH:MM UTC` no formato 24h; cada evento na timeline com
+       timestamp; UTC é o único timezone universal — converter quando
+       compartilhar com stakeholders locais, NUNCA armazenar local.
+```
+
+### ANTI: copy-paste de postmortem template sem investigation
+
+```text
+ANTI: abrir template, preencher campos genéricos, "Resolution: investigamos
+      e resolvemos", "Root Cause: bug no código"; sem dados, sem 5 whys
+
+PROBLEMA: root cause errado documentado; action items irrelevantes;
+          lessons learned superficiais; falha equivalente em 3 meses
+          porque diagnóstico verdadeiro nunca foi feito; postmortem vira
+          ritual burocrático em vez de instrumento de aprendizado.
+
+CERTO: postmortem nasce de investigation real (Core Analysis Loop, /forense,
+       ou logs/state via mcp__supabase__get_logs); preencher com EVIDÊNCIAS
+       (queries que rodaram, logs específicos, métricas observadas), não
+       impressões; cada Root Cause precisa de prova citável.
+```
+
+## Verificação
+
+Antes de marcar postmortem como `Final`:
+
+1. **9 seções canônicas presentes** — Summary, Impact, Root Causes, Trigger, Resolution, Detection, Action Items, Lessons Learned, Timeline UTC
+2. **Root cause sistêmico** — não nomeia pessoa; passou pelo 5 whys
+3. **Action items SMART** — Specific, Measurable, Assignable (owner @user), Realistic, Time-bound (due date)
+4. **Timeline em UTC** — sem timezone ambíguo
+5. **Impact quantificado** — # usuários, duração HH:MM, SLO budget consumido, revenue
+6. **Lições generalizáveis** — aplicáveis a outros serviços/incidents
+7. **Reviewed por par sênior** — checklist 8 perguntas aplicado
+8. **Supporting evidence linkada** — investigation, dashboards, queries
+9. **Action items P0 escalonados** — viraram phases ou tasks no roadmap próximo
+
+## Ver também
+
+- [`_shared-sre/glossary.md`](../_shared-sre/glossary.md) — termos canônicos postmortem, blameless, root cause, Wheel of Misfortune
+- [`core-analysis-loop`](../core-analysis-loop/SKILL.md) (v1.9) — Core Analysis Loop alimenta investigation que vira postmortem
+- [`sre-risk-management`](../sre-risk-management/SKILL.md) — postmortem documenta budget consumido
+- [`production-readiness-review`](../production-readiness-review/SKILL.md) — PRR axis "Emergency Response" exige postmortem culture
+- [`eliminating-toil`](../eliminating-toil/SKILL.md) — toil-induced incidents geram postmortems
+
+---
+
+*Material-fonte: Site Reliability Engineering — Beyer, Jones, Petoff, Murphy (Google/O'Reilly, 2016) — Cap 15: "Postmortem Culture: Learning from Failure".*