## Audit Report: Read Pipeline — Graph Signal Fix + Doc Gaps

**Verdict: PASS**

**PRD:** `.vibeflow/prds/read-pipeline-gaps.md`
**Spec:** Nenhuma spec formal gerada (PRD usado como referência direta)
**Data:** 2026-03-20
**Versão:** 0.6.4

---

### Testes

```
338 passed, 8 warnings in 0.22s
```

CI completo (ruff + mypy + pytest): **PASS**

---

### DoD Checklist (extraído dos Success Criteria do PRD)

- [x] **Graph signal retorna > 0 facts quando existem relations relevantes** — O system prompt em `retrieval_agent.py:153-195` agora inclui regra mandatória "ALWAYS populate entities", campo `entities` em todos os 3 exemplos JSON (similarity, general, greeting), e seção "ENTITY EXTRACTION (MANDATORY)". O parser em `_parse_plan()` (linhas 272-280) já extraía `data.get("entities")` — agora o LLM sabe que deve retorná-los. Testes `test_llm_returns_entities_for_entity_query` e `test_llm_returns_multiple_entities` verificam parsing. O gate `if plan.entities:` no pipeline continua correto.

- [x] **Docs explicam interação reranker × score_weights** — Callout `!!! warning "Reranker overrides score_weights"` adicionado em `docs/en/concepts/read-pipeline.md:208-209` e `docs/pt-BR/concepts/read-pipeline.md:208-209`. Explica que com `enable_reranker=True`, scores são discretos do LLM, não da fórmula ponderada.

- [x] **Docs esclarecem que context_max_tokens é budget** — Callout `!!! note "context_max_tokens is a proportional budget"` adicionado em `docs/en/concepts/read-pipeline.md:221-222` e equivalente PT-BR. Inclui exemplo concreto (100 tokens → ~240 tokens).

- [x] **Docs mostram fórmula completa com 6 sinais** — Seção "Complete Score Breakdown" / "Breakdown Completo do Score" substituiu a tabela parcial. Tabela com 6 sinais (semantic, keyword, recency, importance, confidence, reranker) com range e descrição detalhada. Tabela adicional com pattern e graph. Explicação de importance (dynamic importance job, começa em 0.5) e confidence (LLM extraction, tipicamente 0.95, decay temporal) incluídas inline.

### Scope v0 Checklist

- [x] **1. Atualizar system prompt** — `src/arandu/read/retrieval_agent.py` modificado: +1 regra mandatória, +3 exemplos JSON com entities, +1 seção ENTITY EXTRACTION.
- [x] **2. Teste unitário** — 2 novos testes em `tests/test_retrieval_agent.py`: single entity e multiple entities.
- [x] **3. Doc updates EN + PT-BR** — 3 callouts adicionados em cada idioma (reranker, context_max_tokens, score formula).
- [x] **4. Explicar importance e confidence** — Descrições detalhadas na tabela do score breakdown (EN + PT-BR).

---

### Anti-scope Compliance

- [x] `graph_retrieval.py` — Não modificado ✓
- [x] `read/pipeline.py` — Não modificado ✓
- [x] `config.py` — Não modificado ✓
- [x] Nenhuma mudança no reranker ✓
- [x] Nenhuma implementação de confidence variável ✓
- [x] Nenhuma implementação de importance no write ✓

---

### Pattern Compliance

- [x] **LLM Interaction** — Prompt continua como string inline em `_build_system_prompt()`. Formato JSON mandatório nos exemplos. Nenhum `response_format` alterado (era `max_tokens` sem `response_format`, correto para retrieval agent que usa `temperature=0`). Fail-safe mantido (fallback `multi_signal` em caso de parse error).

- [x] **Testing** — Testes usam `FakeLLMProvider` com canned JSON, `_mock_session_with_schema()` para mock do DB, `run_async()` wrapper, cache clear antes de cada teste. Seguem convenção de `class TestPlanRetrieval` com methods descritivos.

- [x] **Error Handling** — Nenhuma exceção nova introduzida. Fail-safe pattern preservado: entities vazios → graph não roda (não é erro).

---

### Convention Violations

Nenhuma.

---

### Arquivos Modificados

| Arquivo | Mudança |
|---------|---------|
| `src/arandu/read/retrieval_agent.py` | +13 linhas no system prompt |
| `tests/test_retrieval_agent.py` | +61 linhas (2 novos testes) |
| `docs/en/concepts/read-pipeline.md` | +33 linhas (3 callouts + score table) |
| `docs/pt-BR/concepts/read-pipeline.md` | +33 linhas (mesmos callouts em PT-BR) |
| `pyproject.toml` | 0.6.3 → 0.6.4 |
| `CLAUDE.md` | Não relacionado (pré-existente) |

**Total:** 6 arquivos, 184 inserções, 22 deleções. Dentro do budget sugerido (≤ 6 files).

---

### Nota sobre Spec Formal

Este trabalho foi implementado direto do PRD sem uma spec técnica intermediária (`/vibeflow:gen-spec`). O escopo era pequeno (1 arquivo de código + docs), os critérios de sucesso eram claros e binários, e o anti-scope bem definido. A spec formal teria adicionado overhead sem valor proporcional neste caso.
