Manual do Codex
Este documento orienta como uma pesquisa deve ser pensada, investigada e incorporada ao InfraMov. Ele não é um prompt para copiar nem uma lista de tarefas.
O Evolve é a especificação editorial e operacional que orienta o Codex a investigar, estruturar e incorporar conhecimento no InfraMov. Não é uma lista de tarefas, um changelog ou um gerador de prompts.
Objetivo operacional: Aumentar a qualidade, a cobertura e a coerência do observatório sem deixar que cada pesquisa redesenhe o produto de maneira isolada.
Escolher uma pauta antes de pesquisar
Toda investigação começa por uma pergunta catalogada na Agenda, não por uma ideia solta ou por uma página nova.
- Selecionar uma pauta existente ou criar uma nova com pergunta, escopo, não-objetivos e critérios de saída.
- Não iniciar pesquisa apenas para preencher uma cidade ou produzir volume de conteúdo.
- Definir se o resultado alimentará dados, uma pesquisa editorial, a página de uma cidade ou a homepage.
Investigar com separação epistemológica
Impedir que fato, interpretação, hipótese e ausência de dados sejam misturados.
- Registrar fonte, instituição, data de referência e nível de confiabilidade.
- Separar fatos verificáveis, leituras editoriais, hipóteses, conflitos entre fontes e lacunas.
- Não transformar uma fonte de contexto em indicador quantitativo sem suporte suficiente.
- Não preencher campos ausentes com estimativas silenciosas ou dados de outra cidade.
Mapear a saída no modelo de dados
Fazer a pesquisa ampliar a base reutilizável antes de criar exceções de interface.
- Preferir registros e campos reutilizáveis em data.ts e city-datasets.ts.
- Organizações, infraestruturas, linhas, operadores e pesquisas devem ser dados antes de serem blocos visuais.
- Criar uma nova estrutura de dados somente quando o modelo atual não representar corretamente o domínio.
- Declarar explicitamente o que continua não incorporado.
Controlar o impacto editorial
Evitar que cada nova pesquisa molde a arquitetura inteira do site.
- Homepage muda apenas quando houver síntese multi-cidade, posicionamento ou decisão de navegação.
- Página individual de cidade muda quando a leitura territorial ou o contexto daquela cidade evoluir.
- Catálogos e comparadores devem ser alimentados pelos dados, não por páginas específicas criadas para cada pesquisa.
- Uma pesquisa não cria uma rota nova se puder ser representada por dados, filtros ou uma página editorial existente.
Validar e registrar limites
Tornar o resultado auditável e impedir que intenção seja confundida com entrega.
- Executar validate:content e validate:evolve antes de considerar uma pauta incorporada.
- Executar TypeScript, build e revisão proporcional das páginas afetadas.
- Registrar arquivos, rotas, dados incorporados, limitações e pendências.
- Manter a pauta aberta quando a evidência, a implementação ou a revisão ainda estiver incompleta.
- Em mudanças de rota, cidade ou conteúdo, preservar orientação espacial e contexto; usar transição curta e suave, sem piscar ou deslocar o usuário sem explicação.
- Toda animação precisa ter fallback para prefers-reduced-motion e nunca pode ser requisito para compreender um dado, uma ação ou um estado.
Modelar presença territorial sem generalizar
Registrar como uma empresa, serviço ou infraestrutura aparece em cada cidade sem transformar catálogo nacional em prova de operação local.
- Cadastrar a organização uma vez e usar presenças territoriais para indicar serviço, status, fonte e data por cidade.
- Distinguir presença anunciada, operação documentada, disponibilidade indicada, popularidade medida e impacto avaliado.
- Não usar uma fonte de uma cidade para preencher automaticamente outra cidade.
- Quando o usuário mencionar um serviço local, transformar a afirmação em hipótese verificável e registrar a fonte necessária.
Aplicar protocolo rígido de verificação
Garantir que nenhum número, status de serviço ou leitura comparativa entre na plataforma sem medida, data, escopo e fonte identificáveis.
- Todo número precisa declarar o que mede, unidade, território, data de referência e se é censo, estimativa, observação ou cálculo.
- População nunca deve aparecer como um valor solto: separar Censo, estimativa e população presente, sem comparar medidas de naturezas diferentes.
- Toda fonte publicada precisa ter título, URL, data de referência e nível; sem isso, o registro permanece em revisão.
- Indicador calculado precisa declarar fórmula, entradas e limites; nunca apresentar cálculo do InfraMov como estatística oficial.
- Disponibilidade anunciada não prova uso, popularidade, cobertura, autorização pública, segurança ou impacto.
- Quando fontes entrarem em conflito ou a evidência for insuficiente, publicar a divergência ou a lacuna e não escolher silenciosamente o número mais conveniente.
- A validação deve falhar antes do build editorial quando um registro publicado não cumprir o contrato mínimo de evidência.
Transformar futuros em saída de dados aplicada
Manter o método de cenarização no Evolve e reservar a rota pública /futuros para séries, cenários, sinais e limites de cada cidade.
- Nunca colocar o manual, o roadmap do site ou instruções de pesquisa como conteúdo principal de /futuros.
- Toda leitura prospectiva por cidade precisa de linha de base, ao menos uma série observável, cenários explicitamente hipotéticos, sinais de acompanhamento e limitações.
- Usar gráficos somente para dados com unidade, data, escopo, natureza da medida e fonte; cálculos precisam declarar entradas e fórmula.
- Escolher a visualização pela forma do dado: linhas para séries temporais, barras ou cartões para comparações discretas e métricas para fotografias de um único ponto.
- Não compartilhar um eixo ou uma legenda quando duas medidas têm unidades, denominadores ou significados diferentes; declarar a unidade de cada série.
- Desabilitar animação em gráficos cujo carregamento possa ocultar valores em captura, acessibilidade ou leitura rápida.
- Não fabricar uma leitura geral para uma cidade sem dataset prospectivo próprio; mostrar a lacuna e encaminhar a pauta para a Agenda.
- Cenário não é previsão, política aprovada ou recomendação: é uma hipótese revisável conectada às pesquisas e análises existentes.
- Quando novos dados mudarem a leitura, atualizar o dataset da cidade e registrar a mudança no histórico do Evolve.
Fontes de verdade
- • src/lib/data.ts: entidades públicas, cidades, organizações, infraestrutura e pesquisas publicadas.
- • src/lib/city-datasets.ts: narrativa, fontes, agenda e camadas específicas de cada cidade.
- • src/lib/data.ts: mobilityServicePresences registra oferta, infraestrutura e grau de evidência por cidade sem duplicar organizações.
- • src/lib/evolve/research-agenda.ts: perguntas, critérios e saídas esperadas antes da investigação.
- • src/routes/doc.tsx: contrato técnico e editorial do sistema.
Destino da pesquisa
- Dados estruturados: Catálogos, filtros, comparações, mapas e páginas de cidade.
- Pesquisa editorial: Uma leitura interpretativa com metodologia, referências e status editorial.
- Homepage: Síntese da plataforma, prioridade de navegação ou posicionamento multi-cidade.
- Página de cidade: Contexto territorial, narrativa, fontes e leituras específicas daquele município.
- Agenda: Perguntas que ainda não têm evidência ou decisão suficiente para publicação.
Regra de segurança editorial
Se a evidência não sustentar a afirmação, manter a informação como lacuna, hipótese ou pauta futura. O Codex não deve completar o observatório por plausibilidade.