# AGENTS.md — Busca de Imóveis DF

## Missão

Apoiar uma decisão de compra residencial de longo prazo no Distrito Federal usando o banco histórico de anúncios, as fotografias e os critérios pessoais consolidados do usuário.

O trabalho deve ser cético, reproduzível e orientado a evitar uma compra ruim. Não maximizar apenas preço por metro quadrado, valorização ou número de atributos anunciados.

## Leitura obrigatória

Antes de analisar imóveis ou alterar scripts, leia:

- `docs/CURRENT_STATE.md`
- `docs/PROJECT_CONTEXT.md`
- `docs/LOCATION_CRITERIA.md`
- `docs/PROPERTY_CRITERIA.md`
- `docs/FINANCIAL_STRATEGY.md`
- `docs/SCRAPER_OPERATIONS.md`
- `docs/DATA_MODEL.md`
- `docs/ANALYSIS_RULES.md`

Quando houver conflito, use esta precedência:

1. instrução explícita e recente do usuário;
2. `docs/CURRENT_STATE.md`;
3. documento especializado do tema;
4. snapshot ou relatório datado;
5. contexto histórico e inferências.

Nunca transforme inferência, relato de corretor, percepção de morador ou padrão do banco em preferência confirmada.

---

## Prioridade regional vigente

- **Prioridade principal:** Jardins Mangueiral.
- **Alternativa secundária e oportunística:** Cruzeiro, especialmente Cruzeiro Novo.

O ranking interno de quadras do Cruzeiro continua sendo usado para avaliar apartamentos concretos, mas não torna o Cruzeiro prioritário sobre o Mangueiral.

---

## Regras pessoais obrigatórias

### Jardins Mangueiral

- Considerar somente casas com **planta original de três quartos**.
- Excluir plantas originalmente de dois quartos, mesmo que tenham sido adaptadas.
- Não penalizar automaticamente o fechamento do quintal.
- Avaliar se a conversão cria espaço social útil, iluminado, ventilado e sem redundância funcional.
- Usar a hierarquia de QCs de `LOCATION_CRITERIA.md`, sem ignorar a posição exata da casa.
- Avaliar explicitamente ruído de vizinhos, animais, música, áreas sociais, ruas e equipamentos comuns.
- Dar preferência a casas reformadas, com bom espaço na cozinha.

### Cruzeiro

- Tratar como oportunidade secundária.
- Usar o ranking interno Ouro/Prata/Bronze de `LOCATION_CRITERIA.md`.
- Uma unidade fora da faixa superior pode vencer pela combinação de reforma, silêncio, planta, andar, elevador, garagem e preço.
- Ausência de elevador e garagem é concessão relevante.
- Confirmar se os três quartos são utilizáveis e coerentes com a planta.
- Inspecionar sistemas antigos, condomínio, fachada, prumadas, elétrica, hidráulica e obras previstas.

---

## Banco principal

Caminho esperado:

```text
dfimoveis_data/dfimoveis.sqlite3
```

O banco original é **estritamente somente leitura durante análises**.

### Proibições

Nunca executar contra o banco original:

- `INSERT`
- `UPDATE`
- `DELETE`
- `DROP`
- `ALTER`
- `CREATE`
- `REPLACE`
- `VACUUM`
- `REINDEX`
- `ATTACH`

Não mover, substituir, compactar, migrar ou renomear o banco sem instrução explícita. Não remover arquivos `-wal` ou `-shm` arbitrariamente.

### Abertura recomendada

```python
import sqlite3

DB_PATH = "dfimoveis_data/dfimoveis.sqlite3"
connection = sqlite3.connect(f"file:{DB_PATH}?mode=ro", uri=True)
connection.execute("PRAGMA query_only = ON")
```

Use `immutable=1` somente em cópia ou snapshot que não esteja sendo atualizado pelo scraper.

---

## Separação entre scraper e análise

- Não executar coleta e análise pesada simultaneamente no mesmo arquivo SQLite sem avaliar bloqueios e consistência.
- Para análise longa, preferir uma cópia/snapshot consistente ou conexão read-only.
- Resultados derivados devem ir para `reports/`, `exports/` ou `data/derived/`.
- Nunca gravar rankings, notas ou tabelas derivadas dentro do banco original sem autorização.

---

## Fluxo analítico obrigatório

0. Verificar se a primeira foto do anúncio não demonstra que ele foi vendido.
1. Confirmar o snapshot e a cobertura temporal.
2. Ler o esquema real.
3. Identificar anúncios, observações históricas, fotos e execuções de coleta.
4. Verificar falhas de coleta e mudanças do scraper.
5. Separar anúncio, observação e imóvel físico provável.
6. Deduplicar republicações sem apagar registros originais.
7. Auditar a primeira foto e a descrição para “VENDIDO”, “negócio fechado” ou equivalente.
8. Colocar inconsistências em quarentena, sem exclusão silenciosa.
9. Avaliar fotografias; CSV isolado não é evidência suficiente para planta e conservação.
10. Registrar amostra, filtros, exclusões, limitações e método.

---

## Regras analíticas essenciais

- Preço anunciado não é preço negociado.
- Desaparecimento do anúncio não prova venda.
- Selo de vendido é evidência operacional, não prova registral.
- Não misturar área privativa, útil, construída, total e terreno.
- Não usar preço por m² quando a área não for comparável ou confiável.
- Não multiplicar republicações visualmente equivalentes.
- Não considerar “reformado” como prova de renovação elétrica, hidráulica ou estrutural.
- Não atribuir causalidade à QC ou quadra sem controlar tipologia e qualidade.
- Não inferir liquidez com uma janela curta de coleta.
- Rankings servem para ordenar investigação e visitas, não para automatizar a compra.

---

## Finanças

Antes de recomendar compra ou preço máximo, leia `FINANCIAL_STRATEGY.md`.

Regras fixas:

- preservar pelo menos R$ 50.000 de reserva líquida após compra, custos e adequações;
- não tratar FGTS como reserva de emergência;
- excluir Pró-Cotista e MCMV Faixa 4 das simulações atuais;
- distinguir entrada, custos de compra, reforma, reserva e amortizações futuras;
- comparar financiamento, consórcio e aluguel com premissas datadas;
- não usar taxas antigas como atuais;
- incorporar fatores psicológicos sem convertê-los em justificativa para um imóvel inadequado.

---

## Código e relatórios

- Escrever scripts reproduzíveis, parametrizados e idempotentes.
- Usar SQL parametrizado.
- Não imprimir milhares de linhas no terminal.
- Usar `LIMIT` na exploração.
- Usar `EXPLAIN QUERY PLAN` quando necessário.
- Sugerir índices sem criá-los no banco original.
- Preservar HTML bruto, fotos e dados originais.
- Toda conclusão deve separar fato, inferência, percepção e pendência.

Um relatório deve conter:

1. pergunta;
2. snapshot e período;
3. universo e amostra;
4. filtros e quarentenas;
5. método de deduplicação;
6. avaliação fotográfica;
7. resultados;
8. limitações;
9. implicação prática;
10. consultas e scripts para reprodução.

---

## Atualização do contexto

Atualizar os documentos somente quando:

- o usuário corrigir uma premissa;
- uma preferência for explicitamente confirmada;
- houver nova visita relevante;
- um snapshot substituir o anterior;
- uma regra financeira ou operacional mudar;
- o esquema real for documentado.

Registrar a mudança em `docs/CONTEXT_CHANGELOG.md` com data e motivo.