@luanpdd/kit-mcp 1.10.0 → 1.11.0

package/kit/skills/legacy-characterization-tests/SKILL.md

@@ -0,0 +1,330 @@
+---
+name: legacy-characterization-tests
+description: Use ao refatorar código legado SEM testes prévios — characterization tests (cap 13 Feathers) capturam comportamento atual como golden snapshot, viram oracle imutável durante o refactor. Bloqueador para legacy refactor.
+---
+
+# Legacy — Characterization Tests
+
+## Quando usar
+
+LLM carrega esta skill quando o user vai modificar código sem suite de testes adequada e o objetivo é refactor (não bug fix). Trigger phrases:
+
+- "refatorar [arquivo grande]", "extract method de", "quebrar essa classe"
+- "esse arquivo não tem testes", "como começo testando isso?"
+- "preservar comportamento", "snapshot test", "golden master"
+- "cap 13 Feathers", "characterization test"
+- "código legado", "legacy code", "edit and pray"
+- arquivo > 500 linhas que será modificado
+- arquivo com contrato externo (webhook, API, integração) sendo modificado
+
+Carrega antes de planejar/executar refactor. **Bloqueia execução** até characterization existir.
+
+## Regras absolutas
+
+- **Legacy code = código sem testes** (definição Feathers, não emocional). Idade não importa. Estética não importa. **Cobertura comportamental** importa.
+- **Characterize first, refactor second.** Sempre. Sem exceção. Pular esse passo é "edit and pray" — o modo default que o livro existe para combater.
+- **Capture o que o código FAZ, não o que DEVERIA fazer.** Se há bug, o teste preserva o bug. Bug fix é commit separado, depois do refactor, com seu próprio teste.
+- **Mínimo de 5-10 inputs cobrindo grupos de equivalência** — null/vazio, válido típico, válido extremo, inválido recoverable, inválido fatal. Menos que isso = baseline frágil.
+- **Behavioral coverage ≥ 70-80% antes de qualquer extract/move/rename**. Coverage % de linha NÃO É proxy de safety — verifique branches via mutation testing.
+- **Golden master/snapshot é decisão, não copy-paste.** Leia output capturado linha por linha antes de salvar. Bugs conhecidos viram comentários inline (`// BUG #X: deveria Y, é Z`). PII/secrets/UUIDs locais → redact deterministic (hash, mask).
+- **Vermelho em characterization test = regressão até prova ao contrário.** Nunca "atualize o expected" sem investigar e documentar a mudança comportamental no commit.
+- **Bug fix dentro de refactor PR = veto.** Misturar invalida o oracle e torna PR não-revisável. Single-goal editing (cap 22) — uma intenção por commit.
+
+## Patterns canônicos
+
+### Pattern 1: Workflow de characterization (cap 13)
+
+```text
+1. Identificar o método/classe/arquivo a refatorar
+2. Inventariar entradas e saídas:
+   - Inputs: parâmetros + globals lidos + I/O (DB read, API call)
+   - Outputs: return + parâmetros mutados + I/O (DB write, log, API call)
+3. Para cada grupo de equivalência (5+ inputs):
+   a. Construir input ("arrange")
+   b. Executar código real ("act") — sem mocks ainda; isole I/O com seam mínimo se necessário
+   c. Capturar output completo ("snapshot")
+   d. REVISAR output linha por linha — marcar bugs conhecidos como comments
+   e. Salvar como `expected.txt` ou `__snapshots__/foo.test.ts.snap`
+4. Escrever teste:
+   - Arrange = mesmo input
+   - Act = mesmo código
+   - Assert = output igual ao salvo (deep equal OR snapshot match)
+5. Rodar suite — TODOS verdes → BASELINE estabelecido
+6. Refactor pode começar
+```
+
+### Pattern 2: Grupos de equivalência canônicos
+
+Cobertura mínima — pelo menos 1 caso por grupo:
+
+| Grupo | Definição | Exemplo (função `parseOrder(input)`) |
+|---|---|---|
+| **Empty** | Input ausente/zero/vazio | `parseOrder(null)`, `parseOrder({})` |
+| **Typical valid** | Caso comum esperado | `parseOrder({ id: 'O123', items: [...] })` |
+| **Boundary valid** | Limites superiores/inferiores válidos | `parseOrder({ ..., items: [singleItem] })`, `parseOrder({ ..., items: [maxItems_x_50] })` |
+| **Recoverable invalid** | Erro que código trata graceful | `parseOrder({ id: 'O123', items: 'malformed' })` — espera-se exceção tipada |
+| **Fatal invalid** | Erro que código não trata (vai propagar/crashar) | `parseOrder(undefined)` — espera-se NPE/crash |
+| **Side-effect heavy** | Input que dispara muitos side effects (logs, DB writes) | Ordem grande que escreve em audit log + cache + queue |
+| **Edge case histórico** | Cases conhecidos que já causaram bugs (consultar git log/issues) | Input com encoding UTF-16, timestamp negativo |
+
+### Pattern 3: Snapshot tooling por linguagem
+
+| Linguagem | Framework | Snapshot syntax |
+|---|---|---|
+| **JavaScript/TypeScript** | Jest, Vitest | `expect(output).toMatchSnapshot()` ou `toMatchInlineSnapshot()` |
+| **Python** | pytest + pytest-snapshot OR syrupy | `snapshot.assert_match(output)` ou `assert output == snapshot` |
+| **Java** | JUnit + ApprovalTests | `Approvals.verify(output)` |
+| **Ruby** | RSpec + rspec-snapshot | `expect(output).to match_snapshot('foo_bar')` |
+| **Go** | go-cmp + cupaloy/snaps | `cupaloy.SnapshotT(t, output)` |
+| **C#** | Verify, Snapshooter | `await Verifier.Verify(output)` |
+| **Rust** | insta | `insta::assert_yaml_snapshot!(output)` |
+
+**Anti-tooling:** evitar diff visual cru (eyeballed) — snapshot framework gera diff legível e atualiza expected via flag (`--updateSnapshot` no Jest, `--snapshot-update` em pytest). Sem framework, refactor de "atualizar oracle" vira manual e propenso a erro.
+
+### Pattern 4: Captura de outputs com side effects
+
+Quando código tem side effects (DB writes, HTTP calls, logs), o snapshot deve incluir **todos** os efeitos observáveis, não só return. Estratégia:
+
+```ts
+// PT-BR: capturar return + lista canônica de efeitos
+async function characterize_placeOrder() {
+  const sideEffects = {
+    dbWrites: [] as Array<{ table: string, op: string, row: any }>,
+    httpCalls: [] as Array<{ url: string, method: string, body: any }>,
+    logs: [] as Array<{ level: string, msg: string, fields: any }>,
+    queueMsgs: [] as Array<{ queue: string, payload: any }>,
+  }
+
+  // Wire fakes que populam sideEffects ao invés de fazer real I/O
+  const db = makeFakeDb(sideEffects.dbWrites)
+  const http = makeFakeHttp(sideEffects.httpCalls)
+  const log = makeFakeLogger(sideEffects.logs)
+  const queue = makeFakeQueue(sideEffects.queueMsgs)
+
+  const input = { customerId: 'C-42', items: [{ sku: 'SKU-1', qty: 2 }] }
+  const result = await placeOrder(input, { db, http, log, queue })
+
+  return {
+    return: result,
+    sideEffects,
+  }
+  // ↑ ESSE objeto é o que vira snapshot
+}
+
+// Test
+test('placeOrder — typical valid input', async () => {
+  const captured = await characterize_placeOrder()
+  expect(captured).toMatchSnapshot()
+})
+```
+
+Snapshot resultante captura return E efeitos, ambos congelados.
+
+### Pattern 5: Determinismo — eliminar non-determinism antes de capturar
+
+Datas, UUIDs, random, nanos — todos não-determinísticos por default. Capture-os como dependência injetada:
+
+```ts
+// PT-BR: dependências injetadas tornam snapshot reproduzível
+const fakeClock = () => new Date('2024-01-15T10:00:00Z')  // congelado
+const fakeUuid = (() => { let n = 0; return () => `uuid-${++n}` })()  // determinístico
+const fakeRandom = (() => { let n = 0; return () => (n++ % 1000) / 1000 })()  // ciclico
+
+const result = await placeOrder(input, {
+  ...realDeps,
+  clock: fakeClock,
+  uuidGen: fakeUuid,
+  random: fakeRandom,
+})
+```
+
+Sem isso, cada run produz snapshot diferente → "flaky tests" → ninguém confia → suite ignorada.
+
+### Pattern 6: Sanitização para snapshot
+
+Output cru pode incluir dados sensíveis ou voláteis. Sanitize ANTES de salvar:
+
+```ts
+function sanitizeForSnapshot(o: any): any {
+  return JSON.parse(
+    JSON.stringify(o, (key, value) => {
+      if (key === 'apiKey' || key === 'password' || key === 'token') return '***REDACTED***'
+      if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(value)) return '<TIMESTAMP>'
+      if (typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}/.test(value)) return '<UUID>'
+      return value
+    })
+  )
+}
+```
+
+Aplicar **antes** de `expect(...).toMatchSnapshot()`. Documentar quais campos foram sanitized para que reviewer entenda.
+
+### Pattern 7: Behavioral coverage check (mutation testing)
+
+Coverage de linha NÃO É proxy de safety. Para confirmar que characterization realmente cobre comportamento:
+
+```bash
+# JavaScript/TypeScript
+npx stryker run
+
+# Python
+mutmut run
+mutmut results
+
+# Java
+mvn pitest:mutationCoverage
+
+# Métrica desejada: ≥ 70% de mutants killed
+# Survived mutants = comportamento NÃO observado pelos tests = ponto cego
+```
+
+Survived mutant tipicamente indica que falta um observation point. Adicione um test que exercita o branch correspondente.
+
+### Pattern 8: Effort budget para characterization
+
+Dados empíricos baseados em arquivos típicos:
+
+| Tamanho do alvo | Inputs a gerar | Esforço típico | Cobertura esperada |
+|---|---|---|---|
+| Método 20-50 linhas, 1-3 branches | 5-7 inputs | 1-2h | 80-90% behavioral |
+| Método 50-150 linhas, 3-7 branches | 8-12 inputs | 3-6h | 70-85% behavioral |
+| Método 150+ linhas (monster) | 15-25 inputs | 1-3 dias | 60-75% behavioral (exigir cap 22 antes) |
+| Classe inteira 300-500 linhas | 20-40 inputs | 2-5 dias | 65-80% behavioral |
+| Arquivo > 500 linhas | proibido refatorar sem split first | depende | exigir extract class antes |
+
+**Não negocie cobertura para baixo "para ganhar tempo".** Cobertura insuficiente = false sense of safety, pior que ausência total.
+
+## Anti-patterns
+
+### ANTI: testar o "comportamento esperado"
+
+```text
+ANTI: "Vou escrever um teste do que o método deveria fazer e refatorar
+       até passar".
+
+PROBLEMA: o método tem bugs. Teste-do-esperado falha imediato porque o
+          estado atual É buggy. Você não consegue rodar nem 1 verde.
+          Frustrado, "ajusta" expected para o atual — perdeu o ponto
+          inteiro do exercício.
+
+CERTO: characterize first. Capture o que o código faz HOJE, com bugs.
+       Refactor preserva isso. Bug fix vem depois, em commit separado.
+```
+
+### ANTI: 1 teste cobrindo "happy path"
+
+```text
+ANTI: "Adicionei 1 test do caso comum, vai dar".
+
+PROBLEMA: branches raras (null, vazio, edge case) são exatamente onde
+          regressão se esconde. Refactor "verde" no test de happy path
+          mas quebra null handling silencioso → bug em prod no primeiro
+          input null real (1% do tráfego, mas existe).
+
+CERTO: 5+ inputs cobrindo grupos canônicos de equivalência. 1h a mais
+       de teste = N horas a menos de incident.
+```
+
+### ANTI: snapshot sem revisão
+
+```text
+ANTI: rodar code → toMatchSnapshot() → CI verde → commit. "Funcionou".
+
+PROBLEMA: snapshot pode incluir bug, PII, secret, UUID local. CI
+          "verde" só significa "snapshot está consistente com captura
+          anterior" — não que o conteúdo está certo.
+
+CERTO: ler snapshot inteiro antes de commit. Marcar bugs com comments,
+       redact PII com sanitize fn, verificar que não há secrets. Commit
+       de snapshot é decisão de produto, não automation.
+```
+
+### ANTI: mocks excessivos = teste de mock, não de código
+
+```text
+ANTI: tudo mockado — DB, HTTP, log, queue, clock, random. Test passa.
+
+PROBLEMA: você testou que o método chama os mocks na ordem certa, não
+          que o método produz output correto para entrada real. Refactor
+          que muda ORDEM de chamadas (igualmente correto) quebra mock
+          assertion mas é regressão zero.
+
+CERTO: minimize mocks. Use fakes que coletam side effects observáveis
+       (lista, counter), assert sobre o STATE final dos fakes, não
+       sobre sequência de invocações. Snapshot do state pós-execução
+       é mais resiliente que assertion de invocation order.
+```
+
+### ANTI: pular characterization "porque o método é simples"
+
+```text
+ANTI: "esse método tem 30 linhas, é óbvio o que faz, vou refatorar
+       direto".
+
+PROBLEMA: 30 linhas têm ~5-10 branches implícitas (early return, &&
+          short-circuit, exceções, type coercion). Cada branch é uma
+          assumption não-verificada. "Óbvio" é ilusão de quem escreveu
+          o código original — você está lendo, é diferente.
+
+CERTO: SEMPRE characterize, mesmo métodos curtos. 30 linhas → 5 inputs
+       → 30 minutos. Custo trivial. Benefício: zero "wait, eu não sabia
+       que isso retornava undefined em X". Descobre-se durante captura,
+       não em prod.
+```
+
+### ANTI: characterization em fase de bug fix
+
+```text
+ANTI: "Estou consertando bug X, vou aproveitar e characterize tudo
+       enquanto estou aqui".
+
+PROBLEMA: scope creep. PR vira inrevisável (bug fix + 50 testes novos
+          + redesenho mental). Linha entre "preservei comportamento" e
+          "modifiquei comportamento" desaparece.
+
+CERTO: bug fix é bug fix. Escreva 1 teste do COMPORTAMENTO CORRETO
+       (TDD agora, porque você está mudando intenção). Characterize é
+       fase prévia ao refactor — separa em PR/sprint próprio.
+```
+
+## Verificação
+
+Antes de iniciar refactor de código legado:
+
+1. **Inventário completo de inputs/outputs** — todos os parâmetros, globals lidos, I/O capturados
+2. **5+ inputs cobrindo grupos de equivalência** — empty, typical, boundary, invalid recoverable, invalid fatal
+3. **Snapshots revisados linha por linha** — bugs marcados, PII/secrets redacted
+4. **Determinismo garantido** — clock/uuid/random injetáveis, fakes substituem em teste
+5. **Side effects capturados** — DB writes, HTTP calls, logs, queue msgs incluídos no snapshot
+6. **Suite verde** — todos characterization tests rodam OK no main branch
+7. **Behavioral coverage medida** — mutation testing rodado, ≥ 70% mutants killed
+8. **Documentação no PR** — link para snapshots, lista de bugs preservados, fonte do oracle
+
+## Limiar de "pronto para refactor"
+
+```text
+Total inputs cobertos:               ≥ 5  (mínimo); 10+ recomendado
+Behavioral coverage (mutation kill): ≥ 70%
+Branches conhecidas testadas:        100% (todas as branches do código que será tocado)
+Side effects capturados:             100% (zero side effect "esquecido")
+Snapshots revisados:                 100% (cada arquivo lido por humano)
+Bugs documentados como TODO:         lista no PR
+Determinismo:                        OK em 10 runs consecutivos sem flaky
+```
+
+Se algum item < limiar → não inicie refactor. Volte para characterization.
+
+---
+
+## Ver também
+
+- [`_shared-legacy/glossary.md`](../_shared-legacy/glossary.md) — vocabulário canônico
+- [`legacy-seams-and-test-harness`](../legacy-seams-and-test-harness/SKILL.md) — quando characterization requer quebrar dependência primeiro
+- [`legacy-effect-analysis`](../legacy-effect-analysis/SKILL.md) — quais inputs escolher? effect sketch identifica
+- [`legacy-monster-methods`](../legacy-monster-methods/SKILL.md) — método > 100 linhas? characterization tem trato especial
+- [`legacy-sprout-wrap-techniques`](../legacy-sprout-wrap-techniques/SKILL.md) — alternativa quando characterization é caro demais (sprout side-steps)
+- [`pre-refactor-characterization`](../pre-refactor-characterization/SKILL.md) — gate auto-trigger que bloqueia refactor sem characterization
+- [`event-based-slos`](../event-based-slos/SKILL.md) (v1.9) — refactor pode regredir SLO; characterization protege
+- [`production-readiness-review`](../production-readiness-review/SKILL.md) (v1.10) — PRR Axe 5 (Change Management) verifica characterization antes de aceitar mudança em prod
+
+*Material-fonte: Working Effectively with Legacy Code — Feathers, 2004 — Cap 13: "I Need to Make a Change, But I Don't Know What Tests to Write" + Cap 23: "How Do I Know That I'm Not Breaking Anything?".*

package/kit/skills/legacy-effect-analysis/SKILL.md

@@ -0,0 +1,331 @@
+---
+name: legacy-effect-analysis
+description: Use ao decidir quais testes escrever em código sem testes — effect sketch (cap 11-12 Feathers) rastreia propagação de efeitos do change point para inflection/pinch points onde 1 teste cobre N caminhos.
+---
+
+# Legacy — Effect Analysis
+
+## Quando usar
+
+LLM carrega esta skill quando user precisa decidir QUAIS testes escrever em código legado. Trigger phrases:
+
+- "que tests preciso escrever para essa mudança?"
+- "como sei que cobri tudo?"
+- "effect sketch", "rastrear efeitos"
+- "cap 11 Feathers", "cap 12 Feathers"
+- "inflection point", "pinch point", "ponto de interceptação"
+- "muitas mudanças na mesma área"
+- "efeito propaga", "ripple effect"
+
+Carrega entre `legacy-seams-and-test-harness` (já tenho seam) e `legacy-characterization-tests` (vou escrever quais testes?). Resposta: testes nos pinch points.
+
+## Regras absolutas
+
+- **Effect = qualquer mudança observável após chamar o código.** 4 vetores: return value, parâmetros mutados, globals/state estático, side effects via colaborador (DB, HTTP, FS, log, queue).
+- **Effect sketch SEMPRE em papel/whiteboard primeiro.** Diagramar à mão, não em ferramenta. Velocidade > formato. Goal é entender, não documentar.
+- **Inflection point = funil estreito.** Lugar onde N caminhos convergem antes de divergir. 1 teste lá cobre N branches a montante. Foque tempo de teste aqui.
+- **Pinch point é definido pelo problema, não pela arquitetura.** "É onde os efeitos da minha mudança convergem", pode ou não coincidir com camadas/módulos.
+- **Effect-narrowing precede characterization.** Se sketch tem 30 efeitos, primeiro reduza superfície (encapsular variáveis, eliminar globals). Depois characterize a fronteira reduzida.
+- **Shotgun surgery = mesmo change espalhado em N lugares.** Effect sketch detecta. Resposta canônica: extrair para 1 lugar antes de mudar (cap 21 — Single Responsibility Principle aplicado retroativamente).
+- **Não confunda effect com call graph.** Call graph mostra QUEM chama QUEM. Effect sketch mostra O QUE MUDA. Função pode ser chamada 100 vezes e mudar nada (pure); função chamada 1 vez pode mudar 50 coisas.
+
+## Patterns canônicos
+
+### Pattern 1: 4 vetores de propagação de efeito
+
+```text
+1. RETURN VALUE
+   foo() retorna X → callers usam X em decisões/cálculos
+   Trace: grep callers de foo() + grep usos do resultado
+
+2. MUTATED PARAMETERS (output params)
+   foo(list) faz list.push(x) → caller continua a usar list mutada
+   Trace: parâmetros não-primitivos (objetos, arrays, ponteiros)
+
+3. GLOBAL / STATIC STATE
+   foo() faz globalCounter++ ou Foo.lastResult = X
+   Trace: writes em variáveis fora do escopo da função
+
+4. SIDE EFFECTS VIA COLLABORATOR
+   foo() chama db.save(), http.post(), log.warn(), fs.writeFile()
+   Trace: identificar colaboradores injetados/globais e verificar writes
+```
+
+**Heurística:** se um vetor é vazio, ótimo (efeito mais contido). Se múltiplos, sketch é necessário antes de qualquer change.
+
+### Pattern 2: Workflow de effect sketch (cap 11)
+
+```text
+1. DESENHAR change point
+   Caixa central com nome do método/variável que vai mudar.
+
+2. ENUMERAR EFEITOS DIRETOS (1 nível)
+   Setas saindo da caixa central para tudo que MUDA quando aquele
+   change point muda:
+   - retorno (caixa "return")
+   - cada parâmetro mutado
+   - cada global escrito
+   - cada side effect
+
+3. ENUMERAR EFEITOS DERIVADOS (2 níveis)
+   Para cada efeito direto, perguntar: "quem usa isso?"
+   - return é consumido por callers — desenhe callers
+   - parâmetros mutados — quem inspeciona estado?
+   - globals — todos os leitores
+   - side effects — todos os observadores (queue consumers, DB readers)
+
+4. CONTINUE até bordas naturais
+   - Outro processo/serviço (effect cruza process boundary)
+   - Caller que não inspeciona resultado
+   - Side effect terminal (log persistido, sem ler de volta)
+
+5. IDENTIFICAR INFLECTION POINTS
+   Pontos onde múltiplas setas convergem ou divergem.
+   Inflection point é "o gargalo" — testar ali cobre subgrafos inteiros.
+
+6. PRIORIZAR TESTES
+   Test escrito num inflection point cobre N efeitos a montante.
+   1 teste em pinch point > 10 testes em folhas.
+```
+
+### Pattern 3: Exemplo concreto — sketch de OrderProcessor.processOrder()
+
+```text
+                        ┌──────────────────┐
+                        │ Order.discount   │ ← change point (mudando lógica)
+                        └────────┬─────────┘
+                                 │
+        ┌────────────────────────┼─────────────────────────┐
+        ▼                        ▼                         ▼
+  Order.totalCents        OrderEvent.payload         AuditLog.entry
+        │                        │                         │
+        ▼                        ▼                         ▼
+   PaymentRequest.amount    EventBus.publish         AuditDB.write
+        │                        │                         │
+        ▼                        ▼                         ▼
+   Stripe.charge        QueueConsumers (3 svcs)     ComplianceReader
+        │
+        ▼
+   bank ledger
+```
+
+**Inflection point óbvio:** `Order.totalCents` — TODOS os efeitos no payment side passam por essa propriedade.
+
+**Estratégia de testes:**
+- 1 test que asserta `Order.totalCents` para 5+ inputs (boundary, typical, etc.) → cobre subárvore Stripe inteira sem precisar mockar Stripe
+- 1 test que asserta `OrderEvent.payload` shape → cobre EventBus side
+- 1 test que asserta `AuditLog.entry` shape → cobre Audit side
+
+3 testes de 5 minutos cada cobrem 15+ pontos de propagação. Sem sketch, escreveria 15 testes em 5 lugares diferentes.
+
+### Pattern 4: Heurísticas para encontrar inflection points
+
+| Sintoma no sketch | Provável inflection |
+|---|---|
+| Várias setas convergem em 1 nó antes de irradiar | Esse nó (estado intermediário) |
+| Bordas de processo (call externo) | Antes da borda (assertar mensagem enviada) |
+| Pontos de serialização/desserialização | Bem ali — congele forma serializada |
+| Persistência (DB write) | Snapshot do row escrito |
+| Eventos publicados em queue/bus | Snapshot do event payload |
+| Function purity (sem side effect) | Return value direto |
+
+### Pattern 5: Effect-narrowing (cap 12)
+
+Quando sketch tem 20+ efeitos, primeiro REDUZA antes de testar. Técnicas:
+
+| Técnica | Reduz | Trade-off |
+|---|---|---|
+| **Encapsular variável global** | Globals viram fields → menos vetor 3 (state) | Caller pode precisar passar instância |
+| **Imutabilidade no parâmetro** | Mutated params viram return values → menos vetor 2 | Allocation a cada call |
+| **Extract method para state mutation** | Side effect concentrado em 1 método (pinch criado) | + 1 método na classe |
+| **Replace temp with query** | Variável local → método; reduz dispersão | Computação repetida |
+| **Move method (fora de classe X para Y)** | Effect sai do escopo de X → menos efeito a rastrear em X | Pode quebrar outros sketches |
+
+**Princípio:** narrowing é PRECEDENTE a refactor. Faça-o com características de "pure mechanical" — pequena, reversível, comportamento idêntico.
+
+### Pattern 6: 4 perguntas canônicas antes de change
+
+```text
+1. "Que efeitos esse change tem?"
+   → desenhe sketch (vetores 1-4)
+
+2. "Onde converge antes de divergir?"
+   → inflection point(s)
+
+3. "O que preciso testar para SENSE essas convergências?"
+   → 1 test por inflection (input variado), assertando estado intermediário
+
+4. "Quais são as bordas naturais?"
+   → onde termina o sketch; depois disso é território de outras teams/serviços
+```
+
+### Pattern 7: Detect shotgun surgery via sketch
+
+Se ao desenhar sketch para mudança X, você encontra que X aparece em N lugares idênticos espalhados:
+
+```text
+                       (mudança X)
+                            │
+       ┌───────┬────────┬───┴───┬────────┬───────┐
+       ▼       ▼        ▼       ▼        ▼       ▼
+   FileA    FileB    FileC   FileD    FileE   FileF
+   linha    linha    linha   linha    linha   linha
+   42       189      67      23       104     56
+```
+
+**Sintoma:** mesma lógica copiada em N pontos.
+**Resposta:** ANTES de mudar, extrair para função/classe única (cap 21). Depois, mudança vira UM ponto. Effect sketch original com 6 setas vira 1 seta para 1 ponto.
+
+### Pattern 8: Effect sketch tooling
+
+Não precisa de ferramenta sofisticada. Em ordem de preferência:
+
+1. **Papel + caneta** (sempre primeiro — velocidade)
+2. **Whiteboard físico** (se mais que 1 pessoa)
+3. **Whiteboard digital** (Excalidraw, Miro) — quando precisa salvar/compartilhar
+4. **Texto ASCII em PR description** (quando vira artefato persistente)
+5. **Mermaid graph** (last resort — overhead de syntax > benefit visual)
+
+**Anti-tooling:** UML "official", Visio, ferramentas que exigem layout perfeito. Sketch é descartável e iterativo.
+
+### Pattern 9: Heurística de cobertura via inflection
+
+Para mudança em legacy code, cobertura mínima = 1 test por inflection point.
+
+```text
+N inflection points identificados via sketch
+× 5+ inputs cobrindo grupos de equivalência (ver legacy-characterization-tests Pattern 2)
+= N × 5 testes mínimos para refactor
+
+Se muito alto (50+), considere effect-narrowing primeiro.
+Se muito baixo (1 inflection × 5 inputs = 5), provavelmente sketch
+incompleto — verifique se cobriu todos os 4 vetores.
+```
+
+## Anti-patterns
+
+### ANTI: pular sketch "porque é óbvio"
+
+```text
+ANTI: "esse método tem 50 linhas, eu vejo o que ele faz, vou testar
+       direto".
+
+PROBLEMA: efeitos não-óbvios são exatamente os que escapam:
+          - mutação de parâmetro objeto que caller depende
+          - side effect via dependency injetada (parece pure mas não é)
+          - global lido condicionalmente em caminho raro
+          Bug em prod 3 semanas depois pelos efeitos não-vistos.
+
+CERTO: SEMPRE 5 minutos de sketch. Mesmo método "óbvio" → desenhe,
+       confirme, então teste. 5 min poupam horas.
+```
+
+### ANTI: testar todas as folhas do sketch
+
+```text
+ANTI: 30 setas no sketch → 30 testes (1 por folha).
+
+PROBLEMA: massive test suite, slow CI, alto custo de manutenção,
+          tests redundantes (várias folhas testam mesma branch a
+          montante). Sinal de "test theatre" — looks safe but isn't.
+
+CERTO: 1 teste por inflection point. Se inflection cobre 10 folhas,
+       teste lá. Folhas só ganham teste próprio se há comportamento
+       distinto (folha = inflection menor naquele contexto).
+```
+
+### ANTI: testar APENAS na superfície (1 nível de sketch)
+
+```text
+ANTI: testar só `processOrder` retorno, sem verificar side effects.
+
+PROBLEMA: side effects são tipicamente onde regressão escapa.
+          processOrder pode retornar valor correto MAS escrever no
+          DB errado, publicar event errado, logar PII. Test verde
+          mascara breakage.
+
+CERTO: percorrer sketch completo. Side effect significativo
+       (DB write, event publish, log) recebe assertion no test
+       relevante. Use fakes que coletam side effects, asserte sobre
+       state final do fake.
+```
+
+### ANTI: confundir call graph com effect sketch
+
+```text
+ANTI: "fiz um call graph IDE-generated, isso é meu effect sketch".
+
+PROBLEMA: call graph mostra "fooCallsBar". Não mostra que `bar`
+          modifica global lido por `baz` que retorna decisão para
+          `qux`. Effect path passa por chamadas + state, não só
+          chamadas.
+
+CERTO: sketch tem que ser feito por pessoa, lendo código, perguntando
+       "o que muda?". Call graph é input ao sketch, não substituto.
+```
+
+### ANTI: change com sketch não-validado
+
+```text
+ANTI: desenhei sketch, achei 3 inflection points, escrevi tests,
+      mudei código. Sketch não foi validado contra o código real
+      por outra pessoa.
+
+PROBLEMA: effect omitido (vetor 4 — side effect via colaborador raro)
+          significa teste ausente significa regressão escapa.
+
+CERTO: sketch validado por 2ª pessoa OU validado contra mutation
+       testing. Mutants survived = pontos não-cobertos = potencial
+       gap no sketch original.
+```
+
+### ANTI: shotgun surgery sem extract first
+
+```text
+ANTI: "mesma lógica em 6 lugares, vou alterar todos os 6".
+
+PROBLEMA: 6 chances de errar. PR de 600 linhas. Test exigiria 6×
+          characterization. Próxima mudança = mesma cirurgia.
+
+CERTO: extract first (cap 21). PR1 — extrair para função única,
+       cada chamada vira call para a função. PR2 — alterar a função.
+       Sketch original encolhe de 6 setas → 1 seta. Tests também.
+```
+
+## Verificação
+
+Antes de declarar effect analysis completa:
+
+1. **Sketch desenhado** — papel/whiteboard com change point central + 4 vetores explorados
+2. **Todos os 4 vetores considerados** — return, mutated params, globals, side effects via collaborator
+3. **Pelo menos 1 inflection point identificado** — se não, sketch incompleto OU change é trivial demais
+4. **Effect-narrowing aplicado** se sketch tem > 15 efeitos
+5. **Plano de testes derivado do sketch** — N testes em inflection points, NÃO em folhas
+6. **Sketch validado** — 2ª pessoa OR mutation testing pós-implementação
+7. **Bordas naturais identificadas** — onde para de rastrear (process boundary, terminal side effect)
+
+## Limiar de "pronto para testar/refatorar"
+
+```text
+Sketch desenhado:                       sim
+Vetores 1-4 enumerados:                 todos cobertos
+Inflection points identificados:        ≥ 1 (1-3 típico)
+Plano de testes mapeado para sketch:    sim (1 teste por inflection)
+Cobertura esperada com tests planejados: ≥ 70% behavioral
+Effect-narrowing aplicado:              se necessário
+```
+
+Se algum item incompleto → não inicie testes/refactor. Volte ao sketch.
+
+---
+
+## Ver também
+
+- [`_shared-legacy/glossary.md`](../_shared-legacy/glossary.md) — vocabulário (effect sketch, inflection point, pinch point, shotgun surgery)
+- [`legacy-characterization-tests`](../legacy-characterization-tests/SKILL.md) — characterization rodada NOS inflection points achados aqui
+- [`legacy-seams-and-test-harness`](../legacy-seams-and-test-harness/SKILL.md) — break-deps em inflection points = test harness mínimo
+- [`legacy-monster-methods`](../legacy-monster-methods/SKILL.md) — monster method tem sketch interno (em uma única função)
+- [`legacy-sprout-wrap-techniques`](../legacy-sprout-wrap-techniques/SKILL.md) — sprout point ideal = inflection point pré-existente
+- [`pre-refactor-characterization`](../pre-refactor-characterization/SKILL.md) — gate exige effect sketch para refactor de arquivos grandes/críticos
+
+*Material-fonte: Working Effectively with Legacy Code — Feathers, 2004 — Cap 11: "I Need to Make a Change. What Methods Should I Test?" + Cap 12: "I Need to Make Many Changes in One Area" + Cap 16: "I Don't Understand the Code Well Enough to Change It".*