@luanpdd/kit-mcp 1.10.0 → 1.12.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/cascading-failures/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: cascading-failures
+description: Use ao desenhar/auditar serviços com deps externas — cap 22 livro Google SRE. Triggers de cascade, loops de feedback, prevenção via timeout/jitter/deadline/circuit breaker, immediate response.
+---
+
+# SRE — Addressing Cascading Failures
+
+## Quando usar
+
+LLM carrega esta skill ao analisar serviço com risco de cascade, ou durante incident em progresso onde failure se amplifica. Trigger phrases:
+
+- "cascading failure", "falha em cascata"
+- "retry storm", "thundering herd"
+- "outage propagando", "serviço caindo um após outro"
+- "como prevenir cascade?", "circuit breaker"
+- "cap 22 Google SRE"
+- "deadline propagation", "load shedding"
+
+## Regras absolutas
+
+- **Cascade tem 5 triggers canônicos:** server overload, resource exhaustion, service unavailability, latency spike sem timeout, retry sem jitter. Memorize-os.
+- **Prevenção custa 1×, recuperação custa 100×.** Toda dep crítica DEVE ter timeout + retry com jitter + circuit breaker + deadline propagation. Sem isso, cascade é questão de tempo.
+- **Saturation (cap 6 v1.10) é early warning de cascade.** Quando saturation > 80%, ainda há tempo. Quando hit 100%, já está em cascade.
+- **Retry SEMPRE com jitter.** Full jitter por default (`delay = random(0, base × 2^attempt)`). Sem jitter = thundering herd garantido.
+- **Retry SEMPRE com deadline.** Retry sem timeout amplifica cascade — call de 30s vira 90s vira 270s. Deadline propagation evita work zumbi.
+- **Circuit breaker DEFAULT em qualquer dep externa.** Estados closed/open/half-open. Open dispara após N failures consecutivas; half-open permite 1 probe; closed após probe verde.
+- **Load shedding > 503 graceful > queue overflow.** Server saturated DEVE retornar 503 com Retry-After ANTES de aceitar request que vai falhar. Aceitar e cair = pior que rejeitar.
+- **Slow start em recovery.** Após outage, ramp-up gradual (10% → 25% → 50% → 100%). Full blast em recovery = falha de novo (caches frios, conn pools).
+
+## Patterns canônicos
+
+### Pattern 1: 5 triggers canônicos de cascade (cap 22)
+
+```text
+1. SERVER OVERLOAD
+   Sintoma: load > capacity → latency p99 sobe 10× → errors 5xx → crashes
+   Trigger upstream: traffic spike, outage de cache, batch job rodou em horário ruim
+   Detect: Saturation gauge (cap 6) > 80% por > 5 min
+   Resposta: load shedding + escalação manual
+
+2. RESOURCE EXHAUSTION
+   Tipos: CPU, memory, file descriptors, threads, connection pool
+   Sintoma específico:
+     CPU 100% → latency sobe; FDs esgotados → "too many open files"
+     Memory OOM → process kill; threads → deadlock; conn pool empty → wait
+   Detect: monitor por recurso específico; alarmes em 80% de cada
+   Resposta: configure limits; circuit breaker; rate limit caller
+
+3. SERVICE UNAVAILABILITY (DEP DOWN)
+   Sintoma: dep externa retorna 5xx ou timeout. Sem circuit breaker:
+   N clients × M retries × T deadline = explosão de calls
+   Detect: error rate de dep > 50% por 1 min; latency dep > p99 normal × 5
+   Resposta: circuit breaker abre; fallback (cache, default value, degraded mode)
+
+4. LATENCY SPIKE SEM TIMEOUT
+   Sintoma: dep responde lento mas não falha. Caller fica esperando.
+   Conn pool de caller esgota; novos requests também ficam pendurados.
+   Detect: dep latency p99 > baseline × 5
+   Resposta: timeout AGRESSIVO (ex: p99.9 baseline + 50%); circuit breaker
+
+5. RETRY SEM JITTER
+   Sintoma: 1000 clients retentam ao mesmo tempo após dep recovery.
+   Server recém-recuperado é matado pelo wake-up.
+   Detect: traffic spike no momento exato de recovery
+   Resposta: full jitter; retry budget global; slow start
+```
+
+### Pattern 2: Defesa em camadas (cap 22)
+
+Cada chamada externa precisa de **5 camadas de defesa**:
+
+```ts
+// Camada 1: Timeout agressivo
+const TIMEOUT_MS = 2000  // p99.9 baseline + 50%
+
+// Camada 2: Retry com jitter + deadline
+async function callDep(input: Input, deadline: number): Promise<Output> {
+  const startMs = performance.now()
+  let attempt = 0
+  let lastError: Error | undefined
+
+  while (true) {
+    const remaining = deadline - performance.now()
+    if (remaining <= 0) throw new DeadlineExceededError(lastError)
+
+    const callTimeoutMs = Math.min(TIMEOUT_MS, remaining)
+
+    try {
+      // Camada 3: Circuit breaker
+      if (circuitBreaker.isOpen()) throw new CircuitOpenError()
+
+      const result = await withTimeout(
+        depClient.call(input),
+        callTimeoutMs
+      )
+      circuitBreaker.recordSuccess()
+      return result
+    } catch (e) {
+      lastError = e as Error
+      circuitBreaker.recordFailure()
+
+      // Camada 4: Não retentar erros não-retentáveis
+      if (!isRetryable(e)) throw e
+
+      // Camada 5: Retry budget global
+      if (!retryBudget.tryAcquire()) throw new RetryBudgetExhaustedError(e)
+
+      attempt++
+      if (attempt >= MAX_RETRIES) throw e
+
+      // Full jitter
+      const baseMs = 100 * Math.pow(2, attempt - 1)
+      const jitterMs = Math.random() * baseMs * 2
+      await sleep(Math.min(jitterMs, remaining))
+    }
+  }
+}
+
+function isRetryable(e: any): boolean {
+  // 4xx (validation, auth, not_found) → não retry
+  // 5xx, timeout, connection reset → retry
+  if (e.statusCode >= 400 && e.statusCode < 500) return false
+  if (e.statusCode === 429) return true  // rate limited — retry com backoff
+  return true
+}
+```
+
+### Pattern 3: Circuit breaker — estados canônicos
+
+```text
+                    ┌────────────────────┐
+                    │    CLOSED (normal) │
+                    │  request flows OK  │
+                    └─────────┬──────────┘
+                              │ N consecutive failures
+                              ▼
+                    ┌────────────────────┐
+                    │       OPEN         │
+                    │  fail fast for T   │
+                    │   no calls to dep  │
+                    └─────────┬──────────┘
+                              │ T elapsed
+                              ▼
+                    ┌────────────────────┐
+                    │    HALF-OPEN       │
+                    │  allow 1-N probes  │
+                    └────┬───────────┬───┘
+                  success │           │ failure
+                          ▼           ▼
+                       CLOSED        OPEN
+
+Configuração canônica:
+  N (failures-to-open):    5-10 consecutive
+  T (open duration):       30-60s
+  half-open probe count:   1-5
+  failure detection window: 30-60s rolling
+```
+
+### Pattern 4: Deadline propagation across hops
+
+```text
+Client → Service A (deadline=30s) → Service B (deadline=?) → Service C (deadline=?)
+
+WRONG (cascade amplification):
+  A: receives deadline=30s, calls B with timeout=30s
+  B: receives no deadline, default 30s, calls C with timeout=30s
+  C: takes 30s
+  Total: 30s in C, plus parent overhead. Client gone at 30s, A-B-C still working.
+
+RIGHT (deadline propagation):
+  A: receives TTL=30s; takes 100ms processing; calls B with TTL=29.9s
+  B: receives TTL=29.9s; takes 50ms; calls C with TTL=29.85s
+  C: receives TTL=29.85s; works until that limit, no more
+  When TTL hits 0, ALL hops fail fast. No zombie work.
+
+Implementação:
+  - HTTP: header `Deadline-Ms` ou similar (custom)
+  - gRPC: built-in `grpc-timeout` header
+  - JS/TS: AbortSignal.timeout(remainingMs)
+  - Each hop: deadline = received_deadline - elapsed_local; abort se ≤ 0
+```
+
+### Pattern 5: Defesas server-side
+
+Server protege a si próprio (não confia em clientes):
+
+| Defesa | Técnica | Exemplo |
+|---|---|---|
+| **Rate limit per-client** | Token bucket no proxy/gateway | Kong/Envoy rate limit; 100 req/s/client |
+| **Concurrency limit** | Semaphore no handler | Máx 1000 in-flight; reject 503 if cheio |
+| **Queue depth limit** | Bound + drop policy | Queue máx 10k msgs; drop oldest > 5k |
+| **Resource budget** | Cgroups / container limits | CPU 4 cores, memory 8GB hard cap |
+| **Slow start na recovery** | Gradual ramp | Aceita 10% → 25% → 50% → 100% por 5 min |
+
+### Pattern 6: Testing for cascading failures
+
+Antes de prod, exercitar cascade scenarios:
+
+```text
+1. Game day exercise
+   - Cap 1 dep crítica em 50% errors via fault injection
+   - Observar: caller circuit breakers abrem? Latency caller estável?
+   - Métrica: zero impacto a clientes (degraded mode kicks in)
+
+2. Load test até saturação
+   - Ramp traffic até 1.5× expected peak
+   - Confirmar: load shedding ativa antes de crash
+   - Métrica: error rate sob 1% mesmo em 1.5× load
+
+3. Chaos engineering
+   - Random kill de instâncias (Chaos Monkey)
+   - Confirmar: retries com jitter espalham wake-up
+   - Métrica: SLO mantido durante 10 kills/hour
+```
+
+## Anti-patterns
+
+### ANTI: timeout otimista
+
+```text
+ANTI: timeout = p99 baseline. "Maioria das requests fica abaixo".
+
+PROBLEMA: tail latency (1%) sempre estoura. Cada 100 requests, 1
+          consome timeout inteiro. Conn pool acumula slow requests.
+
+CERTO: timeout = p99.9 baseline + 50% margem. Aceita que 0.1% será
+       cancelado. Tail é problema de dep, não cliente.
+```
+
+### ANTI: retry infinito com backoff "razoável"
+
+```text
+ANTI: retry até sucesso, com 1s/2s/4s/8s/... exponencial sem cap.
+
+PROBLEMA: durante outage de 30 min, último retry seria após 30 min
+          esperando. Conn fica pendurada. Memory leak.
+
+CERTO: max retries = 3-5; max backoff = 30s; deadline global
+       (request terminada após T segundos não importa quantos
+       retries). Após max, fallback ou error final.
+```
+
+### ANTI: circuit breaker per-instance (não compartilhado)
+
+```text
+ANTI: cada instância de service A tem seu próprio circuit breaker
+      pra dep B. Quando B fica lenta, instância 1 abre circuito,
+      mas instâncias 2-100 ainda pingam B até abrirem.
+
+PROBLEMA: 100× mais carga em B doente. B nunca recupera.
+
+CERTO: circuit breaker compartilhado (e.g., via Redis/Memcached para
+       state) OR lib que detecta failure rate cross-instance via
+       gossip/coordination. Open = cluster all stop.
+```
+
+### ANTI: load shedding via reject ao invés de 503 + Retry-After
+
+```text
+ANTI: server saturated → drop conn TCP-level (RST).
+
+PROBLEMA: client não sabe que precisa esperar. Retry imediato.
+          Mais carga. Retry storm.
+
+CERTO: 503 Service Unavailable + Retry-After: 30 (segundos).
+       Client aware retry com delay. Backoff respeitado.
+```
+
+### ANTI: graceful degradation só em prod
+
+```text
+ANTI: degraded mode só liga durante incident; nunca exercitado.
+
+PROBLEMA: quando precisa, descobre bug no degraded mode. Outage
+          piora.
+
+CERTO: degraded mode é PATH PRINCIPAL em alguma fração de tráfego
+       (1%) por padrão. Sempre exercitado. Quando dep cai, ramp pra
+       100% degraded é tested transition.
+```
+
+## Verificação
+
+Antes de aceitar serviço em prod:
+
+1. Toda chamada a dep externa tem timeout < p99.9 baseline + 50%
+2. Toda retry tem jitter (full jitter default)
+3. Toda chamada respeita deadline propagation
+4. Circuit breaker ativo em deps críticas (estados closed/open/half-open)
+5. Server-side: rate limit + concurrency limit + queue depth bound
+6. Slow start configurado em deploy/recovery
+7. Game day exercise rodado nos últimos 90 dias
+8. Saturation gauge (cap 6) instrumentado e alertado em 80%
+
+---
+
+## Ver também
+
+- [`_shared-sre/glossary.md`](../_shared-sre/glossary.md) — vocabulário cap 22 (cascading failure, retry storm, etc.)
+- [`retry-strategies`](../retry-strategies/SKILL.md) (v1.11) — detalhes de jitter + deadline propagation
+- [`load-shedding-graceful-degradation`](../load-shedding-graceful-degradation/SKILL.md) (v1.11) — defesas server-side
+- [`four-golden-signals`](../four-golden-signals/SKILL.md) (v1.10) — Saturation como early warning de cascade
+- [`production-readiness-review`](../production-readiness-review/SKILL.md) (v1.10) — PRR Axe 4 verifica defesas
+- [`omm-auditor`](../../agents/omm-auditor.md) (v1.9) — Capacidade 1 (Resilience) consume cascading-failures-auditor
+- [`cascading-failures-auditor`](../../agents/cascading-failures-auditor.md) (v1.11) — agent que detecta gaps automaticamente
+
+*Material-fonte: Site Reliability Engineering — Beyer/Jones/Petoff/Murphy (Google/O'Reilly, 2016) — Cap 22: "Addressing Cascading Failures".*

package/kit/skills/four-golden-signals/SKILL.md

@@ -283,6 +283,23 @@ Antes de marcar instrumentação como production-ready, validar:
 6. **Black-box probe complementar** — synthetic check do happy path principal a cada 30s
 7. **Dashboard de 4 signals** existe e é o **primeiro** lugar de debug em incident
 
+## Saturation as cascading failure trigger (v1.11)
+
+**Saturation > threshold é early warning de cascading failure** (cap 22). Quando ainda há tempo para load shedding manter SLO; quando hit 100%, já está em cascade. Threshold tuning canônico:
+
+| Recurso | Warning | Critical | Ação automática |
+|---|---|---|---|
+| **CPU load** | > 70% | > 90% | Load shed; scale up |
+| **Memory used** | > 80% | > 95% | Load shed; OOM protection |
+| **Queue depth (pgmq)** | > 70% capacity | > 90% capacity | Drop oldest; scale consumers |
+| **Connection pool (DB)** | > 70% used | > 90% used | Throttle slow queries; scale pool |
+| **Concurrency limit** | > 80% inflight | > 95% inflight | Reject new (503 + Retry-After) |
+| **File descriptors** | > 70% ulimit | > 90% ulimit | Close idle conns; scale up |
+
+**Resposta canônica:** quando saturation > Critical, server-side ativa load shedding (skill `load-shedding-graceful-degradation` v1.11) — retorna 503 + Retry-After ANTES de aceitar request que vai falhar. Coopera com caller-side defesas (skill `retry-strategies` v1.11 — full jitter respeita Retry-After).
+
+Cross-ref: `cascading-failures` (v1.11) detalha 5 triggers; `cascading-failures-auditor` (v1.11) detecta gaps em código.
+
 ## Ver também
 
 - [`_shared-sre/glossary.md`](../_shared-sre/glossary.md) — termos canônicos golden signals, black-box, white-box, percentile