@luanpdd/kit-mcp 1.8.1 → 1.10.0

package/kit/skills/sre-risk-management/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: sre-risk-management
+description: Use ao escolher SLO target — risk continuum, error budget como balanço explícito risk × innovation, "as reliable as needs to be, no more", sabedoria 99.99%.
+---
+
+# SRE — Risk Management
+
+## Quando usar
+
+LLM carrega esta skill ao definir SLO target, debater "qual disponibilidade precisamos?", ou justificar trade-off entre velocidade de release e estabilidade. Trigger phrases:
+
+- "SLO target", "qual disponibilidade?"
+- "99.9% vs 99.99%", "quantos noves?"
+- "error budget", "risk budget"
+- "risk continuum"
+- "as reliable as needs to be"
+- "sabedoria 99.99%", "smartphone dilui SLO"
+- "embracing risk", "Google SRE cap 3"
+
+## Regras absolutas
+
+- **100% disponibilidade NÃO é o objetivo** — custo cresce não-linearmente acima de 99.95%; benefício marginal cai a zero porque outros componentes (ISP do usuário, smartphone, ar do ambiente) já têm < 99.99% de disponibilidade. Esforço além disso é desperdício.
+- **"As reliable as needs to be, no more"** — disponibilidade é decisão de produto, não de engenharia. Pergunta: "qual nível o usuário percebe como aceitável e está disposto a pagar?" — não "qual o máximo que conseguimos?".
+- **Sabedoria 99.99%** — smartphone tem ~99% de disponibilidade (sinal cai, bateria acaba, app trava). Usuário em 99% smartphone NÃO distingue serviço 99.99% vs 99.999% — ambos parecem "sempre funcionando" no contexto dele.
+- **Error budget é balanço explícito risk × innovation** — `(1 - SLO_target) × total_events` é orçamento de "bad" que pode ser gasto em deploys arriscados, experimentos, refactors. Se budget esgota, freeze releases até regenerar.
+- **Target ≤ 99.95% para SLO real** — 99.99% = 4.3 min de tolerância em 30d; sem tempo de reagir antes do budget esgotar; alerts viram zero-level. Para 99.99%+, use métricas/dashboards informativos, NÃO SLO acionável.
+- **SLI deve refletir customer perception** — meça o que o usuário sente ("checkout completou em < 800ms"), não estado interno ("threads ativas"). Risk é sobre consequência do customer, não engenharia.
+- **Diferentes tiers, diferentes targets** — `customer.tier='enterprise'` pode ter SLO 99.95%; `tier='free'` pode ter 99.5%. Risk é gradual; tratar todos clientes como tier-1 desperdiça budget.
+
+## Patterns canônicos
+
+### Pattern: risk continuum como decisão explícita
+
+| Target | Tolerância 30d | User-perceptible? | Recomendação | Custo relativo |
+|---|---|---|---|---|
+| 99% | 7.2 h | Sim (notável) | Tier free, beta features, internal tools | 1× |
+| 99.5% | 3.6 h | Notável em paths críticos | Tier free de produção | 2× |
+| 99.9% | 43.2 min | Aceitável para maior parte de UX | Tier paid default | 5× |
+| 99.95% | 21.6 min | Quase imperceptível | Tier enterprise / mission-critical | 10× |
+| 99.99% | 4.3 min | Imperceptível em smartphone | Apenas se justificado por user perception (raro) | 50×+ |
+| 99.999% | 26 s | NÃO perceptível | NUNCA para serviço user-facing | 100×+ |
+
+Cada nove adicional **multiplica custo** mas **divide benefício marginal**. Cliente final (humano em smartphone com ISP residencial ~99%) tem disponibilidade no canal de comunicação inferior à do seu serviço 99.99%. Essa é a sabedoria 99.99%.
+
+### Pattern: error budget como decisão de release
+
+```yaml
+# PT-BR: SLO documenta target + política de budget
+slo:
+  name: checkout_success
+  target: 0.999          # 99.9% — escolha explícita no risk continuum
+  window: 30d_sliding
+
+# PT-BR: política de budget — o que fazer quando queima
+budget_policy:
+  green:                 # > 50% restante
+    action: "Releases livres; experimentos OK"
+  yellow:                # 10-50% restante
+    action: "Aumentar canary % menor; review extra de PRs riscados"
+  red:                   # < 10% restante
+    action: "Freeze de features; foco em stability; postmortems revisitados"
+  exhausted:             # 0%
+    action: "Freeze total; rollback de releases recentes; SEV1 incident review"
+```
+
+Budget esgotado **não é punição** — é sinal de que o time gastou risk em demais releases arriscadas e precisa pausar para investir em stability. Restaurar budget = entregar trabalho que reduz erro, não pular o reset.
+
+### Pattern: target diferenciado por customer.tier
+
+```sql
+-- PT-BR: SLO compliance por tier — diferentes targets, diferentes alarmes
+select
+  customer_tier,
+  count(*) as total,
+  count(*) filter (where result_success = true and duration_ms < 800) as good,
+  count(*) filter (where result_success = true and duration_ms < 800)::float / count(*) as compliance,
+  case customer_tier
+    when 'enterprise' then 0.9995    -- PT-BR: 99.95% — paga por SLO rigoroso
+    when 'pro' then 0.999            -- PT-BR: 99.9%
+    when 'free' then 0.995           -- PT-BR: 99.5% — best effort
+  end as target,
+  case
+    when count(*) filter (where result_success = true and duration_ms < 800)::float / count(*) >= (
+      case customer_tier
+        when 'enterprise' then 0.9995
+        when 'pro' then 0.999
+        when 'free' then 0.995
+      end
+    ) then 'IN_BUDGET'
+    else 'OUT_OF_BUDGET'
+  end as status
+from observability.events
+where service = 'orders-api' and timestamp > now() - interval '30 days'
+group by customer_tier;
+```
+
+### Pattern: justificar 99.99%+ excepcional
+
+```text
+Para SLO ≥ 99.99%, o time DEVE responder afirmativamente a TODAS as perguntas:
+
+1. User percebe diretamente a falha? (não apenas erro 500 — UX colapsa, dados perdidos)
+   Ex: trading platform de high-frequency, controle de fluxo industrial, healthcare critical
+
+2. Custo de outage > 10× custo de engineering p/ atingir target?
+   (calcular: 4.3 min outage por mês × revenue/min impactado)
+
+3. Sistema componentes downstream também são ≥ 99.99%?
+   (cliente em ISP 99% — investir aqui é desperdício; trocar de ISP/CDN primeiro)
+
+4. Time tem cultura para sustentar (canary obrigatório, rollback < 60s, on-call < 30s page)?
+   (sem isso, 99.99% é aspiracional — real será 99.5%)
+
+Se QUALQUER resposta = NÃO → use 99.95% ou menos. Justificar em SLO.md comentário inline.
+```
+
+## Anti-patterns
+
+### ANTI: pursuit of 100% availability
+
+```text
+ANTI: perseguir 100% como meta de disponibilidade — rejeitar qualquer outage como
+      falha de engenharia; medir sucesso por "zero downtime"
+
+PROBLEMA: custo cresce assintoticamente perto de 100%; benefício marginal cai a zero
+          porque downstream (ISP do usuário, smartphone, ar do ambiente) já tem
+          < 99.99%; time burns out perseguindo target inalcançável; budget de
+          inovação some — toda capacidade vai para reliability sem ganho real.
+
+CERTO: aceitar imperfeição como design — error budget existe PARA SER GASTO em
+       deploys arriscados, experimentos, refactors. Reliability é trade-off
+       contra velocity, não absoluto.
+```
+
+### ANTI: SLO 99.99% sem justificativa
+
+```text
+ANTI: definir 99.99% como target por default — "queremos o melhor possível";
+      copiar número do AWS SLA; impor 99.99% sem checklist de justificação
+
+PROBLEMA: 4.3 min de tolerância em 30d é zero margem de manobra; alerts disparam
+          após budget esgotar (zero-level — tarde demais para ação preventiva);
+          comportamentos perversos (esconder outages para preservar number);
+          time-pressure compulsiva; aspiração ≠ realidade — real será 99.5%
+          por falta de cultura para sustentar.
+
+CERTO: ≤ 99.95% por default; 99.99%+ exige passar checklist de 4 perguntas
+       (ver Pattern: justificar 99.99%+ excepcional). Documentar racional em
+       SLO.md como comentário inline auditável.
+```
+
+### ANTI: SLO global "site availability"
+
+```text
+ANTI: 1 SLO genérico "site availability 99.9%" cobrindo tudo — /admin, /api,
+      /checkout, /search, /docs com mesmo target
+
+PROBLEMA: falha em /admin (uso 1×/dia por staff) não importa para customer;
+          falha em /checkout (uso 100×/min com revenue impact) é catastrófico;
+          mistura tudo no mesmo budget — alerts confusos, ações vagas; quando
+          burn dispara, time não sabe o que priorizar.
+
+CERTO: 1 SLO por jornada crítica do user (`checkout_success: 99.9%`,
+       `login_success: 99.95%`, `search_p95: 99% < 200ms`); cada um com target
+       apropriado ao seu risk; admin/docs SEM SLO formal (só metric informativo).
+```
+
+### ANTI: budget como score de "performance"
+
+```text
+ANTI: celebrar "atingimos SLO 99.99% este mês!" como vitória; KPIs comparam
+      times por % budget intacto; pressão de leadership para subir target
+
+PROBLEMA: budget vira métrica de vaidade; budget intacto significa SUBUTILIZAÇÃO
+          (não shippamos suficientes deploys arriscados/experimentos); leadership
+          pressiona por mais features sem reconhecer trade-off; quando budget
+          esgota uma vez, vira "fracasso" — time esconde problemas no próximo mês.
+
+CERTO: budget é orçamento — gastá-lo é OK e esperado. KPI é "shippamos N deploys
+       de valor sem queimar budget", não "budget alto". Budget esgotado = sinal
+       de aprender (quais releases custaram caro?), não punição.
+```
+
+### ANTI: SLA == SLO
+
+```text
+ANTI: usar SLA do contrato (99.9%) como SLO interno — "se prometemos 99.9% no
+      contrato, basta atingir 99.9% internamente"
+
+PROBLEMA: 0 margem de segurança entre compromisso comercial e meta interna;
+          primeira anomalia operacional quebra contrato; sem buffer para reagir;
+          SEV1 vira liability legal; cliente perde confiança no primeiro burn.
+
+CERTO: SLO interno mais rígido que SLA externo — fator de margem 5×.
+       SLA externo: 99.9% (compromisso ao cliente);
+       SLO interno: 99.95% (meta de engenharia com folga para reagir).
+```
+
+## Verificação
+
+Antes de marcar SLO target como decidido:
+
+1. **Target justificado por customer perception** — não "queremos 99.99%" mas "usuário em smartphone percebe falha acima de X%"
+2. **Target ≤ 99.95%** OU passou checklist de 99.99%+ (ver Pattern: justificar 99.99%+ excepcional)
+3. **Tier-aware** — diferentes targets para `customer.tier` quando aplicável (enterprise/pro/free)
+4. **Budget policy documentada** — 4 estados (green/yellow/red/exhausted) com ações claras
+5. **Owner nomeado** — SLO sem dono = sem ação = sem valor
+6. **SLI customer-facing** — mede o que cliente sente, não estado interno
+7. **SLA externo > SLO interno** — margem entre compromisso comercial e meta interna
+
+## Ver também
+
+- [`_shared-sre/glossary.md`](../_shared-sre/glossary.md) — termos canônicos risk continuum, error budget, MTTR/MTBF
+- [`event-based-slos`](../event-based-slos/SKILL.md) (v1.9) — definir SLO event-based com sliding window
+- [`burn-rate-alerting`](../burn-rate-alerting/SKILL.md) (v1.9) — alertas predictive sobre error budget
+- [`production-readiness-review`](../production-readiness-review/SKILL.md) — PRR axis "Performance" usa risk continuum
+- [`blameless-postmortems`](../blameless-postmortems/SKILL.md) — postmortem documenta budget consumido
+
+---
+
+*Material-fonte: Site Reliability Engineering — Beyer, Jones, Petoff, Murphy (Google/O'Reilly, 2016) — Cap 3: "Embracing Risk".*

package/kit/skills/structured-events/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: structured-events
+description: Use ao instrumentar — wide events de alta cardinalidade (1/request), campos canônicos com dot notation, evite logs unstructured e métricas pre-aggregated.
+---
+
+# Observabilidade — Structured Events (Wide Events)
+
+## Quando usar
+
+LLM carrega esta skill quando instrumentar código para emitir telemetria. Trigger phrases:
+
+- "structured logging", "wide events", "observability events"
+- "instrumentar handler", "emitir telemetria", "log estruturado"
+- "como salvar evento de request"
+- "campos canônicos", "atributos de span"
+- "alta cardinalidade", "debug por user_id"
+
+## Regras absolutas
+
+- **1 evento por request** — não múltiplos. Acumule contexto durante o request, emita 1 wide event no final (ou em erros).
+- **Wide é melhor que narrow** — adicione campos liberalmente. Custo de 100 campos/evento ≈ 10 campos. Disco é barato; falta de campo no incidente é caro.
+- **Alta cardinalidade é OBRIGATÓRIA** — `user.id`, `tenant_id`, `request.id`, `customer.email`. Sem isso, observabilidade não funciona (Cap 1).
+- **Dot notation OTel** — `user.id` (não `userId` nem `user_id`). `error.type`, `http.status_code`, `db.query`. Snake_case apenas em colunas de DB.
+- **NUNCA pre-aggregate** — não emita "p99 latency = 247ms"; emita o `duration_ms` cru de cada request. Aggregation no read time.
+- **Estruturado, não texto livre** — JSON, OTel attributes, ou colunas tipadas. **Nunca** `console.log("user 123 did X at 12:34")`.
+- **Errors são especiais** — sample 100% de eventos com `result.success = false`. Sucesso pode ser samplado (skill `telemetry-sampling`).
+- **Capture context, não code** — emita atributos de business logic (`customer.tier`, `feature_flag.x`), não estado interno de código (`var_x_value_at_line_42`).
+
+## Patterns canônicos
+
+### Pattern: handler instrumentado (Node/TypeScript)
+
+```ts
+// PT-BR: 1 evento por request, alta cardinalidade, atributos canônicos
+import { trace, SpanStatusCode } from '@opentelemetry/api'
+
+const tracer = trace.getTracer('orders-service')
+
+export async function handlePlaceOrder(req: Request) {
+  return tracer.startActiveSpan('place_order', async (span) => {
+    // PT-BR: campos canônicos sempre — alta cardinalidade
+    span.setAttribute('user.id', req.user.id)
+    span.setAttribute('tenant_id', req.user.tenant)
+    span.setAttribute('customer.tier', req.user.tier)
+    span.setAttribute('request.id', req.headers['x-request-id'])
+    span.setAttribute('endpoint', '/api/v1/orders')
+    span.setAttribute('http.method', 'POST')
+    span.setAttribute('build_id', process.env.BUILD_ID ?? 'dev')
+
+    // PT-BR: feature flags como dimensões
+    span.setAttribute('feature_flag.new_pricing', req.flags.newPricing)
+
+    try {
+      const order = await createOrder(req.body)
+
+      // PT-BR: result e atributos de domínio
+      span.setAttribute('result.success', true)
+      span.setAttribute('order.id', order.id)
+      span.setAttribute('order.amount_cents', order.amount)
+      span.setAttribute('order.items_count', order.items.length)
+      span.setAttribute('http.status_code', 200)
+      span.setStatus({ code: SpanStatusCode.OK })
+      return order
+    } catch (e) {
+      // PT-BR: erros — sample 100%, classificar por tipo
+      span.setAttribute('result.success', false)
+      span.setAttribute('error.type', classifyError(e))
+      span.setAttribute('error.message', e.message)
+      span.setAttribute('http.status_code', e.statusCode ?? 500)
+      span.setStatus({ code: SpanStatusCode.ERROR, message: e.message })
+      throw e
+    } finally {
+      span.end()  // PT-BR: SEMPRE — duration_ms é calculado aqui
+    }
+  })
+}
+
+function classifyError(e: any): string {
+  if (e.code === 'P2002') return 'db_conflict'
+  if (e.statusCode === 401) return 'auth'
+  if (e.statusCode === 403) return 'authz'
+  if (e.statusCode === 422) return 'validation'
+  if (e.statusCode === 429) return 'rate_limit'
+  if (e.code === 'ETIMEDOUT') return 'timeout'
+  return 'unknown'
+}
+```
+
+### Pattern: Edge Function (Deno) com structured event
+
+```ts
+// PT-BR: Supabase Edge Function — 1 evento estruturado por invocação
+import { trace } from 'npm:@opentelemetry/api@1.9.0'
+
+const tracer = trace.getTracer('edge-process-emails')
+
+Deno.serve(async (req) => {
+  return tracer.startActiveSpan('process_emails', async (span) => {
+    const requestId = crypto.randomUUID()
+    span.setAttribute('request.id', requestId)
+    span.setAttribute('build_id', Deno.env.get('SUPABASE_GIT_SHA') ?? 'local')
+
+    try {
+      const body = await req.json()
+      span.setAttribute('user.id', body.user_id)
+      span.setAttribute('tenant_id', body.tenant_id)
+      span.setAttribute('email.batch_size', body.emails?.length ?? 0)
+
+      const result = await processBatch(body.emails)
+
+      span.setAttribute('result.success', true)
+      span.setAttribute('email.sent_count', result.sent)
+      span.setAttribute('email.failed_count', result.failed)
+      span.setAttribute('duration_ms', result.duration)
+
+      return new Response(JSON.stringify(result), { status: 200 })
+    } catch (e) {
+      span.setAttribute('result.success', false)
+      span.setAttribute('error.type', classify(e))
+      span.setAttribute('error.message', String(e))
+      return new Response(JSON.stringify({ error: 'failed' }), { status: 500 })
+    } finally {
+      span.end()
+    }
+  })
+})
+```
+
+### Pattern: campos canônicos por categoria
+
+| Categoria | Campos | Exemplo |
+|---|---|---|
+| **Identidade** | `user.id`, `tenant_id`, `session.id` | `"550e8400-e29b-41d4-..."` |
+| **Request** | `request.id`, `endpoint`, `http.method`, `http.status_code` | `"req_abc123"`, `"/api/v1/orders"`, `"POST"`, `200` |
+| **Resultado** | `result.success`, `error.type`, `error.message` | `true`, `"validation"`, `"email already exists"` |
+| **Performance** | `duration_ms`, `db.query_count`, `cache.hit` | `127`, `3`, `true` |
+| **Build/Deploy** | `build_id`, `service.version`, `region` | `"abc123f"`, `"v1.9.0"`, `"us-east-1"` |
+| **Business** | `customer.tier`, `order.amount_cents`, `feature_flag.<name>` | `"pro"`, `4990`, `true` |
+| **Tracing** | `trace.id`, `span.id`, `span.parent_id` | (auto via OTel) |
+
+### Pattern: query observability — encontrar pattern em wide events
+
+```sql
+-- PT-BR: alta cardinalidade permite group by ad hoc — sem schema rigido
+-- Exemplo: qual tenant + endpoint + error_type domina os erros da última hora?
+select
+  tenant_id,
+  endpoint,
+  error_type,
+  count(*) as error_count,
+  avg(duration_ms) as avg_duration
+from observability.events
+where 
+  result_success = false
+  and timestamp > now() - interval '1 hour'
+group by tenant_id, endpoint, error_type
+order by error_count desc
+limit 20;
+```
+
+## Anti-patterns
+
+### ANTI: log unstructured
+
+```ts
+// PT-BR: BAD — não estruturado, não queryable, sem alta cardinalidade
+console.log(`User ${userId} placed order ${orderId} for $${amount}`)
+
+// PT-BR: GOOD — structured wide event
+span.setAttribute('user.id', userId)
+span.setAttribute('order.id', orderId)
+span.setAttribute('order.amount_cents', amount * 100)
+```
+
+### ANTI: pre-aggregate em métricas
+
+```ts
+// PT-BR: BAD — pre-aggregation perde alta cardinalidade
+metrics.histogram('order_latency_ms').record(duration, { service: 'orders' })
+
+// PT-BR: GOOD — emit raw event, agregue no read
+span.setAttribute('duration_ms', duration)
+// PT-BR: ao queryar: SELECT percentile_cont(0.99) WITHIN GROUP (ORDER BY duration_ms)
+//        FROM events GROUP BY tenant_id, endpoint  -- alta cardinalidade preservada!
+```
+
+### ANTI: múltiplos eventos por request
+
+```ts
+// PT-BR: BAD — 5 eventos para 1 request, sem trace context
+log('user_action_started', { user_id })
+log('user_action_db_query', { user_id, query })
+log('user_action_email_sent', { user_id, to })
+log('user_action_completed', { user_id })
+log('user_action_response_sent', { user_id, status })
+
+// PT-BR: GOOD — 1 wide event acumulando contexto
+const span = tracer.startSpan('user_action')
+span.setAttribute('user.id', user_id)
+// ... ao longo do handler, span.setAttribute('email.recipient', ...) etc.
+span.end()  // 1 evento emitido com todos os atributos
+```
+
+### ANTI: cardinalidade baixa
+
+```ts
+// PT-BR: BAD — apenas service e endpoint, sem identidade
+span.setAttribute('service', 'orders')
+span.setAttribute('endpoint', '/place')
+// PT-BR: durante incident você não consegue responder "afeta quem?"
+
+// PT-BR: GOOD — adicione identidades de alta cardinalidade
+span.setAttribute('user.id', '550e8400-...')
+span.setAttribute('tenant_id', 'acme-corp')
+span.setAttribute('customer.tier', 'pro')
+// PT-BR: durante incident: "afeta quem?" → group by customer.tier, tenant_id
+```
+
+### ANTI: capturar valores internos de código
+
+```ts
+// PT-BR: BAD — atributos sobre estado de variáveis, não sobre business
+span.setAttribute('var_temp_array_length', tempArr.length)
+span.setAttribute('loop_iteration', i)
+
+// PT-BR: GOOD — atributos sobre business + identidade
+span.setAttribute('order.items_count', items.length)
+span.setAttribute('user.id', userId)
+```
+
+### ANTI: nomes inconsistentes de atributos
+
+```ts
+// PT-BR: BAD — mesmo conceito com nomes diferentes em handlers diferentes
+span.setAttribute('userId', user.id)        // handler A
+span.setAttribute('user_id', user.id)       // handler B
+span.setAttribute('user', user.id)          // handler C
+// PT-BR: query `WHERE user_id = X` falha em handler A; agg cross-handler quebra
+
+// PT-BR: GOOD — convenção única em todo o projeto
+span.setAttribute('user.id', user.id)       // sempre dot notation OTel
+```
+
+## Verificação
+
+Antes de marcar instrumentação completa:
+
+1. **1 evento por request** — em request de exemplo, contar eventos emitidos. Deve ser 1 (ou 2 se houver retry interno).
+2. **Atributos canônicos presentes** — checar `user.id`, `tenant_id`, `request.id`, `result.success`, `endpoint`, `duration_ms` no evento emitido.
+3. **Alta cardinalidade verificada** — `select count(distinct user_id)` deve crescer com tráfego real (não estagnar em N pequeno).
+4. **`result.success` define SLI** — boolean confiável para alimentar SLO downstream (ver skill `event-based-slos`).
+5. **Erros têm `error.type` enum** — não `error.message` cru. Permite group by por categoria.
+6. **Build_id presente** — permite comparar versão antes vs depois de deploy.
+7. **Smoke local** — emitir 100 eventos sintéticos, queryar via `select * from events where user_id = X` deve retornar todos.
+
+---
+
+## Ver também
+
+- `kit/skills/_shared-observability/glossary.md` — termos canônicos, campos canônicos, anti-patterns
+- `kit/skills/distributed-tracing/SKILL.md` — como spans se conectam em traces
+- `kit/skills/opentelemetry-standard/SKILL.md` — SDK e exporters
+- `kit/skills/core-analysis-loop/SKILL.md` — como queryar wide events para debug
+
+*Material-fonte: Observability Engineering (O'Reilly, 2022) — Cap 5: "Structured Events Are the Building Blocks of Observability".*