@luanpdd/kit-mcp 1.8.1 → 1.10.0

package/kit/commands/burn-rate-status.md

@@ -0,0 +1,140 @@
+---
+name: burn-rate-status
+description: Tabela de burn rate por SLO — % budget gasto, ETA exhaustão, ação (page/ticket/warn/ok). Rodável manualmente ou em /loop. Aplica skill burn-rate-alerting.
+argument-hint: "[<slo_name>] [--lookahead 4h] [--baseline 1h]"
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+  - Glob
+---
+
+<objective>
+Snapshot de burn rate para 1 SLO (se especificado) ou TODOS os SLOs definidos. Aplica skill [`burn-rate-alerting`](../skills/burn-rate-alerting/SKILL.md) — fórmula `burn_rate = error_rate / (1 - target)`, lookahead ≤ 4× baseline.
+
+**Cria/Atualiza:** nada — comando read-only.
+
+**Após:** o user vê tabela com status (PAGE / TICKET / WARN / OK) e pode escolher invocar `/investigar-producao` se há burn ativo.
+</objective>
+
+<context>
+**Argumentos:** `$ARGUMENTS` — opcional `<slo_name>` para 1 SLO; sem args = todos.
+
+**Flags:**
+- `--lookahead <duration>` — janela predictive (default: `4h` para short-term)
+- `--baseline <duration>` — janela base (default: `1h`)
+- `--format <table|json>` — output format (default: `table`)
+
+**Combinações canônicas:**
+- short-term: lookahead 4h, baseline 1h (page-tier)
+- long-term: lookahead 3d, baseline 18h (ticket-tier)
+
+**Loop pattern:** rodar este comando via skill `loop` com intervalo 5min para monitoramento contínuo.
+
+```text
+/loop 5m /burn-rate-status
+```
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+SLO_NAME=$(echo "$ARGUMENTS" | awk '{print $1}' | grep -v '^--' || true)
+LOOKAHEAD=$(echo "$ARGUMENTS" | grep -oE -- '--lookahead [^ ]+' | awk '{print $2}')
+BASELINE=$(echo "$ARGUMENTS" | grep -oE -- '--baseline [^ ]+' | awk '{print $2}')
+FORMAT=$(echo "$ARGUMENTS" | grep -oE -- '--format [^ ]+' | awk '{print $2}')
+
+[ -z "$LOOKAHEAD" ] && LOOKAHEAD="4h"
+[ -z "$BASELINE" ] && BASELINE="1h"
+[ -z "$FORMAT" ] && FORMAT="table"
+```
+
+## 2. Listar SLOs
+
+```bash
+if [ -n "$SLO_NAME" ]; then
+  SLO_FILES=(".planning/slos/${SLO_NAME}.md")
+else
+  SLO_FILES=(.planning/slos/*.md)
+fi
+
+if [ ${#SLO_FILES[@]} -eq 0 ] || [ ! -f "${SLO_FILES[0]}" ]; then
+  echo "Nenhum SLO definido. Rode /definir-slo <feature> primeiro."
+  exit 0
+fi
+```
+
+## 3. Para cada SLO, dispatch para `burn-rate-forecaster`
+
+Para cada `SLO_FILE`:
+
+```bash
+SLO_NAME=$(basename "$SLO_FILE" .md)
+TARGET=$(grep -oE 'Target.*[0-9.]+' "$SLO_FILE" | head -1 | grep -oE '[0-9.]+')
+```
+
+```text
+Task(
+  subagent_type="burn-rate-forecaster",
+  prompt="
+slo_name: ${SLO_NAME}
+target: ${TARGET}
+lookahead: ${LOOKAHEAD}
+baseline: ${BASELINE}
+
+Calcular burn rate atual + ETA + status (PAGE/TICKET/WARN/OK).
+Output formato compatível com tabela mestra.
+"
+)
+```
+
+## 4. Agregar resultados em tabela
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► BURN-RATE-STATUS ▸ {timestamp}
+═══════════════════════════════════════════════════════════
+
+| SLO | Target | Window | Budget gasto | Burn rate | ETA exhaustão | Status | Ação |
+|---|---|---|---|---|---|---|---|
+| checkout_success | 99.9% | 30d | 23% | 1.4× | 12d | OK | informativo |
+| login_success | 99.95% | 30d | 78% | 8.0× | 4h | **PAGE** | invocar /investigar-producao |
+| search_latency | 99% | 30d | 15% | 0.7× | — | OK | — |
+```
+
+## 5. Sugerir próximas ações
+
+Se algum SLO em status PAGE ou TICKET:
+
+```
+## ⚠ SLOs em alerta:
+1. login_success — burn rate 8.0×, ETA 4h
+   → /investigar-producao "login_success burn rate = 8.0× às {timestamp}"
+
+## SLOs em WARN (>= 80% gasto):
+- (nenhum)
+
+## SLOs OK:
+- 2 SLOs em compliance saudável
+```
+
+## 6. Modo `/loop`
+
+Se chamado dentro de `/loop`, comportamento idempotente:
+- Não acumular state entre invocações (snapshot fresh)
+- Output curto se nada mudou (apenas status; sem repetir tabela completa em todo loop)
+- Acionar AskUserQuestion APENAS quando status muda de OK → WARN/TICKET/PAGE (transição)
+
+</process>
+
+<success_criteria>
+- [ ] $ARGUMENTS parseados (SLO opcional + flags)
+- [ ] SLOs descobertos via glob `.planning/slos/*.md`
+- [ ] `burn-rate-forecaster` invocado para cada SLO
+- [ ] Tabela agregada em formato consistente
+- [ ] Status enum: PAGE / TICKET / WARN / OK
+- [ ] Sugestões de próximas ações para SLOs em alerta
+- [ ] Idempotente (rodável em /loop sem acúmulo)
+</success_criteria>

package/kit/commands/concluir-marco.md

@@ -133,4 +133,76 @@ Saída: Milestone arquivado (roadmap + requisitos), PROJECT.md evoluído, tag gi
 - **Resumo de uma linha:** Milestone colapsado no ROADMAP.md deve ser uma única linha com link
 - **Eficiência de contexto:** Arquivo mantém ROADMAP.md e REQUIREMENTS.md com tamanho constante por milestone
 - **Novos requisitos:** Próximo milestone começa com `/novo-marco` que inclui definição de requisitos
-  </critical_rules>
+  </critical_rules>
+
+<observability_integration>
+**OMM no-regression gate (v1.9 — INT-FW-05):**
+
+Quando `workflow.complete_milestone_omm_gate = true` (default), o workflow inclui passo OMM regression check antes de arquivar:
+
+1. Procurar `.planning/OMM-REPORT.md` atual. Se ausente: rodar `/auditar-observabilidade` primeiro.
+2. Comparar scores das 5 capacidades com `.planning/milestones/<previous>/OMM-REPORT.md`.
+3. Se alguma capacidade regrediu E `workflow.omm_no_regression = true`: BLOQUEAR conclusion.
+4. Se regression detectada mas `workflow.omm_no_regression = false`: WARN explícito; user decide entre aceitar ou pausar.
+5. OMM-REPORT.md final é arquivado em `.planning/milestones/v<version>/OMM-REPORT.md`.
+
+Gate executável: `gates/omm-no-regression.md`.
+
+Skill consultada: [`observability-maturity-model`](../skills/observability-maturity-model/SKILL.md).
+
+**REQ:** INT-FW-05.
+</observability_integration>
+
+<sre_integration>
+**PRR gate opcional para features production-bound (v1.10 — INT-FW-V2-02):**
+
+Quando `workflow.complete_milestone_prr_gate = true` (default `false` — opt-in até maturidade SRE Engagement do projeto), o workflow inclui passo PRR coverage check **antes de arquivar** o milestone:
+
+1. Listar features production-bound do milestone (heurística: features com Edge Functions deployed, features com SLO definido em `.planning/slos/`, features marcadas explicitamente `production: true` em ROADMAP.md ou em `.planning/phases/<N>-CONTEXT.md`)
+2. Para cada feature production-bound, procurar `.planning/prr/<feature-id>-PRR-REPORT.md` (cross-ref [prr-conductor](../agents/prr-conductor.md) — agent que produz o relatório scored em 6 axes do cap 32)
+3. Verificar status do PRR-REPORT.md:
+   - Se ausente: BLOQUEAR conclusion — sugerir `/prr --feature "<descrição>"` ou `/sre prr --feature "..."` antes de re-rodar `/concluir-marco`
+   - Se presente mas status `failed` (≥ 1 axe P0 reprovado): BLOQUEAR conclusion — listar axes P0 reprovados e exigir remediation
+   - Se presente com status `passed`: incluir `PRR-REPORT.md` como anexo no `.planning/milestones/v<version>-MILESTONE.md` (audit trail)
+4. Quando todos os PRRs de features production-bound forem `passed`: prosseguir para passo 7 (commit + tag) do workflow `complete-milestone.md`
+
+**Distinção `passed` vs `failed`:**
+
+| Status | Definição | Resultado em /concluir-marco |
+|---|---|---|
+| `passed` | Todos os 6 axes scored ≥ 3/5 (cap 32 — System Architecture / Instrumentation / Emergency Response / Capacity Planning / Change Management / Performance) | Milestone arquivável (gate aprova) |
+| `passed-with-warnings` | 6/6 axes ≥ 3/5 mas ≥ 1 axe com action items P1 não resolvidos | Milestone arquivável; warnings explícitos no archive |
+| `failed` | ≥ 1 axe < 3/5 OU ≥ 1 action item P0 não resolvido | Gate BLOQUEIA — exige remediation antes de arquivar |
+
+**Default `false` por design:**
+
+`workflow.complete_milestone_prr_gate` default `false` (≠ `complete_milestone_omm_gate` que é `true`) — PRR Engagement Model do livro Google SRE assume **maturidade organizacional** (SRE team, on-call rotation, incident response). Para projetos em early stage / dogfooding, gate `false` é o correto. Quando o projeto atinge tier-1 (production-user-facing, paid tier, SLA contratual), user explicitamente liga setando `workflow.complete_milestone_prr_gate=true` no config.
+
+**Quando ligar gate:**
+
+- Projeto tem feature user-facing pagante (≥ 1 jornada crítica monetizada)
+- Projeto tem SLO definido em `.planning/slos/` com error budget tracking
+- Projeto tem on-call rotation documentada em runbook
+- Projeto tem postmortem culture estabelecida (≥ 1 postmortem blameless escrito em `.planning/postmortems/`)
+- **Pelo menos 2 dos 4 acima** = liga gate (sinal de production maturity)
+
+**Quando manter gate desligado:**
+
+- Projeto early stage / dogfooding interno (sem usuário pagante)
+- Solo developer side project sem on-call
+- Pesquisa / POC / experimento (não production-bound por design)
+- Equipe ainda construindo SRE muscle (PRR vira teatro se não há cultura de remediation)
+
+**Skill consultada:** [production-readiness-review](../skills/production-readiness-review/SKILL.md) (cap 32 livro Google SRE — *Evolving SRE Engagement Model* — define os 6 axes + 3 engagement models: Simple, Early Engagement, Frameworks/SRE Platform).
+
+**Gate executável:** `gates/prr-checklist-coverage.md` (criado em Phase 41 — QA-SRE-03). Workflow `.claude/framework/workflows/complete-milestone.md` consulta esse gate quando flag `true`.
+
+**Anti-patterns prevenidos:**
+
+- "Marcar feature como production-bound mas pular PRR" → gate exige PRR-REPORT.md presente
+- "PRR-REPORT.md gerado mas status `failed`" → gate exige `passed` (não basta existir)
+- "Auto-PRR pelo time dev" → cross-ref [prr-conductor](../agents/prr-conductor.md) reforça que `prr-conductor` agent é par externo (não o mesmo agent que escreveu a feature)
+- "Gate ligado em projeto early stage" → bloco "Quando ligar gate" exige ≥ 2 sinais de production maturity
+
+**REQ:** INT-FW-V2-02.
+</sre_integration>

package/kit/commands/definir-slo.md

@@ -0,0 +1,108 @@
+---
+name: definir-slo
+description: Invoca slo-engineer para gerar SLO.md + SQL materialização SLI events. Aplica skill event-based-slos. Default 30d sliding window, target ≤ 99.95%.
+argument-hint: "<feature> [--target 99.9] [--owner email]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Definir um SLO event-based para uma feature/jornada do usuário. Invoca o agente [`slo-engineer`](../agents/slo-engineer.md) que aplica a skill [`event-based-slos`](../skills/event-based-slos/SKILL.md) — SLI event-based, sliding window 30d, target ≤ 99.95%, owner nomeado, materialização em Postgres.
+
+**Cria/Atualiza:**
+- `.planning/slos/<slo_name>.md` — definição canônica do SLO
+- `supabase/migrations/<timestamp>_create_sli_<slo_name>.sql` — view materializada SLI
+
+**Após:** SLO está em `draft` status. Próximo passo: `/burn-rate-status <slo_name>` para validar baseline; após 1+ semana, promover de `draft` → `test_channel` → `primary`.
+</objective>
+
+<context>
+**Argumentos:** `$ARGUMENTS` — primeiro token é a feature/jornada (ex: `checkout`, `login`, `bulk-orders`); restante são flags.
+
+**Flags:**
+- `--target <percent>` — target % do SLO (default: agent sugere baseado em criticality, sempre ≤ 99.95%)
+- `--owner <email>` — owner do SLO (default: AskUserQuestion)
+- `--window <duration>` — sliding window (default: `30d`)
+
+**Pré-requisito (Full mode):** projeto Supabase configurado, schema `observability` com tabela de events (Phase 31 supabase-architect projeta isso).
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+FEATURE=$(echo "$ARGUMENTS" | awk '{print $1}')
+TARGET=$(echo "$ARGUMENTS" | grep -oE -- '--target [0-9.]+' | awk '{print $2}')
+OWNER=$(echo "$ARGUMENTS" | grep -oE -- '--owner [^ ]+' | awk '{print $2}')
+WINDOW=$(echo "$ARGUMENTS" | grep -oE -- '--window [^ ]+' | awk '{print $2}')
+
+[ -z "$FEATURE" ] && {
+  echo "Uso: /definir-slo <feature> [--target N] [--owner email]"
+  exit 1
+}
+
+[ -z "$WINDOW" ] && WINDOW="30d"
+```
+
+## 2. Detectar `supabase/config.toml`
+
+```bash
+PROJECT_ID=""
+if [ -f supabase/config.toml ]; then
+  PROJECT_ID=$(grep -E '^project_id\s*=' supabase/config.toml | sed 's/.*= *"\(.*\)".*/\1/' | head -1)
+fi
+```
+
+## 3. Dispatch para `slo-engineer`
+
+```text
+Task(
+  subagent_type="slo-engineer",
+  prompt="
+feature: ${FEATURE}
+${TARGET:+target: ${TARGET}}
+${OWNER:+owner: ${OWNER}}
+window: ${WINDOW}
+${PROJECT_ID:+project_id: ${PROJECT_ID}}
+
+Aplicar skill event-based-slos. Gerar:
+1. .planning/slos/<slo_name>.md (SLO definition canônico)
+2. supabase/migrations/<timestamp>_create_sli_<slo_name>.sql (materialized view + pg_cron refresh)
+
+Se target > 99.95%, recusar e explicar — métrica informativa, não SLO.
+Se Full mode (mcp__supabase disponível), apply_migration; senão, output text.
+"
+)
+```
+
+## 4. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► DEFINIR-SLO ▸ {slo_name}
+═══════════════════════════════════════════════════════════
+
+[output do slo-engineer — ver Step 8 do agent]
+
+## Próximos passos
+1. `/burn-rate-status {slo_name}` — checar baseline atual
+2. Após 1+ semana validando que SLO detecta incidents reais:
+   - Editar `.planning/slos/{slo_name}.md` → status: `test_channel` → `primary`
+3. Configurar alerts (page + ticket) — invocar `burn-rate-forecaster` ou config manual
+```
+
+</process>
+
+<success_criteria>
+- [ ] FEATURE parseado de $ARGUMENTS
+- [ ] `slo-engineer` invocado via Task
+- [ ] `.planning/slos/<slo_name>.md` criado
+- [ ] Migration SQL criada (Full mode applied; Offline mode escrita)
+- [ ] Target ≤ 99.95% enforced
+- [ ] Owner registrado (via flag ou AskUserQuestion)
+</success_criteria>

package/kit/commands/discutir-fase.md

@@ -62,3 +62,29 @@ Se `DISCUSS_MODE` for `"discuss"` (ou não definido, ou qualquer outro valor): L
 - CONTEXT.md captura decisões, não visão vaga
 - Usuário conhece os próximos passos
 </success_criteria>
+
+<observability_integration>
+**Integração com Observability-Driven Development (v1.9):**
+
+Quando o workflow.observability_phase_questions = true (default), o workflow inclui pergunta canônica de ODD na sessão de discussão:
+
+> "Quais SLIs essa fase impacta? O que precisa ser instrumentado para responder às 4 perguntas pré-PR?"
+
+A pergunta é resolvida consultando a skill [`observability-driven-development`](../skills/observability-driven-development/SKILL.md) e o resultado é registrado na seção `<observability>` do CONTEXT.md gerado:
+
+```markdown
+<observability>
+## SLIs impactados
+- [SLI ou "nenhum — fase puramente interna"]
+
+## Instrumentação necessária
+- Spans novos: [lista]
+- Atributos canônicos: [user.id, tenant_id, ...]
+- error.type enum esperado: [validation, timeout, ...]
+</observability>
+```
+
+O `plan-checker` invocado pelo `/planejar-fase` (Phase 33 — INT-FW-02) lê esta seção e bloqueia o plano se ODD ausente para fases voltadas ao usuário (skip silenciosamente para fases de infraestrutura — ver detecção em `discuss-phase.md`).
+
+**REQ:** INT-FW-01.
+</observability_integration>

package/kit/commands/forense.md

@@ -53,4 +53,86 @@ Ler e executar o workflow forensics de @./.claude/framework/workflows/forensics.
 - **Redigir dados sensíveis:** Remover caminhos absolutos, chaves de API, tokens de relatórios e issues.
 - **Fundamentar descobertas em evidências:** Toda anomalia deve citar commits, arquivos ou dados de estado específicos.
 - **Sem especulação sem evidência:** Se os dados forem insuficientes, diga isso — não fabrique causas raiz.
-</critical_rules>
+</critical_rules>
+
+<observability_integration>
+**Integração com Core Analysis Loop (v1.9):**
+
+Forense usa skill [`core-analysis-loop`](../skills/core-analysis-loop/SKILL.md) — método científico iterativo (sintoma → hipótese de dados → validação → próxima iteração) em vez de inspeção ad hoc.
+
+Cada anomalia detectada vira hipótese com query de validação:
+
+| Tipo de anomalia | Hipótese formada | Query de validação |
+|---|---|---|
+| Loop travado | "phase X stuck há Yh" | `git log --since="Yh ago" --grep=phase` para confirmar zero commits |
+| Artefatos ausentes | "PLAN.md ausente em phase X" | `ls .planning/phases/X-*/X-PLAN-*.md` |
+| Trabalho abandonado | "branch sem merge nem commit recente" | `git log -1 <branch>` + `git status` |
+| Crash/interrupção | "executor falhou em meio a fase" | grep no STATE.md por "in_progress" sem update recente |
+
+**Skill consultada explicitamente:** abrir o arquivo `kit/skills/core-analysis-loop/SKILL.md` para padrão "documentação da trilha (formato canônico)" — o relatório forense em `.planning/forensics/report-<ts>.md` segue esse formato com cada hipótese tendo "Query / Resultado / Status (VALIDATED / REFUTED / INCONCLUSIVE)".
+
+**REQ:** INT-FW-06.
+</observability_integration>
+
+<sre_integration>
+**Chain `/postmortem` após Core Analysis Loop (v1.10 — INT-FW-V2-01):**
+
+Forense é diagnóstico evidence-based read-only — identifica o **o que** e o **como** via método científico (sintoma → hipótese → query → status `VALIDATED | REFUTED | INCONCLUSIVE`). Quando o Core Analysis Loop fecha com pelo menos uma hipótese `VALIDATED` apontando para root cause, o próximo passo canônico é **postmortem blameless** (cap 15 livro Google SRE — *Postmortem Culture: Learning from Failure*).
+
+Distinção fundamental:
+
+| Etapa | Pergunta respondida | Output | Audiência |
+|---|---|---|---|
+| Forense | "O que aconteceu? Onde está a evidência?" | `.planning/forensics/report-<ts>.md` | Investigador (você) |
+| Postmortem | "O que aprendemos? O que mudaremos?" | `.planning/postmortems/<id>.md` | Organização inteira (no postmortem left unreviewed) |
+
+Forense **diagnostica**; postmortem **transforma diagnóstico em aprendizado durável**. Pular postmortem = perder aprendizado organizacional (anti-pattern hero culture: "fixei o bug, vamos seguir").
+
+**Trigger automático sugerido (não-bloqueante):**
+
+Quando o relatório forense conclui com:
+- ≥ 1 hipótese `VALIDATED` apontando root cause acionável, OU
+- Incident impactou usuário (não apenas dev experience), OU
+- Workflow framework crashou em produção (não dogfooding)
+
+O comando `/forense` **sugere ao usuário** ao final do relatório:
+
+```text
+Próximo passo recomendado:
+  /postmortem --incident "<one-liner derivado do relatório forense>"
+Continua o blameless write-up com Summary + Impact + Root Causes + Action Items.
+Cross-ref canônico: [blameless-postmortems](../skills/blameless-postmortems/SKILL.md) skill + [postmortem-writer](../agents/postmortem-writer.md) agent.
+
+Nota: para incidents de produção SRE com investigação completa via /investigar-producao
+(que produz .planning/investigations/<id>.md), use `/postmortem --from-investigation <id>`.
+```
+
+**Chain de fluxo canônico:**
+
+```text
+Falha detectada
+  ↓
+/forense "<descrição>"   ← diagnóstico evidence-based (este comando, output: .planning/forensics/report-<ts>.md)
+  ↓ (Core Analysis Loop fecha com VALIDATED)
+/postmortem --incident "<one-liner>"   ← blameless write-up (chain sugerido — modo standalone)
+  ↓
+Action Items P0/P1 viram tarefas em milestone atual ou próximo
+  ↓
+Wheel of Misfortune: postmortem vira treino de novos engineers (cap 15)
+```
+
+**Distinção `/forense` vs `/investigar-producao`:**
+
+- `/forense` — diagnóstico de workflows framework com falha (post-mortem de processo). Output: `.planning/forensics/report-<ts>.md`. Chain: `--incident "<one-liner>"`.
+- `/investigar-producao` (v1.9) — Core Analysis Loop em incident produção SRE com MCP Supabase. Output: `.planning/investigations/<id>.md`. Chain: `--from-investigation <id>`.
+
+**Quando NÃO sugerir chain `/postmortem`:**
+
+- Forense `INCONCLUSIVE` em todas as hipóteses (root cause não identificada — sugerir nova investigação ao invés)
+- Falha trivial documentada (typo em `.gitignore`) sem impacto a usuário
+- Investigação cancelada pelo user antes do Core Analysis Loop fechar
+
+**Cultura blameless é não-negociável:** o postmortem foca em **sistema** (controles ausentes, signals não monitorados, escalation paths frágeis), nunca em **pessoas** ("dev X esqueceu de testar"). Anti-pattern blame culture é explicitamente prevenido pelo template de `postmortem-writer` (cap 15 — *No postmortem left unreviewed*).
+
+**REQ:** INT-FW-V2-01.
+</sre_integration>

package/kit/commands/golden-signals.md

@@ -0,0 +1,142 @@
+---
+name: golden-signals
+description: Invoca golden-signals-instrumenter para serviço/Edge Function/fase — instrumenta 4 golden signals OTel (Latency histogram, Traffic counter, Errors counter, Saturation gauge).
+argument-hint: "<target> [--service <name>] [--saturation <resource>] [--runtime <node|deno|python>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Instrumentar um serviço/Edge Function/fase com os **4 golden signals** do cap 6 do livro Google SRE — Latency (histogram bucketed), Traffic (counter), Errors (counter por `error.type`), Saturation (gauge resource-specific). Invoca o agente [`golden-signals-instrumenter`](../agents/golden-signals-instrumenter.md) que aplica a skill [`four-golden-signals`](../skills/four-golden-signals/SKILL.md).
+
+**Cria/Atualiza:**
+- Patches OTel nos arquivos do `<target>` (Latency + Traffic + Errors + Saturation)
+- `GOLDEN-SIGNALS.md` por target com tabela de instrumentação aplicada (output do agent)
+
+**Após:** os 4 signals estão instrumentados e o user pode rodar smoke local para verificar histogram/counter/gauge no backend OTel.
+</objective>
+
+<context>
+**Argumentos:** `$ARGUMENTS` — primeiro token é o `<target>` (path de arquivo, diretório de service, ou número de fase como `38`); restante são flags.
+
+**Flags:**
+- `--service <name>` — nome canônico do serviço (default: deriva de `package.json#name` ou diretório)
+- `--saturation <resource>` — recurso de saturation (`db_connection_pool` | `cache_memory` | `queue_depth` | `concurrency_limit` | `cpu_load` | `egress_bandwidth`); se omitido, agent infere via heurística
+- `--runtime <node|deno|python>` — runtime; se omitido, detecta via `package.json`/`deno.json`/`pyproject.toml`
+
+**Exemplos:**
+```
+/golden-signals src/orders/handler.ts                              # 1 arquivo
+/golden-signals supabase/functions/process-emails                  # 1 Edge Function
+/golden-signals 38                                                 # todos os arquivos modificados pela Phase 38
+/golden-signals src/api --service orders-api --saturation db_connection_pool
+```
+
+**Pré-requisito:** OTel SDK pode estar ausente — agent flagga deps necessárias no output. Caller decide instalar.
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+TARGET=$(echo "$ARGUMENTS" | awk '{print $1}')
+SERVICE=$(echo "$ARGUMENTS" | grep -oE -- '--service [^ ]+' | awk '{print $2}')
+SATURATION=$(echo "$ARGUMENTS" | grep -oE -- '--saturation [^ ]+' | awk '{print $2}')
+RUNTIME=$(echo "$ARGUMENTS" | grep -oE -- '--runtime [^ ]+' | awk '{print $2}')
+
+if [ -z "$TARGET" ]; then
+  echo "Uso: /golden-signals <target> [--service N] [--saturation R] [--runtime RT]"
+  echo "Exemplos:"
+  echo "  /golden-signals src/orders/handler.ts"
+  echo "  /golden-signals supabase/functions/process-emails"
+  echo "  /golden-signals 38                  # todos arquivos da Phase 38"
+  exit 1
+fi
+```
+
+## 2. Resolver target → lista de target_files
+
+```bash
+# PT-BR: 3 modos de resolução
+if [[ "$TARGET" =~ ^[0-9]+$ ]]; then
+  # Modo fase — extrai files_modified de PLAN.md(s) da Phase $TARGET
+  PHASE_STATE=$(node "./.claude/framework/bin/tools.cjs" init phase-op "$TARGET")
+  PHASE_DIR=$(echo "$PHASE_STATE" | jq -r .phase_dir)
+  if [ "$PHASE_DIR" = "null" ] || [ ! -d "$PHASE_DIR" ]; then
+    echo "Fase $TARGET ainda não foi planejada."
+    exit 1
+  fi
+  TARGET_FILES=$(grep -rh "^  - " "$PHASE_DIR"/*-PLAN-*.md | grep -oE '[a-zA-Z0-9_/.-]+\.(ts|js|py|deno|sql)' | sort -u | tr '\n' ' ')
+elif [ -d "$TARGET" ]; then
+  # Modo diretório — todos arquivos relevantes (.ts, .js, .py)
+  TARGET_FILES=$(find "$TARGET" -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" \) | tr '\n' ' ')
+elif [ -f "$TARGET" ]; then
+  # Modo arquivo único
+  TARGET_FILES="$TARGET"
+else
+  echo "Erro: target '$TARGET' não é arquivo, diretório ou número de fase válido."
+  exit 1
+fi
+
+if [ -z "$TARGET_FILES" ]; then
+  echo "Nenhum arquivo encontrado para target '$TARGET'."
+  exit 0
+fi
+```
+
+## 3. Dispatch para `golden-signals-instrumenter`
+
+```text
+Task(
+  subagent_type="golden-signals-instrumenter",
+  prompt="
+target_files: ${TARGET_FILES}
+${SERVICE:+service_name: ${SERVICE}}
+${RUNTIME:+runtime: ${RUNTIME}}
+${SATURATION:+saturation_resource: ${SATURATION}}
+
+Aplicar skill four-golden-signals. Gerar patches OTel para os 4 signals em cada arquivo:
+1. Latency: histogram com explicitBucketBoundaries exponencial, dimension result=success|error
+2. Traffic: counter incrementado antes de processar request
+3. Errors: counter por error_type enum (5-15 valores; NÃO error.message)
+4. Saturation: ObservableGauge do recurso mais escasso (callback lê estado real)
+
+Validar 6 checks no Step 3 do agent (latency separado success/error, error_type enum, etc.).
+Output: tabela de patches gerados + GOLDEN-SIGNALS.md por target.
+"
+)
+```
+
+## 4. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► GOLDEN-SIGNALS ▸ ${TARGET}
+═══════════════════════════════════════════════════════════
+
+[output do golden-signals-instrumenter — ver Step 4 do agent]
+
+## Próximos passos
+1. Smoke local — enviar request e verificar histogram/counter/gauge no backend OTel
+2. Cross-ref: rodar `/instrumentar-fase ${TARGET}` se spans/wide events ainda ausentes (complementar)
+3. Após validar baseline, definir SLO event-based: `/observabilidade slo <feature>`
+4. PRR antes de production: `/prr --service ${SERVICE:-<name>}`
+```
+
+</process>
+
+<success_criteria>
+- [ ] `<target>` parseado de $ARGUMENTS (arquivo, diretório, ou número de fase)
+- [ ] `target_files` resolvido para lista não-vazia (3 modos suportados)
+- [ ] `golden-signals-instrumenter` invocado via `Task(subagent_type=...)`
+- [ ] Patches aplicados em todos os arquivos do target (4 signals cada)
+- [ ] Output forwarded transparentemente do agent (sem post-processing)
+- [ ] Próximos passos sugerem cross-ref para `/instrumentar-fase`, `/observabilidade slo`, `/prr`
+</success_criteria>