house-quest/AGENTS.md

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:

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

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.