iron-edge 1.0.0

package/squads/squad-research/knowledge-base/community-research-methods.md

@@ -0,0 +1,194 @@
+# Community Research Methods
+
+> Extraído e sintetizado de MS-010 Forum & Community Platform Engineering (2026) — análise de Reddit, Discord, Stack Overflow, Discourse e outras plataformas com dados de 2025-2026.
+
+## Fundamentos Teóricos
+
+### Barabási-Albert Model (Redes Scale-Free)
+Redes sociais reais não são aleatórias — seguem power-law degree distributions onde poucos nós (hubs) têm vastamente mais conexões que a maioria.
+
+**Dois mecanismos:**
+1. **Growth:** Redes adicionam continuamente novos nós
+2. **Preferential attachment:** Novos nós preferem conectar a nós já bem conectados ("rich-get-richer")
+
+**Distribuição:** P(k) ~ k^(-gamma), tipicamente gamma entre 2 e 3.
+
+**Aplicação em research:** Identifique os hubs de uma comunidade/mercado — eles movem informação e opinião de forma desproporcional. Em análise competitiva, os "subreddits hub" são pontes entre clusters de usuários.
+
+### Granovetter: Força dos Laços Fracos (1973)
+Paradoxo fundamental: **laços fracos (conhecidos) são mais valiosos que laços fortes (amigos íntimos)** para difusão de informação.
+
+**Por quê:** Laços fortes clusters dentro de grupos densos onde todos compartilham a mesma informação. Laços fracos fazem ponte entre clusters, permitindo que informação nova flua.
+
+**Duas hipóteses centrais:**
+1. Laços fortes se concentram em grupos densamente conectados
+2. Grupos são conectados por laços fracos esparsos — vitais para difusão
+
+**Aplicação em research:** Para entender como uma ideia/tendência se propaga, mapeie os laços fracos (bridges entre comunidades), não apenas os laços fortes (influenciadores dentro de uma comunidade).
+
+## Network Effects: Taxonomia para Pesquisa
+
+| Tipo | Definição | Exemplo para Pesquisa |
+|------|-----------|----------------------|
+| **Direct** | Mais usuários = mais valor para todos | Mais usuários de uma plataforma = mais dados para análise |
+| **Indirect** | Mais usuários atraem bens complementares | Mais usuários = mais criadores de conteúdo a monitorar |
+| **Cross-side** | Grupo A beneficia Grupo B | Mais compradores = mais vendedores a estudar |
+| **Same-side** | Grupo beneficia a si mesmo | Mais respondentes = pesquisa mais representativa |
+| **Data** | Mais uso = algoritmos melhores | Mais buscas = melhores insights de intenção |
+| **Local** | Network effects dentro de sub-clusters | Comunidade de nicho tem mais relevância que plataforma geral |
+
+## Leis Matemáticas de Redes
+
+### Metcalfe's Law
+**V = n²** (onde V = valor da rede, n = usuários)
+
+- Facebook: revenue ao longo de uma década seguiu curva n-squared
+- Implicação para research: uma plataforma com 2x os usuários tem potencialmente 4x o valor como fonte de dados/insights
+- **Limitação:** Assume todas as conexões igualmente valiosas — raramente verdade
+
+### Reed's Law
+**V = 2^n** (redes que formam grupos)
+
+- Plataformas que suportam grupos (Discord servers, Facebook Groups, Slack) capturam mais valor
+- Função como limite teórico superior — nunca observado completamente na prática
+- **Implicação para research:** Plataformas com sub-comunidades têm mais pontos de pesquisa que plataformas com conexões apenas diáticas
+
+### Andrew Chen's Death Spiral
+Network effects funcionam em ambas as direções. Se usuários saem, a rede perde valor → mais usuários saem → aceleração do declínio.
+
+**Implicação para research:** Monitorar saúde de comunidades é crítico. Métricas de saída antecipam declínio antes que seja evidente nos dados de crescimento.
+
+## Social Graph Analysis em Prática
+
+### Modelos de Grafo por Plataforma
+
+| Plataforma | Modelo de Grafo | Característica-Chave |
+|------------|----------------|---------------------|
+| Reddit | Bipartite (usuários ↔ subreddits) | Routing de conteúdo por assinatura |
+| Discord | Hierárquico (servers → categories → channels) | Controle de acesso por role |
+| Stack Overflow | Tripartite (usuários ↔ perguntas ↔ tags) | Clustering de expertise por tag |
+| LinkedIn | Degrees of connection (1st, 2nd, 3rd) | Alcance profissional por grau |
+| Twitter/X | Directed (follow) + Undirected (mentions) | Influência assimétrica |
+
+### Algoritmos de Detecção de Comunidade
+- **Louvain Method:** Detecta clusters por maximização de modularidade — bom para comunidades grandes
+- **Label Propagation:** Rápido e escalável — cada nó adota label mais comum de seus vizinhos
+- **Girvan-Newman:** Remove arestas de maior betweenness progressivamente — revela hierarquia de comunidades
+
+### Métricas de Grafo para Research
+
+| Métrica | O Que Indica | Uso em Research |
+|---------|-------------|-----------------|
+| **Degree Centrality** | Quantas conexões diretas um nó tem | Identificar influenciadores/hubs |
+| **Betweenness Centrality** | Quantas vezes um nó está no caminho entre outros | Identificar brokers de informação |
+| **Closeness Centrality** | Distância média para todos os outros nós | Identificar nós com acesso rápido à rede |
+| **PageRank** | Importância considerando quem aponta para o nó | Ranquear influência em redes direcionadas |
+| **Clustering Coefficient** | Quão conectados estão os vizinhos de um nó | Detectar echo chambers |
+
+## Algoritmos de Ranking de Conteúdo em Comunidades
+
+### Reddit Hot Algorithm
+```
+hot_score = log10(max(|score|, 1)) * sign(score) + (timestamp / 45000)
+```
+- Score = upvotes - downvotes
+- **Propriedades:** Scaling logarítmico de votos; tempo nunca decresce; half-life de 12.5 horas
+- **Para research:** Os primeiros votos têm impacto desproporcional — posts virais não são necessariamente os melhores
+
+### Hacker News Gravity Algorithm
+```
+score = (P - 1) / (T + 2)^G
+```
+- P = pontos, T = horas desde submissão, G = gravity (default 1.8)
+- **Propriedades:** Decaimento ativo ao longo do tempo; tunable gravity
+- **Para research:** Conteúdo técnico/nicho tem vida mais longa que HN do que em Reddit
+
+### Wilson Score Interval (Stack Overflow Best Sort)
+Ranqueia pelo limite inferior do intervalo de confiança para aprovação real:
+- Corrige para amostras pequenas: 5 upvotes/0 downvotes pode superar 100 upvotes/40 downvotes
+- **Para research:** Melhor proxy de "qualidade real" que simples contagem de votos
+
+## Métodos de Pesquisa de Comunidade
+
+### Digital Ethnography
+Observação sistemática de comunidades online:
+1. **Lurking phase:** 2-4 semanas observando sem intervir — entender normas, gírias, hierarquias
+2. **Mapping phase:** Identificar key contributors, hubs, tipos de conteúdo, horários de pico
+3. **Analysis phase:** Classificar interações, tensões, padrões emergentes
+4. **Validation phase:** Confirmar interpretações com membros da comunidade (se aplicável)
+
+### Netnografia (Kozinets 2002, atualizado 2020)
+Adaptação da etnografia para ambientes digitais:
+- Imersão cultural (participar genuinamente)
+- Coleta de dados naturais (não interferir no comportamento)
+- Interpretação cultural (entender significado, não apenas frequência)
+- **Diferencial:** Captura como comunidades criam significado, não apenas o que dizem
+
+### Community Health Monitoring
+Métricas para monitorar saúde de uma comunidade ao longo do tempo:
+
+| Métrica | Sinal Saudável | Sinal de Alerta |
+|---------|---------------|-----------------|
+| DAU/MAU ratio | >15% | <5% |
+| D1 retention | >40% | <20% |
+| D7 retention | >25% | <10% |
+| Post/member ratio | Crescendo | Declinando 3+ semanas |
+| Response rate | >60% de posts respondidos | <30% |
+| Moderator actions | Estável | Crescente aceleradamente |
+
+## Trust e Reputação em Comunidades
+
+### Discourse Trust Levels (Gold Standard)
+
+| Level | Nome | Como Ganho | Privilégios-Chave |
+|-------|------|-----------|-------------------|
+| TL0 | New | Default | Ações básicas |
+| TL1 | Basic | Ler tópicos, tempo no site | PMs, flags |
+| TL2 | Member | Participação ativa (semanas) | Convites, wiki posts |
+| TL3 | Regular | Participação sustentada (meses) | Recategorizar, mover tópicos; auto-revogado se cair |
+| TL4 | Leader | Concedido por admins | Poderes totais de moderação |
+
+**Insight para research:** Trust levels são o melhor proxy para qualidade de contributor. Análise de TL3+ revela comunidade "real" de especialistas.
+
+### Stack Overflow Reputation-Privilege Model
+- +10 por upvote em resposta; +15 por accepted answer
+- Cap de 200 rep/dia (previne grinding)
+- Privilégios progressivos: 15 rep → upvote; 125 rep → downvote; 2,000 → editar qualquer post
+
+**Insight para research:** Reputação de 1,000+ indica expertise genuína. Padrões de upvote revelam consenso técnico da comunidade.
+
+## Fontes de Dados para Community Research
+
+### APIs Oficiais
+- **Reddit API:** Free tier limitado (100 req/min); dados históricos via Pushshift (parcialmente disponível)
+- **Stack Exchange API:** API pública, 10,000 req/dia sem auth
+- **Discord:** Apenas próprios servers via bot
+- **GitHub API:** Issues, discussions, contribution graphs
+
+### Ferramentas de Análise
+| Ferramenta | Foco | Gratuito? |
+|-----------|------|-----------|
+| Brandwatch | Social listening enterprise | Não |
+| Pulsar | Audience intelligence | Não |
+| SparkToro | Audience research (onde passam tempo) | Parcialmente |
+| Followerwonk | Twitter/X análise | Parcialmente |
+| Social Blade | YouTube/Twitch stats | Sim |
+
+### Dados Estruturados Públicos
+- **Reddit:** Subreddit stats via third-party (Subreddit Stats, Redditmetis)
+- **Stack Overflow:** Data Explorer (SEDE) — queries SQL completas em dados públicos
+- **GitHub:** Trending repositories, dependency graphs públicos
+
+## Armadilhas em Community Research
+
+| Armadilha | Descrição | Mitigação |
+|-----------|-----------|-----------|
+| Vocal minority | 1% cria conteúdo, 9% reage, 90% lurka | Complementar com surveys representativos |
+| Platform sample bias | Comunidade Reddit ≠ mercado geral | Triangular com dados offline/outros canais |
+| Survivorship | Só vê comunidades ativas, não as que morreram | Incluir análise de comunidades fracassadas |
+| Gaming detection | Bots, coordenação artificial, astroturfing | Verificar padrões de criação de conta, timing de posts |
+| Temporal drift | Normas de comunidades mudam rapidamente | Análise longitudinal, não snapshots únicos |
+
+---
+
+*Knowledge base da squad-research | Fonte: MS-010 Forum & Community Platform Engineering*

package/squads/squad-research/knowledge-base/competitive-analysis-frameworks.md

@@ -0,0 +1,122 @@
+# Competitive Analysis Frameworks
+
+## 1. Competitive Landscape Mapping
+
+### Quando Usar
+Visao geral de todos os players no mercado — quem compete, como, e onde ha espacos vazios.
+
+### Como Aplicar
+1. Listar todos os competidores (diretos, indiretos, substitutos)
+2. Classificar por tipo e relevancia
+3. Plotar em mapa 2x2 com eixos relevantes
+4. Identificar clusters e white spaces
+
+### Eixos Comuns para 2x2
+- Preco × Qualidade
+- Escopo × Especialização
+- Enterprise × SMB
+- Self-serve × High-touch
+- Generalista × Nichado
+
+## 2. Competitor Profiling
+
+### Template de Perfil
+- **Overview:** Fundacao, tamanho, funding, mercado, HQ
+- **Produto:** Core features, diferenciacao, pricing model
+- **Target:** Quem serve, ICPs, segmentos
+- **GTM:** Canais, messaging, sales model
+- **Estrategia:** Growth strategy, moat, next moves
+- **SWOT resumido:** Top 3 S/W/O/T
+- **Threat Level:** CRITICO / ALTO / MEDIO / BAIXO
+
+## 3. Feature Comparison Matrix
+
+### Como Construir
+1. Listar features relevantes (20-30 max)
+2. Agrupar por categoria (core, advanced, integration, support)
+3. Classificar: ✅ (tem), ⚠️ (parcial), ❌ (nao tem), 🏆 (melhor da classe)
+4. Calcular score por categoria e total
+5. Identificar gaps e oportunidades
+
+## 4. Positioning Perceptual Maps
+
+### Como Construir
+1. Selecionar 2 dimensoes relevantes para o mercado
+2. Plotar competidores nas dimensoes
+3. Identificar clusters (muitos players) e espacos vazios
+4. Avaliar: nosso posicionamento desejado esta em espaco vazio ou cluster?
+
+### Dimensoes Comuns
+- Innovation vs Tradition
+- Price vs Value
+- Simplicity vs Power
+- Niche vs Broad
+- B2B vs B2C focus
+
+## 5. Win/Loss Analysis
+
+### Quando Usar
+Entender por que clientes escolhem (ou nao) voce vs competidores.
+
+### Como Executar
+1. Entrevistar clientes que GANHARAM (por que escolheram nos?)
+2. Entrevistar prospects que PERDERAM (por que escolheram o competidor?)
+3. Categorizar razoes: produto, preco, relacionamento, marca, timing
+4. Calcular win rate por competidor, segmento, deal size
+5. Identificar padroes actionable
+
+## 6. Battle Card Creation
+
+### Estrutura (1-2 Paginas)
+- **Overview:** Quem sao, o que fazem (3 linhas)
+- **Nos vs Eles:** Tabela comparativa (5-7 criterios)
+- **Nossos diferenciais:** Top 3 razoes para nos escolher
+- **Fraquezas deles:** Top 3 vulnerabilidades
+- **Killer questions:** Perguntas que expoe fraquezas deles
+- **Objecoes comuns:** Top 3 objecoes + respostas
+- **Quando perdemos:** Situacoes onde eles ganham
+- **Red flags:** Sinais de que estao no deal
+
+## 7. Competitive Moat Analysis
+
+### 7 Tipos de Moat
+1. **Network Effects:** Valor aumenta com mais usuarios
+2. **Switching Costs:** Custo de trocar e alto
+3. **Economies of Scale:** Custo por unidade cai com volume
+4. **Brand:** Marca cria preferencia e confianca
+5. **Intellectual Property:** Patentes, proprietary tech
+6. **Regulatory:** Licencas, compliance como barreira
+7. **Data:** Dados proprietarios criam vantagem
+
+### Para Cada Moat
+- Competidor tem? (sim/nao/parcial)
+- Quao forte e? (1-5)
+- Nos temos? (sim/nao/parcial)
+- Podemos construir? (viavel/dificil/impossivel)
+
+## 8. Strategic Group Mapping
+
+### Quando Usar
+Identificar grupos de competidores com estrategias similares.
+
+### Como Aplicar
+1. Escolher 2 variaveis estrategicas (ex: escopo × investimento em R&D)
+2. Plotar competidores
+3. Desenhar circulos ao redor de clusters
+4. Cada circulo = strategic group
+5. Analisar: mobilidade entre grupos, barreiras, dinamicas
+
+## 9. Blue Ocean ERRC Canvas
+
+### Os 4 Quadrantes
+- **Eliminate:** Que fatores o mercado compete que devemos ELIMINAR?
+- **Reduce:** Que fatores devemos REDUZIR bem abaixo do padrao?
+- **Raise:** Que fatores devemos ELEVAR bem acima do padrao?
+- **Create:** Que fatores devemos CRIAR que o mercado nunca ofereceu?
+
+### Resultado
+Strategy canvas mostrando nossa curva de valor vs mercado — diferenciacao visual clara.
+
+---
+
+*Knowledge base da squad-research*

package/squads/squad-research/knowledge-base/cross-squad-integration-protocol.md

@@ -0,0 +1,103 @@
+# Cross-Squad Integration Protocol
+
+## Inbound Requests (Recebendo de Outros Squads)
+
+### Formato de Request
+```yaml
+research_request:
+  from_squad: [nome do squad]
+  requester: [agente]
+  type: [ad-hoc | sprint-task | strategic]
+  question: [pergunta clara]
+  context: [por que precisa disso]
+  depth: [SCAN | ANALYZE | DEEP DIVE | DEFINITIVE]
+  deadline: [data]
+  output_format: [brief | report | data | deck]
+```
+
+### Priorizacao de Requests
+1. **P0 (Urgente):** Bloqueia decisao critica, deadline <48h
+2. **P1 (Alta):** Impacta sprint ativo, deadline <1 semana
+3. **P2 (Media):** Planejamento futuro, deadline <2 semanas
+4. **P3 (Baixa):** Nice to have, sem deadline rigido
+
+### SLA por Prioridade
+- P0: Resposta em 4h, entrega em 24h (SCAN ou ANALYZE)
+- P1: Resposta em 24h, entrega em 3-5 dias
+- P2: Resposta em 48h, entrega em 1-2 semanas
+- P3: Backlog, entrega quando possivel
+
+## Outbound Deliverables (Entregando para Outros Squads)
+
+### brand-system
+- **Precisa de:** Personas com valores e arquetipos, insights culturais, posicionamento competitivo
+- **Formato:** Persona cards + psychographic summary + competitive positioning map
+- **Agentes que recebem:** Meridian (orchestrator), Prism (brand strategist)
+
+### content-intelligence
+- **Precisa de:** Topicos prioritarios, dados de audiencia, tendencias de busca
+- **Formato:** Topic list com volume/relevancia + audience preference matrix
+- **Agentes que recebem:** Nexus (orchestrator), Radar (trend detector)
+
+### copywriting-persuasion
+- **Precisa de:** Pain points, JTBD, gatilhos emocionais, objecoes
+- **Formato:** Messaging framework inputs + objection handling guide
+- **Agentes que recebem:** Voice strategist, persuasion architect
+
+### digital-experience
+- **Precisa de:** Journey maps, behavior data, tech trends, UX benchmarks
+- **Formato:** Journey maps + touchpoint data + UX trend brief
+- **Agentes que recebem:** UX researcher, experience architect
+
+### growth-analytics
+- **Precisa de:** TAM/SAM/SOM, segments, growth rates, conversion benchmarks
+- **Formato:** Data tables + projections + benchmark report
+- **Agentes que recebem:** Growth strategist, data analyst
+
+### commercial-systems
+- **Precisa de:** Battle cards, pricing data, market sizing, ICP
+- **Formato:** Sales enablement package (battle cards + pricing comparison + ICP scorecard)
+- **Agentes que recebem:** Sales strategist, pricing analyst
+
+### product-systems
+- **Precisa de:** Market gaps, opportunities, tech radar, unmet needs
+- **Formato:** Opportunity cards + tech radar + competitive feature matrix
+- **Agentes que recebem:** Product strategist, feature analyst
+
+## Handoff Artifact Format
+
+```yaml
+research_handoff:
+  id: RH-{YYYY}-{NNN}
+  from: squad-research
+  from_agent: [agent name (persona)]
+  to: [squad destino]
+  to_agent: [agent destino]
+  date: [YYYY-MM-DD]
+  type: [personas | market-data | competitive-intel | trends | report]
+  deliverables:
+    - name: [nome do deliverable]
+      format: [md | yaml | csv | pdf]
+      path: [caminho do arquivo]
+  summary: [1-2 frases do que esta sendo entregue]
+  confidence: [HIGH | MEDIUM | LOW]
+  freshness: [data da pesquisa mais recente]
+  next_refresh: [quando deve ser atualizado]
+```
+
+## Quality Standards para Deliverables Cross-Squad
+1. Todo deliverable deve ter confidence level
+2. Todo dado deve ter fonte e data
+3. Insights devem seguir FINDING + IMPLICATION + RECOMMENDATION
+4. Formato deve ser o esperado pelo squad destino
+5. Freshness declarada (quando os dados foram coletados)
+
+## Feedback Loop
+- Squads receptores podem solicitar revisoes
+- Formato: "Request clarification on [item] because [reason]"
+- SLA para revisao: 48h
+- Se feedback muda conclusao → notificar TODOS os squads que receberam o deliverable original
+
+---
+
+*Knowledge base da squad-research*

package/squads/squad-research/knowledge-base/data-visualization-principles.md

@@ -0,0 +1,76 @@
+# Data Visualization Principles
+
+## Principios de Tufte
+
+### Data-Ink Ratio
+- **Regra:** Maximizar a proporcao de tinta usada para dados vs tinta total
+- **Pratica:** Remover gridlines desnecessarias, borders, backgrounds, 3D effects
+- **Teste:** Se remover um elemento e o dado continua claro → remover
+
+### Chartjunk
+- **O que evitar:** Sombras, gradientes, 3D, texturas decorativas, clip art
+- **Resultado:** Graficos limpos onde o DADO e o protagonista
+
+### Small Multiples
+- **Quando usar:** Comparar a mesma metrica em muitas categorias
+- **Como:** Repetir o mesmo grafico em grid, variando apenas os dados
+- **Vantagem:** Comparacao visual rapida
+
+### Lie Factor
+- **Formula:** (Tamanho do efeito visual) / (Tamanho do efeito nos dados)
+- **Ideal:** Lie factor = 1.0 (representacao proporcional)
+- **Problemas comuns:** Y-axis nao comecando em 0, area vs raio em bubbles
+
+## Chart Selection Matrix
+
+| Objetivo | 1 Variavel | 2 Variaveis | 3+ Variaveis |
+|----------|:----------:|:-----------:|:------------:|
+| **Comparar** | Bar (horizontal) | Grouped bar | Small multiples |
+| **Tendencia** | Sparkline | Line | Multi-line (max 4) |
+| **Composicao** | Pie (max 5 fatias) | Stacked bar | Treemap |
+| **Relacao** | — | Scatter | Bubble |
+| **Distribuicao** | Histogram | Box plot | Violin |
+| **Fluxo** | — | Sankey | Network |
+| **Geo** | Choropleth | — | Multi-layer map |
+
+## Paletas de Cores
+
+### Sequential (dados ordenados)
+- Claro → Escuro (mesma hue, variando luminosidade)
+- Uso: valores crescentes, concentracao, intensidade
+
+### Diverging (dados com centro)
+- Cor A → Neutro → Cor B (ex: azul → branco → vermelho)
+- Uso: desvio da media, positivo/negativo, acima/abaixo target
+
+### Categorical (sem ordem)
+- Cores distintas e balanceadas
+- Max 7 categorias (alem disso, agrupar em "Outros")
+- Uso: segmentos, tipos, grupos
+
+### Accessibility
+- Testar com simulador de daltonismo
+- Nao depender APENAS de cor — usar forma, pattern, label
+- Contraste minimo 4.5:1 para texto
+
+## Erros Comuns
+
+| Erro | Problema | Solucao |
+|------|----------|---------|
+| Y-axis truncado | Exagera diferenças | Comecar em 0 ou indicar claramente |
+| Pie chart com 10+ fatias | Ilegivel | Usar bar chart |
+| 3D charts | Distorce proporcoes | Sempre 2D |
+| Dual Y-axis | Confunde e pode ser manipulativo | 2 charts separados |
+| Rainbow palette | Nao tem ordem logica | Usar sequential/diverging |
+| Sem titulo ou fonte | Contexto perdido | Sempre incluir |
+
+## Dashboard Design Principles
+1. **Information hierarchy:** Mais importante no topo-esquerda
+2. **Consistent layout:** Grid uniforme, alinhamento
+3. **Filter first:** Permitir drill-down, nao sobrecarregar
+4. **One KPI per card:** Nao misturar metricas em um visual
+5. **Context:** Sempre mostrar benchmark, target, ou periodo anterior
+
+---
+
+*Knowledge base da squad-research*

package/squads/squad-research/knowledge-base/hybrid-retrieval-patterns.md

@@ -0,0 +1,144 @@
+# Hybrid Retrieval Patterns
+
+> Extraído e sintetizado de MS-009 Agentic Second Brain (2026) — estado da arte em retrieval para sistemas RAG e Second Brains.
+
+## Princípio Central
+
+**Hybrid search (BM25 + embeddings + graph traversal) é o padrão de produção em 2026.** Sistemas com retrieval monomodal (apenas semântico OU apenas keyword) são considerados subótimos. A combinação reduz erros em 35-60% versus retrieval semântico puro.
+
+## Por Que BM25 Ainda Importa
+
+Apesar dos avanços em embeddings, BM25 permanece imbatível para:
+- Códigos de produto exatos e SKUs
+- Terminologia legal e regulatória específica
+- Acrônimos únicos e jargões técnicos
+- Nomes próprios e marcas
+
+Para a maioria das aplicações RAG reais, full-text search fornece precisão que vector search não alcança confiavelmente.
+
+## A Stack Híbrida de Produção
+
+```
+[Query do Usuário]
+  |
+  +-- BM25 (keyword search)        --> Top-K resultados
+  |
+  +-- Dense Embeddings (semantic)  --> Top-K resultados
+  |
+  +-- Knowledge Graph (structured) --> Entidades + Relações
+  |
+  --> Reciprocal Rank Fusion (RRF) --> Merged & Ranked
+  |
+  --> Cross-Encoder Reranking      --> Final Top-N
+  |
+  --> LLM Generation com Context
+```
+
+## Reciprocal Rank Fusion (RRF)
+
+**A fórmula que une os mundos:** Se um documento aparece no Top-5 de AMBOS keyword e semantic search, recebe boost massivo — garantindo que documentos relevantes por ambos critérios sejam priorizados.
+
+```python
+# Fórmula RRF
+rrf_score = sum(1 / (k + rank_i) for i in retrieval_systems)
+# k = constante (tipicamente 60)
+# rank_i = posição do documento no sistema i
+```
+
+**Por que funciona:** Documentos consistentemente relevantes em múltiplos sistemas recebem scores cumulativos, enquanto falsos positivos (relevantes em apenas 1 sistema) ficam abaixo.
+
+## Camadas de Retrieval
+
+### Camada 1: BM25 (Full-Text)
+- **Ferramenta:** Elasticsearch, OpenSearch, Typesense, Meilisearch
+- **Força:** Termos exatos, queries específicas
+- **Configurar:** Field weighting (título > corpo), stemming para pt-BR
+
+### Camada 2: Dense Embeddings (Semantic)
+- **Modelos recomendados 2026:**
+  - `text-embedding-3-large` (OpenAI) — melhor qualidade geral
+  - `voyage-3` (Voyage AI) — melhor custo/benefício para pt-BR
+  - `bge-m3` (open-source) — multilingual, self-hosted
+- **Vector DB:** pgvector (início) → Weaviate/Pinecone (produção)
+- **Força:** Sinonímia, variações linguísticas, contexto semântico
+
+### Camada 3: Knowledge Graph (Structural)
+- **Quando usar:** Queries sobre relações, entidades conectadas, raciocínio multi-hop
+- **Força:** "Quais empresas competem com X no mercado Y?"
+- **Implementação:** Graphiti para temporal, Neo4j para estático
+
+### Camada 4: Cross-Encoder Reranking
+- **O que é:** Segundo estágio de ranking com modelo mais pesado
+- **Modelos:** `cross-encoder/ms-marco-MiniLM-L-6-v2` (open-source)
+- **Trade-off:** +latência vs +precisão (usar apenas no Top-20, não no full corpus)
+
+## Agentic RAG (Estado da Arte 2026)
+
+Evolução do RAG passivo para RAG ativo — agente que planeja, recupera, raciocina e itera:
+
+```
+[Query]
+  --> Plan: Quais sub-queries são necessárias?
+  --> Retrieve: Executar retrieval para cada sub-query
+  --> Reason: Síntese dos resultados
+  --> Critique: Os resultados respondem a query?
+  --> Refine: Se não, reformular e repetir (max 3 ciclos)
+  --> Generate: Resposta final com fontes
+```
+
+**Referência acadêmica:** arXiv 2501.09136 — survey formal sobre Agentic RAG.
+
+## Tiers de Armazenamento para Retrieval
+
+| Tier | Acesso | Armazenamento | Latência | Exemplo |
+|------|--------|---------------|----------|---------|
+| **HOT** | Context window | In-memory (tokens) | <1ms | Tarefa atual, últimas mensagens |
+| **WARM** | Recuperável | Vector DB + Cache | <300ms | Notas recentes, entidades do projeto |
+| **COLD** | Sob demanda | Filesystem + Archive | >1s | Notas antigas, projetos concluídos |
+
+**Princípio do ContextForge:** Uma nota se torna HOT não apenas por acesso recente, mas por relevância semântica à tarefa atual — mesmo armazenada semanas atrás.
+
+## Token Budget para Contexto RAG
+
+```
+TOTAL WINDOW: 200,000 tokens (Claude exemplo)
+  |- System Prompt:      ~2,000 tokens (1%)
+  |- Agent Persona:      ~1,500 tokens (0.75%)
+  |- Memory Context:    ~50,000 tokens (25%)  ← GERENCIADO via retrieval
+  |    |- HOT (current):  ~20,000
+  |    |- WARM (retrieved): ~30,000
+  |- Tool Results:      ~50,000 tokens (25%)  ← DINÂMICO
+  |- Response Budget:   ~76,500 tokens (38%)  ← RESERVADO
+```
+
+## Ferramentas de Memória Híbrida (2026)
+
+| Ferramenta | Abordagem | Destaque |
+|-----------|-----------|----------|
+| **Mem0** | Graph DB + vector | 26% accuracy gain vs OpenAI Memory, 91% menor latência, 90% menos tokens. $24M Series A (Out 2025) |
+| **Zep/Graphiti** | Temporal graph | 94.8% accuracy DMR; retrieval P95 300ms sem LLM calls |
+| **Cognee** | Graph-vector hybrid | $7.5M seed (Fev 2026); 30+ conectores, 1M+ pipeline runs |
+| **Letta (MemGPT)** | Virtual context (OS-inspired) | Memory blocks read/write; Conversations API cross-session |
+| **ContextForge** | Three-tier HOT/WARM/COLD | 10x compression ratio; auto-promoção/remoção entre tiers |
+
+## Implementação Passo a Passo
+
+1. **Dual Index:** BM25 index (Elasticsearch/Typesense) + vector index (pgvector) para cada documento
+2. **Graph Layer:** Extrair entidades/relações durante ingestão com LLM
+3. **Hybrid Fusion:** Implementar RRF com k=60 como ponto de partida
+4. **Reranking:** Adicionar cross-encoder apenas para Top-20 resultados do RRF
+5. **Context Packing:** Selecionar e ordenar chunks para maximizar utilidade no context window
+6. **Feedback Loop:** Rastrear quais resultados o agente realmente usa para melhorar rankings
+
+## Riscos
+
+| Risco | Sinal | Mitigação |
+|-------|-------|-----------|
+| Semantic drift | Embeddings retornando resultados off-topic | Reembarcar modelos periodicamente, monitorar retrieval quality |
+| Index staleness | Respostas referenciando informação desatualizada | Pipeline de re-indexação automática ao update de nota |
+| Over-retrieval | Contexto poluído com muito material | Limit Top-N, threshold de relevância mínimo |
+| Single-modality bias | Perder resultados keyword-específicos | Sempre manter BM25 ativo ao lado de embeddings |
+
+---
+
+*Knowledge base da squad-research | Fonte: MS-009 Agentic Second Brain*