Modulo 5.6: Promotion: 3-strikes → CLAUDE.md

🎯 O que e promotion

Padrao visto 3 ou mais vezes prova valor. Viram regra em CLAUDE.md, originais arquivam.

📐 Ciclo de promotion

Observacao #1 → knowledge/patterns/idempotency-stripe.md
Observacao #2 → knowledge/patterns/idempotency-retry.md
Observacao #3 → knowledge/patterns/idempotency-refund.md
                           │
                           ▼
              Script detecta similaridade
                           │
                           ▼
          promotions/pending.md criada
                           │
                           ▼
              Voce revisa e aprova
                           │
                           ▼
       CLAUDE.md: "Sempre usar idempotency
                    key em payment webhook."
                           │
                           ▼
      3 observacoes movem para archive/promoted/

💡 E um pipeline, nao magica

Promotion nao e detectada magicamente. E script explicito que voce roda periodicamente. Tudo transparente.

🧠 Detectando padrao (LLM-assisted)

Regex nao pega similaridade semantica. LLM pequeno resolve em segundos.

📐 Deteccao via LLM

#!/usr/bin/env python3
# promote.py — versao LLM-assisted

def find_clusters(memories, threshold=3):
    # 1. Gera embedding de cada memoria
    embs = embed_all([m.body for m in memories])

    # 2. Clustering com similarity > 0.85
    clusters = []
    for i, emb_i in enumerate(embs):
        for cluster in clusters:
            if cosine(emb_i, cluster[0].emb) > 0.85:
                cluster.append(memories[i])
                break
        else:
            clusters.append([memories[i]])

    # 3. Retornar clusters com threshold+
    return [c for c in clusters if len(c) >= threshold]

# Uso
candidates = find_clusters(load_memories('knowledge/patterns/'))
for cluster in candidates:
    write_proposal(cluster, 'promotions/pending.md')

💡 Custo minimo

Embeddings locais (fastembed) = 0 recorrente. Clustering passa por 200-500 memorias em ~2 segundos.

✍️ Formato da regra promovida

Formato prescritivo vence descritivo. Claude age sobre um, menciona o outro.

✓ Prescritivo (usar)

✓'Sempre usar idempotency key em payment webhook'
✓'Sempre logar tempo de execucao em hooks'
✓'Nunca commitar .env; usar .env.example'
✓'Ao abrir PR, rodar ruff check primeiro'

✗ Descritivo (evitar)

✗'Observamos que idempotency key ajuda em webhooks'
✗'Ja vimos que logar tempo e util'
✗'Geralmente nao commitamos .env'
✗'Costumamos rodar ruff antes de PR'

🔐 Aprovacao humana

NUNCA promova automatico direto ao CLAUDE.md. Sempre com review.

📐 Fluxo com approval

# Script cria proposta
$ python3 promote.py
3 padroes candidatos criados em:
  ~/.memory/promotions/pending.md

# Voce revisa
$ cat ~/.memory/promotions/pending.md

## Proposta 1 (3 ocorrencias)
Origem: patterns/idempotency-{stripe,retry,refund}.md

Regra sugerida:
"Sempre usar idempotency key em payment webhook
 para evitar processamento duplicado."

[APROVAR] [REJEITAR] [EDITAR]

# Apos editar/aprovar
$ python3 promote.py --apply

Aprovou: 2 regras adicionadas a CLAUDE.md
Rejeitou: 1 proposta descartada
Movidas: 6 memorias originais para archive/promoted/

⚠️ CLAUDE.md poluido e pior que vazio

Uma regra mal escrita contamina a atencao para todas. Qualidade da curadoria importa mais que velocidade.

🗑️ O que acontece com os originais

Arquivam, nao deletam. Rastreio preservado para revisao futura.

📐 Archive com rastreio

archive/promoted/
└── 2026-Q2/
    └── idempotency-webhook-rule/
        ├── SOURCE_MEMORIES/
        │   ├── idempotency-stripe.md
        │   ├── idempotency-retry.md
        │   └── idempotency-refund.md
        └── PROMOTED_RULE.md
            "Extraida em 2026-04-22. Adicionada a CLAUDE.md.
             Regra: 'Sempre usar idempotency key em payment webhook.'"

# Se 6 meses depois voce revisita regra:
# → acha rastreamento
# → ve as 3 observacoes originais
# → entende o porque completo

💡 Provenance importa

Dali 1 ano, voce pode perguntar 'por que temos essa regra?'. Archive responde.

📝 Exemplo ponta a ponta

Seguindo o ciclo inteiro: 3 observacoes → regra permanente.

Observacao 1 (2026-04-10)

Sessao resolve bug na Stripe webhook. Voce nota: 'idempotency key evitou dupla cobranca'. Salvo em patterns/idempotency-stripe.md

Observacao 2 (2026-04-15)

Bug similar em webhook de retry. 'Idempotency key aqui tambem resolveu.' Salvo em patterns/idempotency-retry.md

Observacao 3 (2026-04-20)

Agora no refund webhook. 'Mesmo padrao.' Salvo em patterns/idempotency-refund.md

promote.py roda (2026-04-22)

Detecta cluster com similaridade 0.91. Cria proposal em pending.md

Voce aprova

Regra 'Sempre usar idempotency key em payment webhook' adicionada a CLAUDE.md

Originais arquivam

3 memorias movem para archive/promoted/2026-Q2/idempotency-webhook-rule/

Sessoes futuras

Claude ja sabe aplicar. Voce nunca mais explica. Memoria virou sabedoria.

💡 Meta alcancada

Esse e o sistema de memoria maduro: capta observacoes, deteta padroes, graduacao automatica (com approval), resultado e Claude mais inteligente no seu contexto especifico.

📝 Resumo do Modulo

✓

3x e o gatilho — menos e cedo demais.

✓

LLM faz clustering — regex nao pega similaridade semantica.

✓

Formato prescritivo — 'sempre X quando Y' > 'observamos X'.

✓

Aprovacao humana obrigatoria — CLAUDE.md ruim e pior que ausente.

Proximo:

Trilha 6 — Projeto pratico e integracoes

← Modulo anterior Trilha 6 →