@luanpdd/kit-mcp 1.9.0 → 1.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/CHANGELOG.md +86 -0
  2. package/README.md +58 -0
  3. package/gates/ai-prompt-stability.md +120 -0
  4. package/gates/golden-signals-coverage.md +133 -0
  5. package/gates/legacy-refactor-safety.md +178 -0
  6. package/gates/observability-coverage.md +151 -0
  7. package/gates/postmortem-template-required.md +127 -0
  8. package/gates/prr-checklist-coverage.md +128 -0
  9. package/gates/release-pipeline-policy.md +132 -0
  10. package/kit/COMANDOS.md +15 -0
  11. package/kit/agents/ai-mutation-tester.md +298 -0
  12. package/kit/agents/cascading-failures-auditor.md +306 -0
  13. package/kit/agents/executor.md +13 -0
  14. package/kit/agents/golden-signals-instrumenter.md +241 -0
  15. package/kit/agents/legacy-characterizer.md +378 -0
  16. package/kit/agents/load-shedding-instrumenter.md +297 -0
  17. package/kit/agents/observability-coverage-auditor.md +325 -0
  18. package/kit/agents/omm-auditor.md +99 -0
  19. package/kit/agents/payload-capture-instrumenter.md +283 -0
  20. package/kit/agents/planner.md +29 -0
  21. package/kit/agents/postmortem-writer.md +282 -0
  22. package/kit/agents/prr-conductor.md +296 -0
  23. package/kit/agents/refactor-safety-auditor.md +414 -0
  24. package/kit/agents/release-pipeline-auditor.md +360 -0
  25. package/kit/agents/seam-finder.md +367 -0
  26. package/kit/agents/shotgun-surgery-detector.md +359 -0
  27. package/kit/agents/storytelling-analyst.md +309 -0
  28. package/kit/agents/supabase-architect.md +49 -0
  29. package/kit/agents/supabase-edge-fn-writer.md +114 -0
  30. package/kit/agents/supabase-migration-writer.md +80 -0
  31. package/kit/agents/supabase-storage-implementer.md +156 -0
  32. package/kit/agents/toil-auditor.md +277 -0
  33. package/kit/agents/verifier.md +30 -0
  34. package/kit/commands/auditar-cascading.md +111 -0
  35. package/kit/commands/auditar-marco.md +124 -1
  36. package/kit/commands/auditar-observabilidade-cobertura.md +183 -0
  37. package/kit/commands/auditar-refactor.md +219 -0
  38. package/kit/commands/auditar-release.md +109 -0
  39. package/kit/commands/auditar-toil.md +129 -0
  40. package/kit/commands/capturar-payloads.md +193 -0
  41. package/kit/commands/caracterizar-prompt.md +195 -0
  42. package/kit/commands/caracterizar.md +212 -0
  43. package/kit/commands/concluir-marco.md +95 -1
  44. package/kit/commands/detectar-duplicacao.md +197 -0
  45. package/kit/commands/discutir-fase.md +41 -0
  46. package/kit/commands/encontrar-seams.md +136 -0
  47. package/kit/commands/forense.md +103 -1
  48. package/kit/commands/golden-signals.md +142 -0
  49. package/kit/commands/legacy.md +263 -0
  50. package/kit/commands/load-shedding.md +117 -0
  51. package/kit/commands/observabilidade.md +2 -0
  52. package/kit/commands/postmortem.md +179 -0
  53. package/kit/commands/prr.md +205 -0
  54. package/kit/commands/refactor-seguro.md +321 -0
  55. package/kit/commands/risk-budget.md +220 -0
  56. package/kit/commands/sre.md +230 -0
  57. package/kit/commands/storytelling.md +179 -0
  58. package/kit/skills/_shared-legacy/glossary.md +389 -0
  59. package/kit/skills/_shared-sre/glossary.md +712 -0
  60. package/kit/skills/ai-prompt-characterization/SKILL.md +335 -0
  61. package/kit/skills/blameless-postmortems/SKILL.md +340 -0
  62. package/kit/skills/cascading-failures/SKILL.md +307 -0
  63. package/kit/skills/eliminating-toil/SKILL.md +243 -0
  64. package/kit/skills/event-based-slos/SKILL.md +22 -0
  65. package/kit/skills/four-golden-signals/SKILL.md +314 -0
  66. package/kit/skills/hermetic-builds/SKILL.md +323 -0
  67. package/kit/skills/legacy-api-only-applications/SKILL.md +358 -0
  68. package/kit/skills/legacy-characterization-tests/SKILL.md +330 -0
  69. package/kit/skills/legacy-effect-analysis/SKILL.md +331 -0
  70. package/kit/skills/legacy-extract-class/SKILL.md +203 -0
  71. package/kit/skills/legacy-monster-methods/SKILL.md +444 -0
  72. package/kit/skills/legacy-programming-by-difference/SKILL.md +252 -0
  73. package/kit/skills/legacy-seams-and-test-harness/SKILL.md +460 -0
  74. package/kit/skills/legacy-shotgun-surgery/SKILL.md +286 -0
  75. package/kit/skills/legacy-sprout-wrap-techniques/SKILL.md +434 -0
  76. package/kit/skills/legacy-storytelling-naked-crc/SKILL.md +270 -0
  77. package/kit/skills/llm-as-dependency/SKILL.md +436 -0
  78. package/kit/skills/load-shedding-graceful-degradation/SKILL.md +396 -0
  79. package/kit/skills/pre-refactor-characterization/SKILL.md +421 -0
  80. package/kit/skills/production-readiness-review/SKILL.md +305 -0
  81. package/kit/skills/release-engineering/SKILL.md +367 -0
  82. package/kit/skills/retry-strategies/SKILL.md +372 -0
  83. package/kit/skills/sre-risk-management/SKILL.md +221 -0
  84. package/package.json +2 -2
@@ -0,0 +1,321 @@
1
+ ---
2
+ name: refactor-seguro
3
+ description: Orquestrador de refactor seguro — chain canônico encontrar-seams → caracterizar → auditar-refactor → executar. Suporta modos --mode=full|sprout|safe-extract|override. Substitui edit-and-pray por cover-and-modify.
4
+ argument-hint: "<target_file> [--mode full|sprout|safe-extract|override] [--ticket REQ-N] [--reason \"...\"] [--skip-seams] [--skip-characterize]"
5
+ allowed-tools:
6
+ - Read
7
+ - Write
8
+ - Bash
9
+ - Grep
10
+ - Glob
11
+ - Task
12
+ - AskUserQuestion
13
+ ---
14
+
15
+ <objective>
16
+ Orquestrar fluxo canônico de refactor seguro em código legado: (1) identificar seams + quebrar deps; (2) caracterizar comportamento; (3) auditar safety net; (4) executar refactor com cover-and-modify. Substitui o pattern edit-and-pray (cap 1 Feathers) por cover-and-modify, baseado em characterization tests como oracle.
17
+
18
+ **Chain padrão (`--mode=full`):**
19
+
20
+ ```
21
+ seam-finder → legacy-characterizer → refactor-safety-auditor → executor
22
+ (se necessário) (sempre) (gate) (refactor real)
23
+ ```
24
+
25
+ **Modos alternativos** (atalhos quando mudança não justifica chain completo):
26
+ - `--mode=sprout` — usa `legacy-sprout-wrap-techniques`; legado intocado, comportamento adicionado em sprout testado isoladamente
27
+ - `--mode=safe-extract` — refactor mecânico (rename, IDE-extract bloco contíguo); checklist signed-off + sem characterization
28
+ - `--mode=override` — bypass com audit trail (--ticket + --reason obrigatórios)
29
+
30
+ **Cria/Atualiza:**
31
+ - Em modo full: `.planning/SEAM-ANALYSIS.md`, `tests/characterization/<file_stem>/`, `.planning/REFACTOR-SAFETY.md`
32
+ - Em modo sprout: novo módulo + tests
33
+ - Em modo safe-extract: refactor commit + checklist em `.planning/SAFE-EXTRACT-<file>.md`
34
+ - Em modo override: `.planning/REFACTOR-SAFETY.md` com audit trail
35
+
36
+ **Após:** o user terminou refactor com confiança proporcional ao nível de safety net adotado.
37
+ </objective>
38
+
39
+ <context>
40
+ **Argumentos:**
41
+ - `<target_file>` — caminho do arquivo a refatorar — OBRIGATÓRIO
42
+ - `--mode <full|sprout|safe-extract|override>` — modo do orquestrador (default: `full`)
43
+ - `--ticket REQ-N` — ticket linkado (obrigatório com `--mode=override`)
44
+ - `--reason "<texto>"` — justificativa (obrigatória com `--mode=override`)
45
+ - `--skip-seams` — pular seam-finder (assume deps já controláveis)
46
+ - `--skip-characterize` — pular caracterizar (assume safety net já existe)
47
+ - `--symbol <name>` — escopo limitado a símbolo específico
48
+ - `--feature-description "<texto>"` — em mode=sprout, descreve feature a adicionar
49
+
50
+ **Modos detalhados:**
51
+
52
+ ```
53
+ --mode=full (default)
54
+ =====================
55
+ 1. /encontrar-seams <file> (se necessário, deps externas presentes)
56
+ 2. Aplicar técnicas de break-deps (commits 1-N, manual ou via executor)
57
+ 3. /caracterizar <file> (gera safety net)
58
+ 4. /auditar-refactor <file> (gate retorna GO)
59
+ 5. Refactor real (cover-and-modify, suite verde a cada commit)
60
+ 6. Re-rodar suite final (regressão = 0)
61
+
62
+ --mode=sprout
63
+ =============
64
+ 1. AskUserQuestion para feature description
65
+ 2. Aplicar legacy-sprout-wrap-techniques
66
+ 3. Gerar sprout method/class testável
67
+ 4. Conectar ao legado em 1-2 linhas
68
+ 5. Tests do sprout (100% cobertura no novo)
69
+ 6. PR criado com TODO de débito técnico (legado ainda untested)
70
+
71
+ --mode=safe-extract
72
+ ====================
73
+ 1. Validar checklist canônico:
74
+ - Bloco a extrair é CONTÍGUO?
75
+ - Sem control flow saindo do meio (return/throw/break)?
76
+ - Variáveis lidas/escritas mapeadas?
77
+ - Sem mover lógica entre escopos?
78
+ 2. Aplicar refactor IDE-assisted
79
+ 3. Compilação verde + smoke run
80
+ 4. PR com SAFE-EXTRACT-<file>.md como artefato
81
+
82
+ --mode=override
83
+ ================
84
+ 1. Validar --ticket E --reason
85
+ 2. Auditoria do refactor-safety-auditor com flag override
86
+ 3. Audit trail registrado em REFACTOR-SAFETY.md
87
+ 4. Refactor pode prosseguir SEM characterization
88
+ 5. Débito técnico documentado no ticket
89
+ ```
90
+
91
+ **Exemplos:**
92
+ ```
93
+ /refactor-seguro src/orders/handler.ts # full chain (recomendado)
94
+ /refactor-seguro src/orders/handler.ts --mode=sprout # adicionar feature sem tocar legado
95
+ /refactor-seguro src/orders/handler.ts --mode=safe-extract # rename/extract mecânico
96
+ /refactor-seguro src/orders/handler.ts --mode=override \
97
+ --ticket REQ-2026-Q2-1234 --reason "hot fix SEV1, char em REQ-...1235"
98
+ /refactor-seguro src/orders/handler.ts --skip-seams # deps já testáveis
99
+ /refactor-seguro src/orders/handler.ts --symbol processOrder # método específico
100
+ ```
101
+
102
+ **Quando este comando é o caminho certo:**
103
+ - Você vai modificar arquivo > 200 linhas com cobertura < 60%
104
+ - Webhook/API/Edge Function precisa refactor (contrato externo)
105
+ - Equipe quer disciplina cover-and-modify em vez de edit-and-pray
106
+ - `/discutir-fase` ou `/planejar-fase` detectaram refactor intent
107
+
108
+ **Quando NÃO é o caminho:**
109
+ - Bug fix → use TDD direto (escrever test do comportamento correto, depois fix)
110
+ - Feature nova em código novo → use `/discutir-fase` + `/planejar-fase` normais
111
+ - Arquivo trivial → refactor inline sem ceremonial
112
+ </context>
113
+
114
+ <process>
115
+
116
+ ## 1. Parsear argumentos + validações
117
+
118
+ ```bash
119
+ TARGET_FILE=$(echo "$ARGUMENTS" | awk '{print $1}')
120
+ MODE=$(echo "$ARGUMENTS" | grep -oE -- '--mode[= ][^ ]+' | sed 's/--mode[= ]//')
121
+ TICKET=$(echo "$ARGUMENTS" | grep -oE -- '--ticket [^ ]+' | awk '{print $2}')
122
+ REASON=$(echo "$ARGUMENTS" | grep -oE -- '--reason "[^"]+"' | sed 's/--reason "\(.*\)"/\1/')
123
+ SYMBOL=$(echo "$ARGUMENTS" | grep -oE -- '--symbol [^ ]+' | awk '{print $2}')
124
+ FEATURE_DESC=$(echo "$ARGUMENTS" | grep -oE -- '--feature-description "[^"]+"' | sed 's/--feature-description "\(.*\)"/\1/')
125
+ SKIP_SEAMS=false
126
+ SKIP_CHAR=false
127
+
128
+ echo "$ARGUMENTS" | grep -qE -- '--skip-seams' && SKIP_SEAMS=true
129
+ echo "$ARGUMENTS" | grep -qE -- '--skip-characterize' && SKIP_CHAR=true
130
+
131
+ [ -z "$MODE" ] && MODE="full"
132
+
133
+ if [ -z "$TARGET_FILE" ]; then
134
+ echo "ERROR: target_file é obrigatório."
135
+ echo "Uso: /refactor-seguro <target_file> [opções]"
136
+ exit 1
137
+ fi
138
+
139
+ if [ ! -f "$TARGET_FILE" ]; then
140
+ echo "ERROR: arquivo não encontrado: $TARGET_FILE"
141
+ exit 1
142
+ fi
143
+
144
+ # PT-BR: validações por mode
145
+ case "$MODE" in
146
+ full|sprout|safe-extract|override) ;;
147
+ *)
148
+ echo "ERROR: --mode inválido: $MODE"
149
+ echo "Valores válidos: full, sprout, safe-extract, override"
150
+ exit 1
151
+ ;;
152
+ esac
153
+
154
+ if [ "$MODE" = "override" ]; then
155
+ if [ -z "$TICKET" ] || [ -z "$REASON" ]; then
156
+ echo "ERROR: --mode=override requer --ticket REQ-N E --reason \"<texto>\"."
157
+ exit 1
158
+ fi
159
+ fi
160
+ ```
161
+
162
+ ## 2. Roteamento por mode
163
+
164
+ ### Mode=full (default chain)
165
+
166
+ ```text
167
+ Step 1 — Seam analysis (skip se --skip-seams)
168
+ /encontrar-seams ${TARGET_FILE} ${SYMBOL:+--symbol $SYMBOL}
169
+ → produz .planning/SEAM-ANALYSIS.md
170
+ → user aplica técnicas (commits 1-N)
171
+
172
+ Step 2 — Verificar suite verde após break-deps
173
+ Run test suite, abort se vermelho
174
+
175
+ Step 3 — Characterization (skip se --skip-characterize)
176
+ /caracterizar ${TARGET_FILE} ${SYMBOL:+--symbol $SYMBOL}
177
+ → produz tests/characterization/<file_stem>/
178
+ → user revisa snapshots manualmente
179
+ → user commita como `chore: characterize <file_stem>`
180
+
181
+ Step 4 — Audit do safety net
182
+ /auditar-refactor ${TARGET_FILE} --change-kind=refactor
183
+ → produz .planning/REFACTOR-SAFETY.md com veredito GO/WARN/BLOCK
184
+ → SE BLOCK ainda → loop de volta para step 3 (com --gap-fill)
185
+ → SE GO → prossegue
186
+
187
+ Step 5 — Refactor real
188
+ Delegar para executor OR prompt user para refactor manual
189
+ Após cada commit: rodar suite (verde)
190
+ Após cada commit: characterization tests (verdes — comportamento preservado)
191
+
192
+ Step 6 — Verificação final
193
+ Suite verde
194
+ Characterization VERDE (regressão = 0)
195
+ Mutation kill ≥ 70% (validar safety net)
196
+ PR pode ser aberto
197
+ ```
198
+
199
+ ### Mode=sprout
200
+
201
+ ```text
202
+ Step 1 — Coletar feature description
203
+ Se $FEATURE_DESC vazio → AskUserQuestion:
204
+ "Descreva a feature a ser adicionada (será encapsulada em sprout):"
205
+
206
+ Step 2 — Aplicar legacy-sprout-wrap-techniques
207
+ Decision: sprout method vs sprout class vs wrap method vs wrap class
208
+ - feature ≤ 30 linhas, 1 responsabilidade → sprout method
209
+ - feature > 30 linhas OR multi-responsibility → sprout class
210
+ - feature transforma input/output do legado inteiro → wrap method
211
+ - feature atravessa N métodos da classe → wrap class
212
+
213
+ Step 3 — Gerar sprout
214
+ Criar arquivo novo (sprout module) com lógica testável
215
+ DI explícita para qualquer dep
216
+
217
+ Step 4 — Conectar ao legado em 1-2 linhas
218
+ Inserir chamada ao sprout no legado
219
+ Comment canônico: [legacy-debt #issue-N] sprout — <descrição>
220
+
221
+ Step 5 — Tests do sprout (100% cobertura)
222
+ Escrever 5+ tests cobrindo grupos de equivalência
223
+ Mutation testing no sprout (não no legado)
224
+
225
+ Step 6 — PR
226
+ Diff esperado: arquivo novo + 1-2 linhas no legado
227
+ README/CHANGELOG atualizado se aplicável
228
+ Ticket de débito técnico criado se ainda não existia
229
+ ```
230
+
231
+ ### Mode=safe-extract
232
+
233
+ ```text
234
+ Step 1 — Validar checklist canônico
235
+ AskUserQuestion ou inline-confirm:
236
+ □ Bloco a extrair é CONTÍGUO? (não pode ter return/throw/break/continue saindo)
237
+ □ Variáveis lidas dentro mas declaradas fora → parâmetros (in)?
238
+ □ Variáveis escritas dentro mas usadas fora → return values (out)?
239
+ □ NÃO move lógica entre escopos? (sem move method)
240
+ □ NÃO muda control flow? (sem inverter ifs, sem early return novo)
241
+ □ NÃO modifica sintaxe além de extract/rename?
242
+ Qualquer NÃO → veto, voltar para mode=full
243
+
244
+ Step 2 — Identificar refactor IDE-assisted
245
+ Se Cursor/VS Code/IntelliJ disponível → usar Refactor → Extract Function/Method/Variable
246
+ Caso contrário → manual mas mecânico
247
+
248
+ Step 3 — Aplicar refactor (commits single-goal)
249
+ Após cada commit: compilação verde
250
+ Após cada commit: smoke run (qualquer comando que rodava antes)
251
+
252
+ Step 4 — Output checklist signed-off
253
+ Escrever .planning/SAFE-EXTRACT-<file_stem>.md com:
254
+ - Checklist canônico (todos os itens marcados)
255
+ - Lista de commits (cada um single-goal)
256
+ - Validação de comportamento (smoke verde)
257
+ ```
258
+
259
+ ### Mode=override
260
+
261
+ ```text
262
+ Step 1 — Validar --ticket E --reason (já feito acima)
263
+
264
+ Step 2 — Auditar com flag override
265
+ /auditar-refactor ${TARGET_FILE} \
266
+ --change-kind=override \
267
+ --ticket ${TICKET} \
268
+ --reason "${REASON}"
269
+ → audit trail registrado em REFACTOR-SAFETY.md
270
+
271
+ Step 3 — Refactor pode prosseguir
272
+ Output:
273
+ ⚠ MODE=OVERRIDE — refactor sem characterization
274
+ Ticket: ${TICKET}
275
+ Reason: ${REASON}
276
+ Audit trail: .planning/REFACTOR-SAFETY.md
277
+
278
+ Você aceitou o débito técnico. Refactor pode iniciar AGORA.
279
+ Lembre-se: regressão silenciosa em prod é responsabilidade do owner do ticket.
280
+ ```
281
+
282
+ ## 3. Output canônico
283
+
284
+ ```
285
+ ═══════════════════════════════════════════════════════════
286
+ framework ► REFACTOR-SEGURO ▸ ${TARGET_FILE} (mode: ${MODE})
287
+ ═══════════════════════════════════════════════════════════
288
+
289
+ [output específico do mode escolhido]
290
+
291
+ ## Sumário do que foi feito
292
+
293
+ | Step | Ação | Output |
294
+ |---|---|---|
295
+ | 1 | Seam analysis | .planning/SEAM-ANALYSIS.md |
296
+ | 2 | Characterization | tests/characterization/<file_stem>/ |
297
+ | 3 | Safety audit | .planning/REFACTOR-SAFETY.md (veredito: GO) |
298
+ | 4 | Refactor | <commits sequenciais> |
299
+ | 5 | Verificação final | suite verde, mutation kill ≥ 70% |
300
+
301
+ ## Cross-suite
302
+
303
+ - **/instrumentar-fase** (v1.9) — adicionar instrumentação para detectar regressão precoce em prod via golden signals
304
+ - **/burn-rate-status** (v1.9) — monitor SLO budget pós-deploy do refactor
305
+ - **/prr** (v1.10) — PRR Axe 5 (Change Management) — invoque após refactor para validar production-readiness
306
+ - **/postmortem** (v1.10) — pronto para usar se algo regredir em prod (audit trail completo via REFACTOR-SAFETY.md)
307
+ - **/concluir-marco** — gate `legacy-refactor-safety` (opt-in) bloqueia close se há refactors com mode=override sem ticket close
308
+ ```
309
+
310
+ </process>
311
+
312
+ <success_criteria>
313
+ - [ ] $ARGUMENTS parseados (target_file obrigatório, --mode opcional com 4 valores)
314
+ - [ ] Validações por mode aplicadas (override → ticket + reason; safe-extract → checklist)
315
+ - [ ] Mode=full executa chain canônico (seam-finder → characterizer → safety-auditor → refactor)
316
+ - [ ] Mode=sprout aplica legacy-sprout-wrap-techniques + AskUserQuestion para feature
317
+ - [ ] Mode=safe-extract valida checklist + commits single-goal
318
+ - [ ] Mode=override registra audit trail completo via refactor-safety-auditor
319
+ - [ ] Steps 1-5 e cross-suite documentados no output
320
+ - [ ] Each sub-comando invocado via syntax canônica (`/encontrar-seams`, `/caracterizar`, `/auditar-refactor`)
321
+ </success_criteria>
@@ -0,0 +1,220 @@
1
+ ---
2
+ name: risk-budget
3
+ description: Exibe error budget atual vs risk continuum (cap 3 SRE) — lê .planning/slos/, posiciona no continuum 99% → 99.999%, aplica sabedoria 99.99% e "as reliable as needs to be".
4
+ argument-hint: "[<slo_name>] [--format table|json]"
5
+ allowed-tools:
6
+ - Read
7
+ - Bash
8
+ - Grep
9
+ - Glob
10
+ ---
11
+
12
+ <objective>
13
+ Snapshot read-only de **error budget vs risk continuum** (cap 3 do livro Google SRE) para 1 SLO ou todos. Aplica skill [`sre-risk-management`](../skills/sre-risk-management/SKILL.md) — risk continuum como decisão explícita, error budget como balanço risk × innovation, sabedoria 99.99% (user em smartphone 99% NÃO distingue 99.99% vs 99.999%), "as reliable as needs to be, no more".
14
+
15
+ Lê SLOs definidos em [`event-based-slos`](../skills/event-based-slos/SKILL.md) (v1.9) — `.planning/slos/*.md`. Complementa [`burn-rate-status`](./burn-rate-status.md) (v1.9 — burn rate forecast) com **decisão estratégica** sobre target apropriado.
16
+
17
+ **Cria/Atualiza:** nada — comando read-only.
18
+
19
+ **Após:** o user vê posição de cada SLO no continuum, % budget gasto, custo relativo (1× → 100×+), e recomendação de tier (free/paid/enterprise) consistente com user-perception.
20
+ </objective>
21
+
22
+ <context>
23
+ **Argumentos:** `$ARGUMENTS` — opcional `<slo_name>` para 1 SLO; sem args = todos os SLOs.
24
+
25
+ **Flags:**
26
+ - `--format <table|json>` — output format (default: `table`)
27
+ - `--explain` — incluir bloco "sabedoria 99.99%" + anti-patterns inline (verbose)
28
+
29
+ **Pré-requisito:** SLOs definidos em `.planning/slos/*.md` (v1.9 — comando `/observabilidade slo` ou `/definir-slo`).
30
+
31
+ **Risk continuum canônico** (cap 3, aplicado inline pela skill):
32
+
33
+ | Target | Tolerância 30d | User-perceptible? | Recomendação | Custo relativo |
34
+ |---|---|---|---|---|
35
+ | 99% | 7.2 h | Sim | Tier free, beta, internal | 1× |
36
+ | 99.5% | 3.6 h | Notável | Tier free de produção | 2× |
37
+ | 99.9% | 43.2 min | Aceitável para UX | Tier paid default | 5× |
38
+ | 99.95% | 21.6 min | Quase imperceptível | Tier enterprise / mission-critical | 10× |
39
+ | 99.99% | 4.3 min | Imperceptível em smartphone | Apenas se justificado (raro) | 50×+ |
40
+ | 99.999% | 26 s | NÃO perceptível | NUNCA para user-facing | 100×+ |
41
+
42
+ **Loop pattern:** rodar via skill `loop` para monitoramento contínuo.
43
+
44
+ ```text
45
+ /loop 1h /risk-budget
46
+ ```
47
+
48
+ **Exemplos:**
49
+ ```
50
+ /risk-budget # todos SLOs, formato table
51
+ /risk-budget checkout_success # 1 SLO específico
52
+ /risk-budget --format json # output estruturado
53
+ /risk-budget login_success --explain # com sabedoria 99.99% + anti-patterns inline
54
+ ```
55
+ </context>
56
+
57
+ <process>
58
+
59
+ ## 1. Parsear argumentos
60
+
61
+ ```bash
62
+ SLO_NAME=$(echo "$ARGUMENTS" | awk '{print $1}' | grep -v '^--' || true)
63
+ FORMAT=$(echo "$ARGUMENTS" | grep -oE -- '--format [^ ]+' | awk '{print $2}')
64
+ EXPLAIN=$(echo "$ARGUMENTS" | grep -c -- '--explain' || echo 0)
65
+
66
+ [ -z "$FORMAT" ] && FORMAT="table"
67
+ ```
68
+
69
+ ## 2. Listar SLOs
70
+
71
+ ```bash
72
+ if [ -n "$SLO_NAME" ]; then
73
+ SLO_FILES=(".planning/slos/${SLO_NAME}.md")
74
+ else
75
+ SLO_FILES=(.planning/slos/*.md)
76
+ fi
77
+
78
+ if [ ${#SLO_FILES[@]} -eq 0 ] || [ ! -f "${SLO_FILES[0]}" ]; then
79
+ echo "Nenhum SLO definido em .planning/slos/."
80
+ echo "Defina um com: /observabilidade slo <feature> (v1.9)"
81
+ exit 0
82
+ fi
83
+ ```
84
+
85
+ ## 3. Para cada SLO, extrair metadados + computar posição no continuum
86
+
87
+ Para cada `SLO_FILE`:
88
+
89
+ ```bash
90
+ SLO_NAME=$(basename "$SLO_FILE" .md)
91
+ TARGET=$(grep -m1 -oE 'target.*[0-9.]+' "$SLO_FILE" | grep -oE '[0-9.]+')
92
+ WINDOW=$(grep -m1 -oE 'window.*[0-9]+[dh]' "$SLO_FILE" | grep -oE '[0-9]+[dh]' || echo "30d")
93
+ TIER_LABEL=$(grep -m1 'tier:' "$SLO_FILE" | sed 's/.*tier: //' || echo "(unset)")
94
+ OWNER=$(grep -m1 'owner:' "$SLO_FILE" | sed 's/.*owner: //' || echo "(unset)")
95
+ ```
96
+
97
+ **Mapear target → posição no risk continuum** (skill `sre-risk-management` Pattern 1):
98
+
99
+ | Target faixa | Posição | Custo relativo | Tier típico | User-perceptible |
100
+ |---|---|---|---|---|
101
+ | < 0.99 | abaixo do continuum (under-spec) | <1× | beta/dev | sim |
102
+ | 0.99 ≤ t < 0.995 | 99% | 1× | free, beta, internal | sim (notável) |
103
+ | 0.995 ≤ t < 0.999 | 99.5% | 2× | free de produção | notável em paths críticos |
104
+ | 0.999 ≤ t < 0.9995 | 99.9% | 5× | paid default | aceitável para UX |
105
+ | 0.9995 ≤ t < 0.9999 | 99.95% | 10× | enterprise/mission-critical | quase imperceptível |
106
+ | 0.9999 ≤ t < 0.99999 | 99.99% | 50×+ | só com checklist 4-perguntas | imperceptível em smartphone |
107
+ | t ≥ 0.99999 | 99.999% | 100×+ | NUNCA para user-facing | NÃO perceptível |
108
+
109
+ **Computar budget gasto** (heurística — leitura grosseira do SLO file):
110
+
111
+ ```bash
112
+ # PT-BR: SLO file pode ter linha "**Budget consumido (snapshot):** XX%" atualizada por job
113
+ BUDGET_USED_PCT=$(grep -m1 -oE 'Budget consumido.*[0-9]+%' "$SLO_FILE" | grep -oE '[0-9]+%' || echo "?")
114
+
115
+ # PT-BR: se não, sugerir invocar /burn-rate-status (que tem queries live)
116
+ if [ "$BUDGET_USED_PCT" = "?" ]; then
117
+ BUDGET_USED_PCT="(invoque /burn-rate-status para snapshot live)"
118
+ fi
119
+ ```
120
+
121
+ **Status no continuum** (4 níveis enum — interpretação canônica):
122
+
123
+ - `OPTIMAL` — target apropriado para tier; budget < 50% gasto → "as reliable as needs to be"
124
+ - `OVER-SPEC` — target acima do necessário (ex: tier free com 99.99%) → desperdício; baixar target
125
+ - `UNDER-SPEC` — target abaixo do esperado (ex: enterprise com 99% só) → SLA risk; subir target
126
+ - `BUDGET-EXHAUSTED` — budget < 10% restante → freeze releases; revisitar postmortems
127
+
128
+ ## 4. Agregar resultados em tabela
129
+
130
+ ```
131
+ ═══════════════════════════════════════════════════════════
132
+ framework ► RISK-BUDGET ▸ {timestamp}
133
+ ═══════════════════════════════════════════════════════════
134
+
135
+ | SLO | Target | Posição | Tier | Custo relativo | Budget gasto | Status | Decisão |
136
+ |---|---|---|---|---|---|---|---|
137
+ | checkout_success | 99.9% | 99.9% (5×) | paid | 5× | 23% | OPTIMAL | manter |
138
+ | login_success | 99.99% | 99.99% (50×+) | enterprise | 50×+ | 78% | BUDGET-EXHAUSTED | freeze releases; checklist 4-perguntas? |
139
+ | search_latency | 99% | 99% (1×) | free | 1× | 15% | OPTIMAL | manter (tier free OK) |
140
+ | admin_panel | 99.95% | 99.95% (10×) | (?internal) | 10× | 5% | OVER-SPEC | baixar para 99% (internal tool, custo desperdício) |
141
+ ```
142
+
143
+ Output JSON (`--format json`) — mesmo conteúdo serializado:
144
+
145
+ ```json
146
+ {
147
+ "timestamp": "2026-05-07T...",
148
+ "slos": [
149
+ {
150
+ "name": "checkout_success",
151
+ "target": 0.999,
152
+ "position": "99.9%",
153
+ "cost_multiplier": "5×",
154
+ "tier": "paid",
155
+ "budget_used_pct": 23,
156
+ "status": "OPTIMAL",
157
+ "decision": "manter"
158
+ }
159
+ ]
160
+ }
161
+ ```
162
+
163
+ ## 5. Modo `--explain` — sabedoria 99.99% + anti-patterns inline
164
+
165
+ Se `--explain` setado, anexar após tabela:
166
+
167
+ ```markdown
168
+ ## Sabedoria 99.99% (cap 3)
169
+
170
+ > Smartphone tem ~99% de disponibilidade (sinal cai, bateria acaba, app trava).
171
+ > Usuário em 99% smartphone NÃO distingue serviço 99.99% vs 99.999% — ambos
172
+ > parecem "sempre funcionando" no contexto dele. Cada nove adicional **multiplica
173
+ > custo** mas **divide benefício marginal**. Cliente final (humano em smartphone
174
+ > com ISP residencial ~99%) tem disponibilidade no canal de comunicação inferior
175
+ > à do seu serviço 99.99%. Essa é a sabedoria 99.99%.
176
+
177
+ ## Anti-patterns detectados
178
+
179
+ {Para cada SLO em status OVER-SPEC, BUDGET-EXHAUSTED:}
180
+ - **{slo_name}** ({status}): {explicação curta}
181
+ - {ação recomendada}
182
+
183
+ Exemplos:
184
+ - **admin_panel** (OVER-SPEC): tier internal com 99.95% (10× custo). Internal tool não exige tier paid.
185
+ - Ação: editar `.planning/slos/admin_panel.md` → target: 0.99 (1×); ou remover SLO formal (apenas métrica informativa).
186
+ - **login_success** (BUDGET-EXHAUSTED 78%): 99.99% sem checklist 4-perguntas justificada?
187
+ - Ação: revisar Pattern "justificar 99.99%+ excepcional" (skill sre-risk-management); se NÃO atende 4 critérios, baixar para 99.95%.
188
+ ```
189
+
190
+ ## 6. Sugerir próximas ações
191
+
192
+ Se algum SLO em status `BUDGET-EXHAUSTED` ou `OVER-SPEC`:
193
+
194
+ ```
195
+ ## ⚠ Decisões pendentes
196
+
197
+ {Para cada SLO em alerta:}
198
+ - {slo_name} ({status}): {recomendação curta}
199
+ → /investigar-producao "{slo_name} budget exhausted às {timestamp}" # se BUDGET-EXHAUSTED
200
+ → editar `.planning/slos/{slo_name}.md` target: {sugestão} # se OVER-SPEC
201
+
202
+ ## Cross-refs
203
+ - `/burn-rate-status {slo_name}` — burn rate live (forecast ETA)
204
+ - `/postmortem --incident "..."` — se budget exhausted virou incident
205
+ - `/observabilidade omm` — Capacidade 1 (Embracing Risk) consome este snapshot
206
+ ```
207
+
208
+ </process>
209
+
210
+ <success_criteria>
211
+ - [ ] `<slo_name>` opcional + flags `--format` e `--explain` parseadas
212
+ - [ ] SLOs listados via glob `.planning/slos/*.md`
213
+ - [ ] Cada SLO mapeado para posição no risk continuum (1× a 100×+)
214
+ - [ ] 4 status enum: OPTIMAL / OVER-SPEC / UNDER-SPEC / BUDGET-EXHAUSTED
215
+ - [ ] Tabela agregada com 8 colunas (SLO, Target, Posição, Tier, Custo relativo, Budget gasto, Status, Decisão)
216
+ - [ ] Modo `--explain` anexa sabedoria 99.99% + anti-patterns detectados inline
217
+ - [ ] Cross-refs para `/burn-rate-status`, `/postmortem`, `/observabilidade omm` (Capacidade 1 Embracing Risk)
218
+ - [ ] Idempotente — rodável em `/loop` sem state acumulado
219
+ - [ ] Read-only — comando NÃO modifica arquivos
220
+ </success_criteria>