# AGENTS.md — Busca de Imóveis DF

## Finalidade

Este repositório apoia a coleta, organização e análise histórica de anúncios imobiliários do Distrito Federal para uma decisão residencial de longo prazo.

Antes de trabalhar no projeto, leia integralmente:

- `docs/PROJECT_CONTEXT.md`
- `docs/PROPERTY_CRITERIA.md`
- `docs/DATA_MODEL.md`
- `docs/ANALYSIS_RULES.md`

Esses documentos são a referência operacional do projeto. Quando houver conflito:

1. uma instrução explícita e recente do usuário prevalece;
2. depois, prevalecem estes documentos;
3. por último, hipóteses inferidas a partir dos dados.

Nunca trate uma hipótese como preferência confirmada.

Para auxiliar no entendimento e contexto, as plantas das casas dos Jardins Mangueiral estão em:

- `resources/plans`

Para auxiliar no entendimento e contexto, foram feitas capturas dos mapas dos Jardins Mangueiral, que foram salvas na em:

- `resources/maps`

---

## Banco de dados

O banco principal deve ser tratado como **estritamente somente leitura**.

### Regras obrigatórias

- Nunca execute `INSERT`, `UPDATE`, `DELETE`, `DROP`, `ALTER`, `CREATE`, `REPLACE`, `VACUUM`, `REINDEX`, `ATTACH` ou comandos equivalentes contra o banco original.
- Não substitua, mova, compacte, migre ou renomeie o arquivo original.
- Não remova arquivos `-wal` ou `-shm` sem uma instrução explícita.
- Não execute scripts de scraping contra o banco durante uma análise sem autorização.
- Use `LIMIT` em consultas exploratórias.
- Não imprima tabelas inteiras no terminal.
- Prefira agregações, amostras pequenas e exportações derivadas.
- Salve resultados em `reports/`, `exports/` ou `data/derived/`.
- Nunca grave resultados derivados dentro do banco original.
- Antes de qualquer análise, confirme o caminho do banco e abra-o em modo somente leitura.

### Abertura recomendada em Python

```python
import sqlite3

DB_PATH = "data/imoveis.sqlite"

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

Se o banco estiver sendo atualizado por outro processo, não use `immutable=1`; mantenha `mode=ro` e confirme a consistência do snapshot antes de analisar.

### Cliente de linha de comando

```bash
sqlite3 -readonly data/imoveis.sqlite
```

---

## Fluxo inicial obrigatório

Ao iniciar uma nova tarefa de análise:

1. Identifique o arquivo SQLite correto e seu tamanho.
2. Leia `sqlite_master` para listar tabelas, views, índices e triggers.
3. Examine o esquema real antes de escrever consultas analíticas.
4. Conte registros por tabela.
5. Identifique campos de data, preço, área, quartos, localização, URL, anunciante e identificadores.
6. Verifique valores nulos, duplicidades, formatos inconsistentes e possíveis quebras de coleta.
7. Descubra se os dados representam:
   - anúncios;
   - imóveis físicos;
   - observações históricas do mesmo anúncio;
   - execuções do scraper.
8. Documente qualquer ambiguidade antes de produzir conclusões.

Não presuma que o modelo lógico descrito em `docs/DATA_MODEL.md` já existe fisicamente.

---

## Princípios de análise

- Diferencie sempre **anúncio**, **imóvel físico** e **observação histórica**.
- Um mesmo imóvel pode aparecer em vários anúncios, portais, corretores ou datas.
- Um mesmo anúncio pode mudar de preço, descrição, área informada ou status.
- Preço anunciado não é preço efetivamente negociado.
- Ausência de anúncio não prova venda.
- Remoção de anúncio não prova fechamento de negócio.
- Campo preenchido pelo anunciante não deve ser considerado confiável sem validação.
- Não calcule preço por metro quadrado quando a área não for comparável ou confiável.
- Não misture área privativa, útil, construída e total sem separar os conceitos.
- Não compare períodos sem verificar mudanças no universo coletado.
- Não compare regiões sem controlar tipologia, quartos, área, garagem, estado e padrão do imóvel.
- Sempre informe tamanho da amostra, cobertura temporal, filtros e limitações.
- Prefira mediana, percentis e intervalos interquartis a médias isoladas.
- Mostre a sensibilidade das conclusões a outliers, duplicidades e dados ausentes.

---

## Segurança e desempenho

- Nunca exponha credenciais, cookies, tokens, chaves, sessões ou dados pessoais em relatórios.
- Não envie o banco ou grandes amostras para serviços externos sem autorização explícita.
- Não tente contornar mecanismos de proteção de sites.
- Respeite limites de requisição, termos aplicáveis e regras definidas para o scraper.
- Evite consultas que façam varreduras desnecessárias repetidas em tabelas grandes.
- Use `EXPLAIN QUERY PLAN` em consultas lentas.
- Sugira índices apenas como recomendação; não os crie no banco original.
- Para transformações pesadas, crie um banco derivado ou arquivos Parquet/CSV separados.

---

## Código

- Escreva scripts reproduzíveis, parametrizados e idempotentes.
- Use caminhos relativos ao repositório.
- Evite constantes escondidas.
- Registre os filtros e premissas usados.
- Inclua tratamento de erros.
- Use consultas SQL parametrizadas.
- Adicione testes para regras de normalização, deduplicação e cálculo.
- Não altere arquivos sem relação com a tarefa.
- Não faça refatorações amplas sem necessidade.
- Não invente significado para colunas pouco claras; documente a dúvida.

---

## Saídas esperadas

Relatórios analíticos devem, sempre que aplicável, conter:

1. pergunta respondida;
2. período e universo analisados;
3. filtros e exclusões;
4. tamanho da amostra;
5. método de deduplicação;
6. qualidade dos dados;
7. resultados;
8. limitações;
9. implicações para a decisão de compra;
10. consultas ou scripts usados para reproduzir o resultado.

Use gráficos apenas quando eles melhorarem a interpretação. Todo gráfico deve ter título, unidade, período, tamanho da amostra e definição da métrica.

---

## Contexto imobiliário prioritário

As regiões prioritárias são:

1. Cruzeiro, especialmente Cruzeiro Novo;
2. Jardins Mangueiral.

Não exclua outras regiões de uma análise exploratória quando forem úteis como referência, mas não desvie o projeto de seu objetivo principal sem instrução.

Para Jardins Mangueiral:

- considerar somente casas com planta original de três quartos;
- não penalizar automaticamente o fechamento do quintal;
- avaliar a funcionalidade real da conversão;
- considerar as preferências de QC descritas em `docs/PROPERTY_CRITERIA.md`;
- tratar relatos de moradores como evidência anedótica, não como fato conclusivo.

---

## Atualização do contexto

Não altere estes documentos apenas porque encontrou um padrão no banco.

Atualize-os somente quando:

- o usuário corrigir uma premissa;
- uma preferência for explicitamente confirmada;
- um valor financeiro for atualizado;
- uma regra metodológica for aprovada;
- o esquema real do projeto for consolidado.

Ao atualizar uma premissa financeira, registre a data de referência e preserve o histórico em Git.