# PRD: Plano de Testes do Personal Genius

> Generated via /vibeflow:discover on 2026-04-10

## Problem

O Arandu SDK passou por 6 releases (v0.11.8 a v0.13.1) em poucos dias,
com mudancas estruturais significativas: FactQuery builder, alias
resolution, mirror facts reconcile, planner deterministico. Cada fix
foi validado isoladamente pelo Personal Genius, mas nao existe uma
bateria de testes sistematica que cubra o ciclo completo de uso real
do assistente pessoal.

Sem isso, nao sabemos:
- Se o produto funciona end-to-end no caso de uso real (conversa
  natural em portugues, multiplas entidades, relacoes, temporal)
- Onde estao os gaps de qualidade que vao aparecer quando rodarmos
  LoCoMo contra concorrentes (Mem0, Zep, Letta)
- Se regressoes foram introduzidas nas refatoracoes recentes

O Personal Genius e o dogfooder perfeito: ele usa o Arandu em conversa
real com o Pedro, tem acesso ao SDK via MCP server, e ja demonstrou
capacidade de reportar bugs com reproducao detalhada.

## Target Audience

**Executor dos testes:** Personal Genius (agente assistente pessoal do
Pedro). Ele recebe cada etapa do plano, executa, e reporta resultados
na thread do Obsidian vault.

**Consumer dos resultados:** Pedro (dev) e Claude Code (dev). Os
resultados alimentam decisoes sobre proximos fixes e priorizacao
antes do benchmark LoCoMo.

## Proposed Solution

Um plano de testes estruturado em etapas sequenciais, cada uma cobrindo
um aspecto da API do Arandu no contexto de uso real do Personal Genius.
Cada etapa e um "test suite" com:

- Cenarios concretos com input exato
- Output esperado
- Criterio de pass/fail binario
- Espaco pra Personal Genius reportar resultado e observacoes

As etapas sao mandadas uma por vez na thread do Obsidian. O Personal
Genius executa, reporta, e so entao recebe a proxima.

### Etapas propostas

**Etapa 1 — Write: Extracao e Entity Resolution (fundacao)**
Testa se o write pipeline extrai fatos corretamente de conversas
naturais em portugues. Sem write correto, nada mais funciona.

Cenarios:
1. Conversa simples com fatos biograficos ("moro em SP, trabalho na Stone")
2. Conversa com multiplas entidades e relacoes ("minha esposa Ana trabalha na Acme")
3. Conversa com speaker provenance (Pedro fala X, Personal Genius responde Y)
4. Update de fato existente ("me mudei de SP pra Curitiba")
5. Retratacao ("na verdade nao trabalho mais na Stone")
6. Conversa em portugues coloquial com girias/abreviacoes
7. Conversa mista pt-BR/en ("fiz deploy do feature branch ontem")

Criterios: fatos extraidos corretamente, entidades resolvidas, relacoes
criadas, speaker correto, confidence razoavel.

**Etapa 2 — Retrieve: Cenarios de busca (core do produto)**
Testa se retrieve retorna fatos relevantes pra queries reais.

Cenarios:
1. Query direta com nome ("onde o Pedro mora?")
2. Query sem nome ("onde eu trabalho?" — self-reference)
3. Query sobre relacao ("quem e a esposa do Pedro?")
4. Query de agregacao ("quem sao meus amigos?")
5. Query broad ("me conta tudo sobre mim")
6. Query temporal ("onde eu morava antes?")
7. Query com entity_keys filter
8. Query sem resultados (topico nunca mencionado)
9. Query cross-language ("where does Pedro work?" sobre fatos em pt-BR)
10. Query com reranker ON vs OFF (comparar qualidade)

Criterios: fatos corretos retornados, ordem de relevancia faz sentido,
context string e util pra LLM, latencia razoavel.

**Etapa 3 — CRUD: Operacoes de gestao (DX)**
Testa as operacoes de leitura e gestao de memoria.

Cenarios:
1. get() por fact_id
2. get_all() com paginacao
3. get_all() com entity_keys filter (alias, canonical, slug)
4. entities() — lista todas entidades
5. delete() de um fato especifico
6. delete_all() de um agente
7. Warnings quando entity_key nao existe

Criterios: operacoes funcionam, paginacao estavel, warnings claros.

**Etapa 4 — Ciclo completo: Conversa real (integracao)**
Simula um dia real de uso do Personal Genius com o Pedro. Sequencia de
writes e retrieves que exercitam o ciclo completo.

Cenarios:
1. Pedro conta sobre o dia de trabalho (write) → Personal Genius
   pergunta detalhes (retrieve pra contexto) → Pedro responde (write)
2. Pedro menciona pessoa nova → retrieve posterior encontra
3. Pedro corrige informacao anterior → retrieve retorna versao atualizada
4. Pedro pergunta sobre algo de semanas atras → retrieve encontra
5. Conversa longa (10+ turnos) com multiplos topicos → retrieve
   consegue separar e encontrar cada topico

Criterios: o Personal Genius consegue usar o Arandu como memoria
funcional numa conversa real, sem momentos de "esqueceu" ou "confundiu".

**Etapa 5 — Stress e edge cases (robustez)**
Testa limites e comportamentos de borda.

Cenarios:
1. Write com mensagem muito longa (2000+ chars)
2. Write com mensagem vazia
3. Retrieve com query vazia
4. Write com emojis e caracteres especiais
5. Write de informacao contraditoria rapida ("moro em SP" + "moro em RJ" no mesmo minuto)
6. Retrieve com muitos fatos armazenados (pos-etapas anteriores)

Criterios: sem crashes, degradacao graceful, resultados razoaveis.

## Success Criteria

1. **Todas as 5 etapas executadas** com resultado reportado pelo
   Personal Genius
2. **>80% dos cenarios PASS** (criterio global)
3. **Zero crashes/erros nao tratados** em qualquer cenario
4. **Lista clara de gaps** identificados (cenarios que falharam ou
   degradaram) pra priorizar fixes
5. **Baseline de qualidade documentada** antes de rodar LoCoMo

## Scope v0

1. Documento de plano de testes no Obsidian vault
2. 5 etapas com ~35 cenarios totais
3. Cada etapa mandada como mensagem na thread pra Personal Genius
4. Resultados reportados na mesma thread
5. Consolidacao de gaps apos todas as etapas

## Anti-scope

1. **Benchmark LoCoMo** — vem depois, com base nos gaps identificados
2. **Comparacao com concorrentes** — vem depois do LoCoMo
3. **Testes automatizados** — estes sao testes manuais de dogfooding.
   Os unit/integration tests do CI sao outra coisa
4. **Fix de bugs encontrados** — o plano identifica gaps, fixes sao
   tarefas separadas
5. **Testes de performance/latencia** — foco e funcionalidade e
   qualidade, nao performance
6. **Testes do MCP server** — foco e no SDK. O MCP server e wrapper
   fino, se o SDK funciona o server funciona
7. **Testes com outros idiomas alem de pt-BR e en** — foco nos 2
   idiomas que o Personal Genius usa

## Technical Context

**API publica do Arandu (v0.13.1):**

- `memory.write(agent_id, message, speaker_name=, recent_messages=)` — write pipeline
- `memory.retrieve(agent_id, query, entity_keys=, config_overrides=)` — read pipeline
- `memory.get(agent_id, fact_id)` — busca fact por ID
- `memory.get_all(agent_id, entity_keys=, limit=, offset=)` — lista facts
- `memory.delete(agent_id, fact_id)` — deleta fact
- `memory.delete_all(agent_id)` — deleta todos facts de um agente
- `memory.entities(agent_id)` — lista entidades

**Configuracoes relevantes pra testes:**

- `enable_reranker: bool` — ON/OFF pra comparar qualidade
- `topk_facts: int` — quantos facts retornar
- `min_score: float` — threshold minimo
- `min_confidence: float` — threshold de confianca

**Achados pendentes da thread anterior:**

- Achado 2a: cross-language degrada semantic search
- Achado 2b: reranker timeout ocasional em cold start

Estes achados devem ser exercitados nos cenarios pra confirmar status.

**Patterns de `.vibeflow/`:**

- `patterns/testing.md` — mock-based testing com fake providers
- `patterns/pipeline-orchestration.md` — como os pipelines se conectam
- `patterns/error-handling.md` — degradacao graceful esperada

## Open Questions

1. **Q:** O Personal Genius tem capacidade de rodar os cenarios
   programaticamente (script Python) ou vai ser manual via MCP tools?
   **Impacto:** se for programatico, os cenarios podem ter assertions
   automaticas. Se manual, precisa de criterio de observacao.
   **Proposta:** assumir MCP tools (manual com observacao), que e o
   uso real. Scripts automatizados seriam over-engineering pro objetivo.

2. **Q:** Qual o volume de dados ja existente na memoria do Pedro
   quando os testes rodarem?
   **Impacto:** testes em memoria limpa vs memoria populada dao
   resultados diferentes. Retrieve com 8 fatos e trivial; com 800 e
   o teste real.
   **Proposta:** rodar com a memoria real do Pedro (nao limpar). Isso
   e o cenario de producao.

3. **Q:** Os cenarios da Etapa 4 (ciclo completo) devem usar conversa
   real do Pedro ou conversa simulada?
   **Proposta:** conversa real. O Personal Genius conversa com o Pedro
   normalmente durante 1-2 dias e reporta os resultados. Isso e o
   teste mais valioso porque e o caso de uso real.
