# SPEC: [Feature Name]

> **Propósito deste documento:** Definir O QUE a feature faz, POR QUE ela existe, e quais RESTRIÇÕES o agente deve respeitar. O COMO técnico (lib, arquitetura interna) o agente descobre — desde que justifique cada decisão contra os três eixos: **custo mínimo, máxima eficiência/velocidade, máxima qualidade.**
>
> Este documento é o contrato. O agente implementa contra ele. Se não está no contrato, o agente pergunta — não inventa.

---

## Meta
- **Feature ID:** `[EPIC]-[NN]` (ex: `RAG-05`, `COST-04`)
- **Status:** Draft → In Review → Approved → Implementing → Done
- **Author:** Murilo
- **Created:** YYYY-MM-DD
- **Depends on:** [IDs de specs que precisam estar DONE antes desta; "none" se standalone]

---

## 1. WHY — Problema e Objetivo

### 1.1 Current Behavior (o que acontece hoje)
[Descreva o comportamento atual do sistema. Seja específico — use métricas, logs, exemplos concretos.]

Exemplo:
- RRF retorna scores 0.0154-0.0164 indistinguíveis para todos os 50 chunks
- Chunk de cookie consent: score 0.0154
- Chunk de preço de produto: score 0.0164
- Resultado: LLM recebe lixo e conteúdo útil com mesma prioridade

### 1.2 Pain (por que precisa mudar)
[Qual o impacto real no usuário/negócio? Use dados se possível.]

Exemplo:
- Ale respondeu "não encontrei informações sobre esse produto" quando o chunk com preço existia mas estava rankeado em 47º lugar
- Usuários de e-commerce recebem respostas genéricas sobre garantia quando perguntam preços específicos

### 1.3 Goal (o que a feature deve entregar)
[Uma frase. Concreta. Mensurável.]

Exemplo:
- Re-ranquear os top-50 chunks do hybrid search usando similaridade semântica real (cross-encoder), garantindo que chunks relevantes tenham score >0.7 e chunks irrelevantes <0.3

---

## 2. WHAT — O Que a Feature Deve Fazer

### 2.1 Functional Contract

**Entrada:**
- O que chega (tipo, estrutura, exemplo)
- De onde vem (qual módulo/função chama)

**Processamento:**
- O que deve acontecer (transformação, enriquecimento, decisão)
- Em qual ponto do pipeline (antes/depois do quê)

**Saída:**
- O que sai (tipo, estrutura, campos obrigatórios)
- Pra onde vai (qual módulo/função recebe)

**Exemplo concreto de dados** (obrigatório):

```json
// INPUT
{
  "query": "Quanto custa a Skillet Redonda Signature?",
  "chunks": [
    {"chunk_id": "c_001", "text": "...preço R$ 1.449...", "source_id": 29, "rrf_score": 0.0161},
    {"chunk_id": "c_047", "text": "...aceitar cookies...", "source_id": 12, "rrf_score": 0.0159}
  ]
}

// OUTPUT
{
  "query": "Quanto custa a Skillet Redonda Signature?",
  "results": [
    {"chunk_id": "c_001", "text": "...preço R$ 1.449...", "score": 0.92, "source_id": 29},
    {"chunk_id": "c_047", "text": "...aceitar cookies...", "score": 0.08, "source_id": 12}
  ],
  "metadata": {
    "reranker_model": "bge-reranker-v2-m3",
    "reranker_latency_ms": 180,
    "low_confidence": false
  }
}
```

### 2.2 Success Criteria (métricas de satisfação)

| Critério | Métrica | Threshold | Medição |
|----------|---------|-----------|---------|
| Relevância | Chunk correto no top-1 | ≥ 80% dos casos | Holdout scenarios (5 runs) |
| Discriminação | Score(relevante) / Score(irrelevante) | > 2.0 | Holdout scenarios |
| Cobertura | Top-3 contém diversidade de fontes | ≥ 2 fontes distintas | Holdout scenarios |
| Robustez | Sistema não crasha com reranker offline | Fallback graceful | Scenario 5 (failure) |

---

## 3. CONSTRAINTS — A Jaula do Agente

> **Regra de ouro:** O agente TEM liberdade técnica DENTRO destas constraints. Toda decisão que o agente tomar deve ser justificada contra os três eixos: custo, velocidade, qualidade. Se uma decisão sacrifica um eixo, o trade-off deve ser explícito e justificado no PLAN.md.

### 3.1 Cost (custo deve ser o mínimo possível)

| Restrição | Valor | Justificativa |
|-----------|-------|---------------|
| Custo incremental por 1000 queries | < $0.50 | Embedding já é free (bge-m3); não queremos triplicar custo |
| Modelo preferido | Self-hosted / Open-source gratuito | Sem custo recorrente de API |
| API paga tolerada? | Só se self-hosted for inviável tecnicamente | Justificar no PLAN.md com benchmark comparativo |
| Hardware extra necessário? | Máx 1.5GB VRAM | VPS já tem outros serviços; não podemos consumir tudo |

### 3.2 Speed (deve ser o mais rápido possível)

| Restrição | Valor | Justificativa |
|-----------|-------|---------------|
| Latência p95 total da feature | < 500ms | Não pode degradar perceptivelmente o tempo de resposta |
| Latência p99 | < 1000ms | Pico aceitável |
| Timeout | 2000ms | Após isso, fallback |
| Processamento em batch | 50 chunks em paralelo | Não processar 1 por 1 |

### 3.3 Quality (deve ser a máxima possível)

| Restrição | Valor | Justificativa |
|-----------|-------|---------------|
| Modelo deve ser multilingue | pt-BR ≥ en | Usuários brasileiros |
| Score deve discriminar relevante de irrelevante | Ratio > 2.0 | RRF atual tem ratio ~1.0 (não discrimina) |
| Data lineage preservado | chunk_id + source_id intactos | Debug e auditoria |
| Observabilidade | Logar modelo, latência, low_confidence flag | Essencial pra diagnosticar problemas |

### 3.4 Architecture (constraints de integração)

| Restrição | Valor |
|-----------|-------|
| Onde no pipeline? | Entre `hybrid_search` e `call_llm` no LangGraph |
| Interface | Deve implementar a mesma interface de `retrieve()` atual |
| Banco de dados | Não adicionar novo banco (usar Postgres existente se necessário) |
| Container | agent-worker existente (não criar novo serviço) |
| Fallback | Se falhar: retornar top-5 do RRF atual (sem crash) |

---

## 4. WHAT NOT — O Que a Feature NÃO Deve Fazer

> Tão importante quanto definir o escopo é definir o que está FORA do escopo.
> Isso evita que o agente implemente coisas desnecessárias.

- ❌ Não substituir o hybrid search (continua igual)
- ❌ Não alterar o modelo de embedding (continua bge-m3)
- ❌ Não adicionar banco de dados novo
- ❌ Não alterar a estrutura do `agent_logs` (adicionar campos no `metadata` JSON, não novas colunas)
- ❌ Não implementar cache de reranking (fora do escopo — spec separada)
- ❌ Não criar endpoint HTTP novo (feature é interna ao pipeline LangGraph)

---

## 5. ACCEPTANCE SCENARIOS (Holdout — AGENTE NÃO VÊ)

> **CRÍTICO:** Estes cenários são armazenados em `scenarios/scenarios.yaml`. O agente NUNCA lê este arquivo durante a fase IMPLEMENT. A validação (fase 5) roda contra cenários que o agente nunca viu.

### Scenario 1: Happy Path — Produto com preço
- **Query:** "Quanto custa a Skillet Redonda Signature?"
- **Context:** 50 chunks — 3 com preço real, 47 com navegação/cookies
- **Expected:** Chunk com preço no top-1, score > 0.7
- **Satisfaction:** `score(correto) / score(segundo) > 2.0` em ≥ 4 de 5 runs

### Scenario 2: Edge Case — Conteúdo de cuidado
- **Query:** "Como limpar panela de ferro fundido esmaltada?"
- **Context:** 50 chunks — 5 de cuidados, 15 produtos, 30 lixo
- **Expected:** Top-3 contém ≥ 2 chunks de cuidados
- **Satisfaction:** `count(care_chunks_in_top3) >= 2` em ≥ 4 de 5 runs

### Scenario 3: Diversity — Terminologia específica
- **Query:** "Qual a diferença entre ferro fundido e antiaderente?"
- **Context:** 50 chunks — 10 com comparações, 40 produtos
- **Expected:** Top-3 menciona ambos os materiais
- **Satisfaction:** `n_distinct_materials_in_top3 >= 2` em ≥ 4 de 5 runs

### Scenario 4: Garbage Filter — Chunks de lixo
- **Query:** "Qual a garantia dos produtos?"
- **Context:** 49 chunks de cookie/promoção + 1 chunk de garantia real
- **Expected:** Chunk de garantia no top-3; zero cookies no top-5
- **Satisfaction:** `garantia_rank <= 3 AND cookies_in_top5 == 0` em ≥ 4 de 5 runs

### Scenario 5: Failure — Reranker offline
- **Query:** "Qual o prazo de entrega?"
- **Simulate:** Reranker timeout/erro
- **Expected:** Sistema retorna top-5 do RRF atual (fallback), não crasha
- **Satisfaction:** `response.status == "ok" AND response.metadata.fallback == true`

---

## 6. OBSERVABILITY

> O que deve ser logado para debugging e auditoria. Campos obrigatórios.

```
agent_logs.debug: {
  "reranker": {
    "model": "bge-reranker-v2-m3",
    "latency_ms": 180,
    "chunks_in": 50,
    "chunks_out": 5,
    "top_score": 0.92,
    "bottom_score": 0.03,
    "low_confidence": false,
    "fallback": false
  }
}
```

---

## 7. ROLLBACK

> Como desfazer se a feature causar problemas em produção.

- **Feature flag:** Via `rag_enable_reranker` no `agent_model_routing` (já existe tabela)
- **Desabilitar:** `UPDATE agent_model_routing SET rag_enable_reranker = false WHERE agent_name = '...'`
- **Fallback automático:** Se reranker falhar → RRF top-5 (comportamento atual). Sistema nunca fica pior.
- **Rollout:** Sandbox → 1 agente prod (Ale) → todos agentes

---

## 8. AFFECTED FILES

> Preenchido pelo agente na fase PLAN. Lista de arquivos a criar/modificar/deletar com paths completos.

```
[path] — [CREATE|MODIFY|DELETE] — [motivo]
```

---

## 9. REFERENCES

- [Link para documentação externa, papers, issues]
- [Link para ADR em docs/adr/]
- [Link para spec relacionada]
- [Link para modelo no HuggingFace/GitHub]

---

## 10. VALIDATION RESULTS

> Preenchido APÓS implementação (fase VALIDATE).

### Test Results
- [ ] Unit tests: ___ passed, ___ failed
- [ ] Integration tests: ___ passed, ___ failed
- [ ] Holdout scenarios: ___/5 satisfied
- [ ] Browser-use validation: [url]
- [ ] Latência p95 medida: ___ms
- [ ] Custo verificado: $___ / 1000 queries

### Agent Justifications
> O agente preenche: para cada decisão técnica, qual foi o trade-off e por que essa escolha.

| Decisão | Alternativas consideradas | Trade-off | Por que esta |
|---------|--------------------------|-----------|--------------|
| Modelo X vs Y | Y (mais rápido), Z (mais barato) | X é 50ms mais lento que Y mas 2x mais preciso | Qualidade > 50ms |
| ... | ... | ... | ... |

### Known Limitations
- [Limitação documentada — toda feature tem limitações]

---

## 11. DEEP ANALYSIS — Pesquisa Pré-Implementação

> **Formato:** Esta seção segue o mesmo padrão do Paper Analyst (research.html).
> **Propósito:** Análise profunda do problema contra o codebase real ANTES de implementar.
> **Preenchimento:** O agente faz pesquisa (codebase docs, papers, referências) e preenche.
> **Renderização:** O kanban.html renderiza esta seção como HTML estruturado no modal.

### 11.1 Scores

| Dimensão | Score (1-10) | Justificativa |
|----------|-------------|---------------|
| **Qualidade** | [1-10] | [Ganho de qualidade esperado] |
| **Performance** | [1-10] | [Impacto em latência/throughput] |
| **Segurança** | [1-10] | [Redução de vulnerabilidades] |
| **Dificuldade** | [1-10] | [Complexidade técnica] |
| **Custo** | baixo / médio / alto | [Estimativa de esforço] |
| **Urgência** | agora / breve / depois / nunca | [Por que essa prioridade] |

### 11.2 Descoberta

> **O que é o problema e por que ele existe.**

[Análise do problema raiz. Use dados de logs, métricas, exemplos concretos de falha.
Cite arquivos específicos do codebase. Explique o impacto no usuário final.]

### 11.3 Análise do Pipeline

#### Fluxo Atual

> **Como o sistema funciona HOJE no caminho afetado.**

[Descreva o fluxo atual com paths exatos de arquivos e funções.
Ex: "O `call_llm_node` em `internal/runner/nodes.py` invoca OpenRouter e retorna
a resposta sem avaliação de qualidade."]

#### Fluxo Proposto

> **Como o sistema DEVE funcionar após a feature.**

[Descreva o novo fluxo. Use paths específicos de arquivos que serão modificados.
Mostre a diferença em relação ao fluxo atual. Inclua diagrama textual se relevante.]

#### Componentes Afetados

> **Quais subsistemas são impactados e como.**

[Liste cada subsistema (RAG, LangGraph, n8n, Chatwoot, Frontend, NATS, etc.)
e explique exatamente o que muda em cada um.]

### 11.4 Ganho de Qualidade

#### Antes

> **Qualidade atual (com evidência).**

[Descreva o estado atual com métricas reais quando possível.
Ex: "Taxa de tool calls incorretas ~15% baseado em logs manuais."]

#### Depois

> **Qualidade esperada após a feature.**

[Descreva a melhoria esperada. Seja específico sobre o que muda na experiência
do usuário ou na confiabilidade do sistema.]

#### Métricas

> **Como medir o ganho de qualidade.**

| Métrica | Baseline | Target | Medição |
|---------|----------|--------|---------|
| [Métrica 1] | [valor atual] | [valor esperado] | [como medir] |
| [Métrica 2] | [valor atual] | [valor esperado] | [como medir] |

### 11.5 Análise de Custo

#### Custo Atual

> **Quanto custa o pipeline afetado hoje.**

[Detalhe custos de API, infra, e custos ocultos (erros, retrabalho).]

#### Custo de Implementação

> **Quanto custa desenvolver esta feature.**

[Estime horas de engenharia, custo de API para testes, complexidade.]

#### Custo Operacional

> **Quanto custa manter esta feature em produção.**

[Custo recorrente mensal: tokens, infra, storage, mão de obra operacional.]

### 11.6 Sugestão de Código

#### Arquivo Alvo

> **Qual(is) arquivo(s) principal(is) serão modificados.**

[Path exato + breve descrição do que o arquivo faz hoje.]

#### Mudança Proposta

> **Pseudocódigo ou descrição detalhada da mudança.**

[Descreva a mudança em detalhes: novas funções, modificações em funções
existentes, novas tabelas, mudanças de schema. Use blocos de código se relevante.]

### 11.7 Evidência

> **Por que acreditamos que isso funciona.**

[Referências: papers, posts, issues similares resolvidos, dados de produção,
experiência de outros times. Cite URLs e explique a relevância para este caso.]

### 11.8 Riscos

> **O que pode dar errado e como mitigar.**

| Risco | Probabilidade | Impacto | Mitigação |
|-------|--------------|---------|-----------|
| [Risco 1] | Alta / Média / Baixa | Alto / Médio / Baixo | [Como mitigar] |
| [Risco 2] | Alta / Média / Baixa | Alto / Médio / Baixo | [Como mitigar] |

---

## 12. POST-MORTEM

> Preenchido após 1+ semana em produção. O que aprendemos?

- [O que funcionou bem]
- [O que faríamos diferente]
- [Métricas reais vs estimadas]