@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.
- package/CHANGELOG.md +86 -0
- package/README.md +58 -0
- package/gates/ai-prompt-stability.md +120 -0
- package/gates/golden-signals-coverage.md +133 -0
- package/gates/legacy-refactor-safety.md +178 -0
- package/gates/observability-coverage.md +151 -0
- package/gates/postmortem-template-required.md +127 -0
- package/gates/prr-checklist-coverage.md +128 -0
- package/gates/release-pipeline-policy.md +132 -0
- package/kit/COMANDOS.md +15 -0
- package/kit/agents/ai-mutation-tester.md +298 -0
- package/kit/agents/cascading-failures-auditor.md +306 -0
- package/kit/agents/executor.md +13 -0
- package/kit/agents/golden-signals-instrumenter.md +241 -0
- package/kit/agents/legacy-characterizer.md +378 -0
- package/kit/agents/load-shedding-instrumenter.md +297 -0
- package/kit/agents/observability-coverage-auditor.md +325 -0
- package/kit/agents/omm-auditor.md +99 -0
- package/kit/agents/payload-capture-instrumenter.md +283 -0
- package/kit/agents/planner.md +29 -0
- package/kit/agents/postmortem-writer.md +282 -0
- package/kit/agents/prr-conductor.md +296 -0
- package/kit/agents/refactor-safety-auditor.md +414 -0
- package/kit/agents/release-pipeline-auditor.md +360 -0
- package/kit/agents/seam-finder.md +367 -0
- package/kit/agents/shotgun-surgery-detector.md +359 -0
- package/kit/agents/storytelling-analyst.md +309 -0
- package/kit/agents/supabase-architect.md +49 -0
- package/kit/agents/supabase-edge-fn-writer.md +114 -0
- package/kit/agents/supabase-migration-writer.md +80 -0
- package/kit/agents/supabase-storage-implementer.md +156 -0
- package/kit/agents/toil-auditor.md +277 -0
- package/kit/agents/verifier.md +30 -0
- package/kit/commands/auditar-cascading.md +111 -0
- package/kit/commands/auditar-marco.md +124 -1
- package/kit/commands/auditar-observabilidade-cobertura.md +183 -0
- package/kit/commands/auditar-refactor.md +219 -0
- package/kit/commands/auditar-release.md +109 -0
- package/kit/commands/auditar-toil.md +129 -0
- package/kit/commands/capturar-payloads.md +193 -0
- package/kit/commands/caracterizar-prompt.md +195 -0
- package/kit/commands/caracterizar.md +212 -0
- package/kit/commands/concluir-marco.md +95 -1
- package/kit/commands/detectar-duplicacao.md +197 -0
- package/kit/commands/discutir-fase.md +41 -0
- package/kit/commands/encontrar-seams.md +136 -0
- package/kit/commands/forense.md +103 -1
- package/kit/commands/golden-signals.md +142 -0
- package/kit/commands/legacy.md +263 -0
- package/kit/commands/load-shedding.md +117 -0
- package/kit/commands/observabilidade.md +2 -0
- package/kit/commands/postmortem.md +179 -0
- package/kit/commands/prr.md +205 -0
- package/kit/commands/refactor-seguro.md +321 -0
- package/kit/commands/risk-budget.md +220 -0
- package/kit/commands/sre.md +230 -0
- package/kit/commands/storytelling.md +179 -0
- package/kit/skills/_shared-legacy/glossary.md +389 -0
- package/kit/skills/_shared-sre/glossary.md +712 -0
- package/kit/skills/ai-prompt-characterization/SKILL.md +335 -0
- package/kit/skills/blameless-postmortems/SKILL.md +340 -0
- package/kit/skills/cascading-failures/SKILL.md +307 -0
- package/kit/skills/eliminating-toil/SKILL.md +243 -0
- package/kit/skills/event-based-slos/SKILL.md +22 -0
- package/kit/skills/four-golden-signals/SKILL.md +314 -0
- package/kit/skills/hermetic-builds/SKILL.md +323 -0
- package/kit/skills/legacy-api-only-applications/SKILL.md +358 -0
- package/kit/skills/legacy-characterization-tests/SKILL.md +330 -0
- package/kit/skills/legacy-effect-analysis/SKILL.md +331 -0
- package/kit/skills/legacy-extract-class/SKILL.md +203 -0
- package/kit/skills/legacy-monster-methods/SKILL.md +444 -0
- package/kit/skills/legacy-programming-by-difference/SKILL.md +252 -0
- package/kit/skills/legacy-seams-and-test-harness/SKILL.md +460 -0
- package/kit/skills/legacy-shotgun-surgery/SKILL.md +286 -0
- package/kit/skills/legacy-sprout-wrap-techniques/SKILL.md +434 -0
- package/kit/skills/legacy-storytelling-naked-crc/SKILL.md +270 -0
- package/kit/skills/llm-as-dependency/SKILL.md +436 -0
- package/kit/skills/load-shedding-graceful-degradation/SKILL.md +396 -0
- package/kit/skills/pre-refactor-characterization/SKILL.md +421 -0
- package/kit/skills/production-readiness-review/SKILL.md +305 -0
- package/kit/skills/release-engineering/SKILL.md +367 -0
- package/kit/skills/retry-strategies/SKILL.md +372 -0
- package/kit/skills/sre-risk-management/SKILL.md +221 -0
- 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>
|