@luanpdd/kit-mcp 1.8.1 → 1.10.0

package/kit/skills/distributed-tracing/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: distributed-tracing
+description: Use ao instrumentar tracing — trace_id/span_id/parent_id, propagar W3C TraceContext via header traceparent, stitching além de RPCs (batch, lambda, queue).
+---
+
+# Observabilidade — Distributed Tracing
+
+## Quando usar
+
+LLM carrega esta skill ao instrumentar tracing distribuído ou stitching de spans. Trigger phrases:
+
+- "distributed tracing", "traces", "spans"
+- "propagar contexto entre serviços", "trace cross-service"
+- "W3C TraceContext", "traceparent header"
+- "trace_id span_id parent_span_id"
+- "ligar lambda batch job ao trace"
+- "stitching de eventos"
+
+## Regras absolutas
+
+- **trace_id é compartilhado** entre todos os spans de um único request distribuído. **NÃO** mude por hop.
+- **span_id é único por span** — gere novo a cada `startSpan()`. 16 hex chars (8 bytes).
+- **parent_span_id aponta para span pai** — null no root span. Define a árvore.
+- **W3C TraceContext é o padrão** — header HTTP `traceparent: 00-{trace_id}-{span_id}-{flags}`. Adote sempre. B3 é fallback para legacy.
+- **Propague ANTES de fazer call cross-service** — extrair contexto do request inbound, propagar no request outbound. Sem isso, trace quebra.
+- **Stitching ≠ apenas RPC** — também batch jobs, queue messages, lambda invocations, S3 uploads. Carregue `traceparent` em metadata da queue, env var do lambda, header da Step Function.
+- **Sample decision propaga** — bit `01` em flags de `traceparent` significa "sample=true". Decisão tomada no head propaga downstream.
+- **Não invente trace_id** — sempre derive do contexto inbound ou gere via SDK (não `crypto.randomUUID()`).
+- **Spans devem ter `kind`** — `SERVER` (handler de inbound), `CLIENT` (call outbound), `PRODUCER`/`CONSUMER` (queue), `INTERNAL` (subspan dentro do mesmo process).
+
+## Patterns canônicos
+
+### Pattern: extrair contexto inbound + propagar outbound (Node)
+
+```ts
+// PT-BR: handler HTTP — extrai traceparent do request inbound, propaga em call outbound
+import { trace, context, propagation } from '@opentelemetry/api'
+
+const tracer = trace.getTracer('orders-service')
+
+export async function placeOrder(req: Request) {
+  // PT-BR: 1 — extrair contexto inbound do header traceparent
+  const inboundContext = propagation.extract(context.active(), req.headers)
+
+  return tracer.startActiveSpan(
+    'place_order',
+    { kind: SpanKind.SERVER },
+    inboundContext,
+    async (span) => {
+      span.setAttribute('user.id', req.user.id)
+
+      // PT-BR: 2 — fazer call outbound — propagation injeta traceparent automaticamente
+      //         se você usar fetch/grpc instrumentados (ver skill opentelemetry-standard)
+      const outboundHeaders: Record<string, string> = {}
+      propagation.inject(context.active(), outboundHeaders)
+
+      const inventoryRes = await fetch('http://inventory/check', {
+        headers: outboundHeaders,  // PT-BR: traceparent injetado aqui
+        body: JSON.stringify({ items: req.items })
+      })
+
+      span.end()
+      return inventoryRes.json()
+    }
+  )
+}
+```
+
+### Pattern: traceparent format
+
+```text
+traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+             ^  ^                                ^                 ^
+             |  |                                |                 |
+             version                             |                 flags (sampled bit)
+                trace_id (32 hex / 16 bytes)     |
+                                                 span_id (16 hex / 8 bytes)
+```
+
+```text
+flags:
+  01 = sampled    (decisão upstream: capture este trace)
+  00 = not sampled (decisão upstream: skip)
+```
+
+### Pattern: trace cross-service via Supabase Edge Function
+
+```ts
+// PT-BR: Edge Function recebe request → propaga para outro service
+import { trace, context, propagation } from 'npm:@opentelemetry/api@1.9.0'
+import { W3CTraceContextPropagator } from 'npm:@opentelemetry/core@1.27.0'
+
+propagation.setGlobalPropagator(new W3CTraceContextPropagator())
+
+const tracer = trace.getTracer('edge-orders')
+
+Deno.serve(async (req) => {
+  // PT-BR: extrair traceparent inbound
+  const inboundCtx = propagation.extract(context.active(), {
+    traceparent: req.headers.get('traceparent') ?? '',
+  })
+
+  return tracer.startActiveSpan(
+    'edge_handler',
+    { kind: 1 /* SERVER */ },
+    inboundCtx,
+    async (span) => {
+      span.setAttribute('endpoint', new URL(req.url).pathname)
+
+      // PT-BR: call outbound para Postgres via PostgREST — injeta traceparent
+      const outHeaders: Record<string, string> = {}
+      propagation.inject(context.active(), outHeaders)
+
+      const dbRes = await fetch(Deno.env.get('SUPABASE_URL') + '/rest/v1/orders', {
+        method: 'POST',
+        headers: {
+          ...outHeaders,
+          'apikey': Deno.env.get('SUPABASE_ANON_KEY')!,
+          'content-type': 'application/json',
+        },
+        body: await req.text(),
+      })
+
+      span.setAttribute('db.status_code', dbRes.status)
+      span.end()
+      return dbRes
+    }
+  )
+})
+```
+
+### Pattern: stitching além de RPC — queue message (não-RPC)
+
+```ts
+// PT-BR: producer — anexa traceparent ao payload da queue (pgmq, SQS, RabbitMQ)
+import { trace, context, propagation } from '@opentelemetry/api'
+
+const tracer = trace.getTracer('producer')
+
+export async function enqueueEmail(emailJob: EmailJob) {
+  return tracer.startActiveSpan(
+    'enqueue_email',
+    { kind: SpanKind.PRODUCER },
+    async (span) => {
+      span.setAttribute('queue.name', 'emails')
+      span.setAttribute('email.recipient', emailJob.to)
+
+      // PT-BR: serializar contexto no payload da mensagem
+      const carrier: Record<string, string> = {}
+      propagation.inject(context.active(), carrier)
+
+      await pgmqEnqueue('emails', {
+        ...emailJob,
+        _trace_context: carrier,  // PT-BR: viaja com o job
+      })
+
+      span.end()
+    }
+  )
+}
+
+// PT-BR: consumer — extrai traceparent do payload, continua o trace
+export async function processEmailJob(job: EmailJobWithContext) {
+  const inboundCtx = propagation.extract(
+    context.active(),
+    job._trace_context ?? {}  // PT-BR: se vazio, novo trace
+  )
+
+  return tracer.startActiveSpan(
+    'process_email',
+    { kind: SpanKind.CONSUMER },
+    inboundCtx,
+    async (span) => {
+      span.setAttribute('email.recipient', job.to)
+      // PT-BR: agora o span do worker faz parte do mesmo trace do producer
+      await sendEmail(job)
+      span.end()
+    }
+  )
+}
+```
+
+### Pattern: stitching de batch job (não-RPC)
+
+```ts
+// PT-BR: cron job processa N items — 1 span por item, todos com mesmo trace_id
+const tracer = trace.getTracer('billing-cron')
+
+export async function dailyBillingJob() {
+  return tracer.startActiveSpan('daily_billing', async (rootSpan) => {
+    rootSpan.setAttribute('job.type', 'cron')
+    rootSpan.setAttribute('build_id', BUILD_ID)
+
+    const customers = await db.getCustomersDueForBilling()
+    rootSpan.setAttribute('customers.count', customers.length)
+
+    // PT-BR: cada customer vira span filho com mesmo trace_id
+    for (const customer of customers) {
+      await tracer.startActiveSpan(
+        'bill_customer',
+        { kind: SpanKind.INTERNAL },
+        async (span) => {
+          span.setAttribute('customer.id', customer.id)
+          span.setAttribute('customer.tier', customer.tier)
+          try {
+            await chargeCustomer(customer)
+            span.setAttribute('result.success', true)
+          } catch (e) {
+            span.setAttribute('result.success', false)
+            span.setAttribute('error.type', classify(e))
+          } finally {
+            span.end()
+          }
+        }
+      )
+    }
+
+    rootSpan.end()
+  })
+}
+```
+
+### Pattern: span kinds
+
+| Kind | Quando usar | Exemplo |
+|---|---|---|
+| `SERVER` | Recebendo request inbound | Handler HTTP, gRPC server method |
+| `CLIENT` | Fazendo call outbound | `fetch()`, gRPC client call, DB query |
+| `PRODUCER` | Enviando msg para queue | `pgmq.enqueue()`, SQS publish |
+| `CONSUMER` | Processando msg de queue | Worker recebendo job |
+| `INTERNAL` | Subdivisão dentro do mesmo process | "json_parse", "validation_step" |
+
+### Pattern: query traces — montar waterfall
+
+```sql
+-- PT-BR: pegar todos os spans de um trace em ordem cronológica
+select
+  span_id,
+  parent_span_id,
+  span_name,
+  span_kind,
+  service_name,
+  duration_ms,
+  start_time
+from observability.spans
+where trace_id = '4bf92f3577b34da6a3ce929d0e0e4736'
+order by start_time asc;
+
+-- PT-BR: encontrar root span — parent_span_id IS NULL ou span sem parent no mesmo trace
+select * 
+from observability.spans
+where trace_id = '4bf92f3577b34da6a3ce929d0e0e4736'
+  and parent_span_id is null;
+
+-- PT-BR: spans mais lentos cross-trace, último 1h
+select 
+  service_name, 
+  span_name,
+  percentile_cont(0.99) within group (order by duration_ms) as p99,
+  count(*) as samples
+from observability.spans
+where start_time > now() - interval '1 hour'
+group by service_name, span_name
+having count(*) > 100
+order by p99 desc
+limit 20;
+```
+
+## Anti-patterns
+
+### ANTI: gerar trace_id por hop
+
+```ts
+// PT-BR: BAD — quebra a cadeia, cada service vê trace diferente
+const traceId = crypto.randomUUID().replace(/-/g, '').slice(0, 32)
+
+// PT-BR: GOOD — extrair do header inbound; deixar SDK gerar root
+const inboundCtx = propagation.extract(context.active(), req.headers)
+tracer.startActiveSpan('handler', {}, inboundCtx, ...)
+```
+
+### ANTI: esquecer de propagar em call outbound
+
+```ts
+// PT-BR: BAD — outbound call sem traceparent — trace quebra no service B
+await fetch('http://service-b/api', { body: ... })
+
+// PT-BR: GOOD — injetar traceparent
+const headers: Record<string, string> = {}
+propagation.inject(context.active(), headers)
+await fetch('http://service-b/api', { headers, body: ... })
+```
+
+### ANTI: trace só de RPCs, não de batch/queue
+
+```ts
+// PT-BR: BAD — producer/consumer não compartilham trace, debug fica fragmentado
+await pgmqEnqueue('emails', payload)  // sem trace context
+// ... depois worker processa sem saber que veio do request X
+
+// PT-BR: GOOD — propagar contexto via metadata da queue
+const carrier = {}
+propagation.inject(context.active(), carrier)
+await pgmqEnqueue('emails', { ...payload, _trace_context: carrier })
+```
+
+### ANTI: span sem `end()`
+
+```ts
+// PT-BR: BAD — span fica aberto forever, duration_ms não calculado, memory leak
+const span = tracer.startSpan('handler')
+// ... handler logic
+return result  // PT-BR: ESQUECEU span.end()
+
+// PT-BR: GOOD — sempre `try/finally`
+const span = tracer.startSpan('handler')
+try {
+  // ... logic
+} finally {
+  span.end()
+}
+```
+
+### ANTI: span hierarchy errada
+
+```ts
+// PT-BR: BAD — usar startSpan sem startActiveSpan, parent não é settado automático
+const parent = tracer.startSpan('parent')
+const child = tracer.startSpan('child')  // PT-BR: parent_span_id ficou null
+parent.end()
+child.end()
+
+// PT-BR: GOOD — startActiveSpan empurra contexto, child herda parent
+tracer.startActiveSpan('parent', (parent) => {
+  tracer.startActiveSpan('child', (child) => {
+    // PT-BR: child.parent_span_id === parent.span_id
+    child.end()
+  })
+  parent.end()
+})
+```
+
+## Verificação
+
+1. **1 trace_id por request** — enviar 1 request, queryar `SELECT DISTINCT trace_id FROM spans WHERE request_id = X` → 1 resultado.
+2. **Cross-service stitching** — request HTTP service A → service B → DB. Queryar `SELECT count(distinct service_name) FROM spans WHERE trace_id = X` → ≥ 3.
+3. **Root span identificável** — `SELECT * FROM spans WHERE trace_id = X AND parent_span_id IS NULL` → 1 row (o root).
+4. **Span hierarchy correta** — graficar via tool (Jaeger UI, Honeycomb, etc.) ou recursivo SQL — deve formar árvore válida (sem ciclos).
+5. **Duration não-zero** — `SELECT min(duration_ms), max(duration_ms) FROM spans` — min ≥ 0, max razoável.
+6. **Sampled flag respeitado** — verificar que se traceparent inbound = `01`, downstream também sample=true.
+7. **Queue stitching funciona** — enqueue + consume → mesmo `trace_id` em ambos os spans.
+
+---
+
+## Ver também
+
+- `kit/skills/_shared-observability/glossary.md` — W3C TraceContext, B3, span kinds
+- `kit/skills/structured-events/SKILL.md` — atributos canônicos por span
+- `kit/skills/opentelemetry-standard/SKILL.md` — SDK que faz extract/inject
+- `kit/skills/telemetry-sampling/SKILL.md` *(Phase 34)* — head vs tail sampling decisão
+
+*Material-fonte: Observability Engineering (O'Reilly, 2022) — Cap 6: "Stitching Events into Traces".*

package/kit/skills/eliminating-toil/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: eliminating-toil
+description: Use ao identificar/eliminar toil — 6 critérios canônicos (manual, repetitivo, automatizável, tático, sem valor durável, escala linear), regra ≤ 50%, automação como invariante.
+---
+
+# SRE — Eliminating Toil
+
+## Quando usar
+
+LLM carrega esta skill ao auditar tarefas operacionais, classificar trabalho como toil/non-toil, ou propor automação. Trigger phrases:
+
+- "toil", "trabalho operacional"
+- "eliminar toil", "reduzir toil"
+- "≤ 50% toil", "regra 50%"
+- "automation", "automatizar tarefa repetitiva"
+- "isso é toil ou overhead?"
+- "Google SRE cap 5"
+- "TOIL-AUDIT"
+
+## Regras absolutas
+
+- **Toil tem 6 critérios canônicos** — uma tarefa É toil se TODOS os 6 valem: (1) **Manual** — humano executa cada vez; (2) **Repetitivo** — você já fez isso 3+ vezes; (3) **Automatizável** — script/cron resolve sem julgamento humano; (4) **Tático** — reage a evento, não planeja; (5) **Sem valor durável** — não cria asset permanente; (6) **Escala linear** — mais users = mais trabalho. Se QUALQUER um dos 6 = não, NÃO é toil (é overhead ou grungy work).
+- **Regra ≤ 50%** — SRE não pode gastar mais que 50% do tempo em toil; restante é engineering (automação, capacity planning, instrumentation, postmortems). Se medindo > 50% por 1+ trimestre, é red flag — peça ajuda à liderança.
+- **Toil ≠ overhead** — reuniões, RH, planejamento de quarter, performance review são **overhead** — necessários, não-elimináveis, NÃO contam para a regra ≤ 50%. Confundir overhead com toil = sub-medir.
+- **Toil ≠ grungy work** — refactor de código legado, security cleanup, DB rebuild para reduzir bloat são **grungy work** — necessários, têm valor durável, são engineering trabalho. NÃO contam como toil.
+- **Automação é o objetivo, não o meio** — automatizar parcialmente (humano clica botão A, depois B, depois C) ainda é toil. Automação completa (cron + script + alert se falhar) elimina toil. Meias-medidas perpetuam.
+- **Toil tax cresce com produto** — cada feature nova adiciona toil potencial: deploy manual, migration manual, feature flag rotation, customer-specific config. Prevenir > remediar — design feature considerando "como auto-operar isso?".
+- **Quantificar toil em horas-pessoa** — "TOIL-AUDIT.md" deve ter coluna `hours_per_week_per_person` para cada item. Sem quantificação, "muito toil" é subjetivo e não-acionável.
+- **Priorizar por (frequency × pain) / automation_effort** — P0 = alto frequency + alto pain + baixo effort. P2 = baixa frequency OU alto effort. Não automatizar tudo de uma vez — começar pelo P0.
+
+## Patterns canônicos
+
+### Pattern: decision tree para classificar trabalho
+
+```text
+Tarefa repetitiva detectada → aplicar 6 critérios canônicos:
+
+1. Manual?           (humano executa cada vez)             ┐
+2. Repetitiva?       (já fiz isso 3+ vezes)                 │
+3. Automatizável?    (script/cron resolve sem julgamento)   │── Se TODOS sim → TOIL
+4. Tática?           (reage a evento, não planeja)          │   → automatizar / eliminar
+5. Sem valor durável? (não cria asset permanente)           │   → contar em ≤ 50% rule
+6. Escala linear?    (mais users = mais trabalho)          ─┘
+
+Se NÃO for toil mas repetitivo, classificar:
+- OVERHEAD       (reuniões, RH, planning) → não-eliminável; NÃO conta em ≤ 50%
+- GRUNGY WORK    (refactor, sec cleanup) → necessário, valor durável → projeto engineering
+- PROJECT WORK   (criar novo serviço) → engineering trabalho ≠ toil
+```
+
+### Pattern: template `TOIL-AUDIT.md`
+
+Formato canônico que `toil-auditor` (Phase 37) gera:
+
+```markdown
+# TOIL-AUDIT — <projeto> — <data>
+
+## Métrica agregada
+
+- Toil estimado: X.X horas-pessoa/semana (Y% do tempo do time)
+- **Status vs ≤ 50% rule:** [GREEN: < 30%] | [YELLOW: 30-50%] | [RED: > 50%]
+- Top 3 áreas: <lista>
+
+## Itens identificados
+
+| # | Item | Frequência | Hours/week | Pain (1-5) | Automation effort | Priority |
+|---|------|------------|------------|------------|-------------------|----------|
+| 1 | Reset DB seed manual antes de cada test run | 2×/dia | 1.5 h | 4 | M (3 dias) | P0 |
+| 2 | Rotation de access_token de Edge Function | 1×/semana | 0.5 h | 2 | S (1 dia) | P1 |
+| 3 | Rebuild de índice fts_search após batch import | 1×/mês | 0.5 h | 3 | M (2 dias) | P1 |
+| 4 | Limpeza manual de orphan rows em audit_log | 1×/semana | 0.3 h | 1 | S (1 dia) | P2 |
+
+## P0 (automatizar agora)
+
+### Item 1: Reset DB seed manual
+
+**Por que é toil:** atende 6 critérios canônicos (manual, repetitivo 2×/dia, automatizável via script + pg_cron, tática reativa, sem valor durável, escala com #devs).
+
+**Automação proposta:** `make db-reset` que invoca `supabase db reset && pnpm run seed`. Adicionar pre-test hook em CI.
+
+**Esforço estimado:** 3 dias (Med — script existe parcialmente, falta seed deterministic).
+
+**Owner sugerido:** @dev-tools-team
+
+## P1 / P2 (escalonar)
+
+...
+
+## Não-toil identificado
+
+- **Overhead:** sprint planning (2h × semana × 5 pessoas = 10h/semana) — NÃO conta no ≤ 50%
+- **Grungy work:** refactor de `legacy_orders_service` (8h × semana × 1 pessoa = 8h/semana) — projeto, não toil
+```
+
+### Pattern: estágios de automação (níveis Google)
+
+| Estágio | Descrição | Exemplo |
+|---|---|---|
+| **L0: Manual** | 100% humano | "Cada deploy: SSH no host, copy binary, kill+restart" |
+| **L1: Documented** | Runbook escrito; humano segue passos | "Doc passo-a-passo de deploy em wiki" |
+| **L2: Tooled** | Script executa passos; humano invoca | "`./deploy.sh prod`" |
+| **L3: Self-service** | UI/CLI trigger; humano clica | "GitHub Actions deploy on PR merge" |
+| **L4: Autonomous** | Sem humano; só fail-state intervenção | "Auto-rollback se SLO burn rate > 4 nos primeiros 5 min após deploy" |
+
+Meta SRE é mover toda toil de L0/L1 para L3/L4. L2 é meio-passo aceitável quando L3+ requer investimento maior. **L1 (apenas runbook) é toil disfarçado** — runbook é manual com passo extra de "ler doc".
+
+### Pattern: identificação de toil via git log + scripts
+
+```bash
+# PT-BR: scripts shell em runbooks/ ou docs/runbooks/
+find . -name "*.sh" -path "*runbook*" -o -path "*ops*" | head -20
+
+# PT-BR: "manual steps" em README/docs (heurística — frase canônica)
+grep -rn "manually\|por favor\|run this\|every week\|cada semana" --include="*.md" .
+
+# PT-BR: tarefas repetitivas via git log — commits de mesmo tipo
+git log --since="3 months ago" --pretty=format:"%s" | sort | uniq -c | sort -rn | head -20
+# Ex: "20× Re-run failed migration in prod"  → TOIL candidato
+# Ex: "15× Bump deploy-token"                → TOIL candidato
+
+# PT-BR: cron jobs já automatizados (saída esperada)
+crontab -l 2>/dev/null
+cat /etc/cron.d/* 2>/dev/null
+```
+
+### Pattern: "toil tax" — prevenir feature nascer com toil
+
+```text
+Antes de mergear PR de nova feature, perguntar:
+
+1. "Como auto-operar isso em prod?"          → instrumentação ODD
+2. "Como auto-monitorar?"                     → 4 golden signals
+3. "Como auto-recuperar de fail comum?"       → retry, circuit breaker
+4. "Como auto-rotacionar credenciais?"        → vault + cron rotation
+5. "Como auto-limpar dados históricos?"       → retention policy + scheduled cleanup
+6. "Como onboarding de novo cliente?"         → self-service signup, não Slack ping
+
+Se QUALQUER resposta = "humano fará isso" → toil tax. Bloqueie ou descontar do release budget.
+```
+
+## Anti-patterns
+
+### ANTI: confundir overhead com toil
+
+```text
+ANTI: contar reuniões, RH, planning, performance review como toil — toda
+      atividade não-codificadora vira "toil" no audit.
+
+PROBLEMA: métrica inflada (e.g., 60% "toil" falso); ações erradas — cortar
+          reunião não diminui toil real; equipe perde tempo em automação
+          de overhead (que é não-eliminável por design).
+
+CERTO: overhead é categoria separada; ≤ 50% rule conta APENAS toil estrito
+       (6 critérios canônicos). Audit lista overhead em seção própria,
+       fora do total.
+```
+
+### ANTI: hero culture (toil mascara via heroísmo)
+
+```text
+ANTI: engineer fica 2h por dia executando deploys manuais e é "celebrado
+      por dedicação" / "salvador" — toil nunca aparece em métrica.
+
+PROBLEMA: toil invisível para liderança; investimento em automação adiado
+          indefinidamente; engineer pede demissão; sucessor herda toil sem
+          context — incidente garantido. Ciclo se repete.
+
+CERTO: TOIL-AUDIT trimestral mandatório; quantificar em hours/week por
+       pessoa; tornar visível em dashboards de produtividade. Heroísmo
+       sustentado = sinal de underinvestment, não de mérito.
+```
+
+### ANTI: documentar runbook em vez de automatizar
+
+```text
+ANTI: "Vamos só escrever um doc detalhado de como fazer isso passo-a-passo"
+      — runbook de 30 passos no wiki, sem script.
+
+PROBLEMA: L1 (Documented) ainda é toil — humano lê doc, segue passos,
+          falha em algum, doc desatualiza em 3 meses; primeira pessoa que
+          segue após drift quebra prod; ninguém atualiza doc retroativamente.
+
+CERTO: doc como passo intermediário (L1); meta é L3/L4 (autonomous);
+       marcar runbook com TODO de automação + owner + due date; sprint
+       seguinte transforma em script (L2) ou melhor.
+```
+
+### ANTI: automatizar parcialmente
+
+```text
+ANTI: script faz 3 dos 5 passos; humano completa os outros 2 — "execute
+      primeiro ./step1.sh, depois manualmente faça X em prod, depois
+      ./step3.sh".
+
+PROBLEMA: ainda é toil (humano envolvido); contexto-switch entre script e
+          humano dobra tempo total; script raramente atualizado por estar
+          "incompleto"; degrada para chain frágil que ninguém quer mexer.
+
+CERTO: automação completa OU não automatizar — meias-medidas perpetuam.
+       Se faltam 2 passos manuais, gastar mais 1 dia para fechar o loop;
+       resultado é L3/L4 autônomo, não L1.5 frankenstein.
+```
+
+### ANTI: ignorar toil de baixa frequência
+
+```text
+ANTI: "Só faço isso 1× por trimestre, não vale automatizar" — descartar
+      tarefas raras do audit.
+
+PROBLEMA: cumulative impact alto (10 tarefas trimestrais × 4 trimestres ×
+          30 min = 20h/ano); cada vez que retorna, pessoa esquece passos;
+          documentação envelhece entre execuções; DR exercises e migrations
+          raras são exatamente onde erro humano custa mais.
+
+CERTO: priorizar por (frequency × pain) / effort; baixa frequência +
+       alto pain (e.g., DR exercise, schema migration crítica) = ainda
+       P1. Frequência baixa ≠ toil baixo — soma de raras é alta.
+```
+
+## Verificação
+
+Antes de marcar audit de toil como completo:
+
+1. **Aplicado os 6 critérios canônicos** — cada item passou pelo decision tree (manual, repetitivo, automatizável, tático, sem valor durável, escala linear)
+2. **Quantificado em hours/week** — não "muito toil" mas "3.5h/week por pessoa"
+3. **% do tempo do time** computado — comparado contra ≤ 50% rule
+4. **Priorização por (frequency × pain) / effort** — P0/P1/P2 atribuído
+5. **Owner nomeado** para cada item P0
+6. **Overhead identificado separadamente** — não conta para ≤ 50%
+7. **Grungy work identificado separadamente** — projeto engineering, não toil
+8. **Pelo menos 1 item P0 escalonado** com automação proposta + esforço estimado
+
+---
+
+## Ver também
+
+- [`_shared-sre/glossary.md`](../_shared-sre/glossary.md) — termos canônicos toil, overhead, grungy work, automation
+- [`observability-maturity-model`](../observability-maturity-model/SKILL.md) (v1.9) — Capacidade 3 (Complexidade/Tech Debt) consome toil score
+- [`production-readiness-review`](../production-readiness-review/SKILL.md) — PRR axis "Change Management" verifica deploy não é toil
+- [`blameless-postmortems`](../blameless-postmortems/SKILL.md) — postmortems de toil-induced incidents alimentam audit
+- [`sre-risk-management`](../sre-risk-management/SKILL.md) — toil reduz tempo para reduzir risk
+
+*Material-fonte: Site Reliability Engineering — Beyer, Jones, Petoff, Murphy (Google/O'Reilly, 2016) — Cap 5: "Eliminating Toil".*