O que econ-research-kit faz?
Pesquisa em economia como um conjunto de etapas executáveis. Não é uma coleção de prompts — é uma biblioteca de fluxos de trabalho onde cada habilidade declara suas entradas, seus artefatos e seus critérios de aceitação.
O que é, e o que não é
Isto é um conjunto de oito habilidades, cada uma cobrindo uma etapa de um projeto empírico. Cada habilidade informa quando entrar, o que precisa, o que fazer, quais arquivos deve produzir e como verificar o resultado.
Isto não é um depósito de prompts. Um prompt produz texto. Uma habilidade produz arquivos que outra pessoa pode reexecutar. Se uma etapa termina com "o assistente escreveu um belo parágrafo", a etapa não foi concluída.
Também não é: um substituto para seu julgamento sobre identificação. As habilidades aqui forçam você a declarar suas premissas e suas ameaças. Elas não podem dizer se as premissas são verdadeiras.
Livro complementar: book/ contém Prompt Engineering for Economists por LW Walker, com queridos amigos e amada família, 208 páginas e sessenta modelos. O livro explica por que cada etapa é moldada desta forma; este repositório diz o que fazer nela. book/README.md mapeia capítulos em etapas.
As oito etapas
| # | Etapa | Habilidade | A pergunta que responde |
|---|---|---|---|
| 0 | Portão de viabilidade | skills/feasibility/ | Isto pode ser feito com os dados e a variação disponíveis? |
| 1 | Problema e literatura | skills/literature/ | A lacuna é real e vale um artigo? |
| 2 | Desenho de identificação | skills/identification/ | Que variação identifica o efeito, e o que o quebraria? |
| 3 | Dados | skills/data-prep/ | As variáveis estão definidas como penso que estão? |
| 4 | Estimação | skills/estimation/ | A especificação é defensável, e contra o que cada teste de robustez protege? |
| 5 | Tabelas e figuras | skills/tables-figures/ | As saídas atendem ao formato do periódico? |
| 6 | Relatório | skills/report/ | Outra pessoa pode reproduzir isto a partir dos meus arquivos? |
| 7 | Redação e submissão | skills/writing/ | A prosa transmite a história da identificação? |
| — | Resposta a pareceristas | skills/review/ | Como responder sem ceder o que não se deve? |
A etapa 0 é um portão, não um passo. Se falhar, pare. Não limpe dados para um projeto cuja identificação não pode funcionar.
Roteamento: o que o usuário diz, qual habilidade entrar
Antes de ler a tabela abaixo, execute python scripts/preflight.py "<as palavras do usuário>". Ele informa quais dos quatro slots estão faltando. Em seguida, execute python scripts/spec.py "<as palavras do usuário>": ele imprime um rascunho de especificação de tarefa — os quatro slots, a etapa que lê, um prompt editável e as três coisas a confirmar — e esse rascunho é o que você mostra ao usuário antes de fazer qualquer trabalho. Editem juntos, depois comecem. Todo "primeiro movimento" na tabela ocorre somente após os quatro slots serem preenchidos; enquanto um slot estiver aberto, o único movimento é perguntar sobre ele.
| O usuário diz algo como | Entrar | Primeiro movimento |
|---|---|---|
| "Quero estudar X, isso é viável?" / "Tem dados?" / "isso é provavelmente inviável" | skills/feasibility/ | Enumere os dados e a variação antes de escrever qualquer código |
| "Alguém já fez isso?" / "novelty" / "lacuna na literatura" | skills/literature/ | Escreva o plano de busca primeiro, depois construa a matriz |
| "Uso DID / IV / RDD / estudo de evento" / "estratégia de identificação" / "como identifico isso" | skills/identification/ | Escreva a lista de ameaças antes da regressão |
| "Limpar os dados" / "como construir a variável" / "não consigo mergear" / "definição" | skills/data-prep/ | Verifique as definições das variáveis entre os anos primeiro |
| "Rodar uma regressão" / "adicionar efeito fixo" / "robustez" / "robustness" | skills/estimation/ | Justifique o nível de clustering e o conjunto de efeitos fixos |
| "Fazer uma tabela" / "tabela de três linhas" / "desenhar gráfico de estudo de evento" / "tabela de regressão" | skills/tables-figures/ | Decida Stata ou Python, depois iguale ao formato do periódico |
| "Organizar como relatório" / "reproduzir" / "pacote de replicação" | skills/report/ | Faça do relatório uma saída de script, nunca um arquivo editado manualmente |
| "Escrever resumo" / "escrever introdução" / "submeter" / "abstract" | skills/writing/ | Rascunhe o parágrafo de identificação antes da introdução |
| "Como responder ao parecerista" / "referee report" / "réplica" | skills/review/ | Classifique cada comentário como obrigatório / discutível / rejeitável |
Se duas habilidades puderem ser aplicadas, vá a montante. Um problema de tabela geralmente é um problema de especificação; um problema de especificação geralmente é um problema de identificação.
Antes de qualquer coisa: lembrar, depois perguntar
Toda sessão começa com arquivos, não com memória:
python scripts/recall.py
Ele imprime onde o projeto está, o que a última etapa produziu e o que ainda está aberto.
Uma sessão que o ignora vai refazer perguntas que o repositório já responde, ou reconstruir algo que já existe. Execute-o primeiro, depois scripts/preflight.py, depois responda.
Cinco regras rígidas
1. Pergunte antes de responder: não prossiga até que os quatro slots estejam preenchidos.
Em qualquer solicitação de pesquisa, a primeira ação é python scripts/preflight.py "<as palavras do usuário em seu próprio idioma>". Ele divide a pergunta em quatro slots — unidade de análise, variável de tratamento, resultado, comparação — e informa quais estão faltando.
- Slots faltando: escreva no máximo três perguntas, faça todas de uma vez, depois pare e aguarde a resposta.
- Um slot que você preencheu por inferência deve ser marcado como "assumindo X", e o usuário deve confirmá-lo.
- Somente quando todos os quatro slots estiverem preenchidos — pelo usuário, ou por uma premissa que o usuário confirmou — você pode entrar no passo 2 de qualquer habilidade. Esta é a única regra no kit que exige parar para esperar um humano. Trabalho produzido após este portão é um palpite vestido de documento.
2. Leia glossary.yaml antes de escrever qualquer termo metodológico.
Ele tem três níveis: locked (use literalmente), pending (use o primeiro candidato e coloque a alternativa entre parênteses), fallback (mantenha o substantivo próprio em chinês, dê a expansão em inglês uma vez). Violar uma tradução locked é um defeito, não uma escolha de estilo.
3. Especificidades de domínio vivem em domains/, não nas habilidades.
As habilidades descrevem como trabalhar. Elas não descrevem o que é a Inspeção Central de Proteção Ambiental, como o CFPS define educação, ou o que os pareceristas perguntam sobre exposição à poluição. A última seção de cada habilidade informa qual arquivo de domínio abrir. Abra-o.
4. Toda etapa deve deixar um arquivo, e todo arquivo deve passar em sua lista de aceitação.
## Acceptance é uma lista de verificação, não uma sugestão. Um item para o qual você não pode responder sim/não é um item mal escrito — reescreva-o.
5. Diga onde você está antes de fazer qualquer outra coisa. Toda resposta que entra em uma etapa abre com três linhas: qual etapa (número e nome), o que este passo isolado faz (uma frase, nunca "analise os dados"), e qual arquivo produzirá mais se o usuário deve confirmar antes de você continuar. Uma resposta sem esse cabeçalho é uma caixa preta, e o usuário paga por ela.
Toda etapa também termina fazendo uma pergunta e esperando. Veja a tabela abaixo.
Oito pontos de confirmação
O portão na etapa 0 não é o único. Cada etapa fecha com uma pergunta e para. Isso não é cortesia: uma decisão que o usuário nunca viu é uma decisão que o usuário não pode corrigir.
| Etapa | A pergunta para parar e fazer | Continuar sem resposta |
|---|---|---|
| 0 Viabilidade | Os quatro slots estão preenchidos; você pode confirmar os dois que inferi? | Não |
| 1 Problema e literatura | Qual destas três perguntas candidatas? A lacuna é esta? | Não |
| 2 Desenho de identificação | Grupo de tratamento, grupo de comparação, período definidos assim: você aceita? | Não |
| 3 Dados | Definições de variáveis e limites da amostra definidos assim: você aceita? | Não |
| 4 Estimação | Especificação principal e esta lista de robustez: adicionar ou remover algo? | Não |
| 5 Tabelas e figuras | Este layout de tabela e estilo de nota: é o que você deseja? | Não |
| 6 Relatório | Conclusão de uma página escrita assim: alguma mudança em como os números são lidos? | Não |
| 7 Redação | Qual parte deste rascunho volta? | Não |
| 8 Resposta a pareceristas | Revisamos este comentário ou contestamos, e esta é a razão? | Não |
python scripts/stage.py 3 imprime o cabeçalho e a pergunta para qualquer etapa, para que a redação não se desvie entre sessões. workflows/main.yaml é a mesma linha principal escrita como um contrato de transferência legível por máquina: cada etapa declara requires (o que já deve estar no disco) e produces (o que deve deixar para trás), e python scripts/workflow_check.py falha se uma etapa requer algo que nenhuma etapa anterior produz. python scripts/gate.py status torna o portão mecânico em vez de uma convenção: ele mantém um arquivo de estado por projeto (.econ-kit/gate.json), recusa avançar até que os artefatos da etapa existam e uma resposta humana de pelo menos oito caracteres seja registrada, e registra a resposta com um timestamp. gate.py pass "<a resposta>" é a única maneira de avançar; --force existe, mas escreve a lacuna no registro. Para ver o que as verificações de qualquer etapa realmente procuram, execute python scripts/explain.py 6 (--list mostra todas as nove etapas; para as etapas 3 e 4, que já têm scripts executáveis, ele aponta para esses scripts e para a lista de aceitação da habilidade).
Quando um termo é incerto
Nunca escolha silenciosamente uma tradução. Se o termo estiver em pending, use o primeiro candidato e acrescente a alternativa entre parênteses. Marque no máximo três desses lugares em uma saída; além disso, use o primeiro candidato silenciosamente e adicione uma linha de resumo no final.
Se o termo não estiver no glossário, mantenha o original em chinês e dê uma expansão em inglês entre parênteses. Em seguida, adicione-o a pending em glossary.yaml para que a próxima pessoa não tenha que decidir novamente.
Consulta de domínio
| Direção | Diretório |
|---|---|
| Economia energética e ambiental | domains/energy-env/ |
| Economia do trabalho | domains/labor/ |
| Economia da educação | domains/education/ |
| Economia da saúde | domains/health/ |
| Economia comportamental e experimental | domains/behavioral/ |
| Desenvolvimento e experimentos de campo | domains/development/ |
| Economia pública e avaliação de políticas | domains/public/ |
| Organização industrial e regulação | domains/industrial-organization/ |
| Economia do comércio e espacial | domains/trade-spatial/ |
| Macroeconomia e finanças | domains/macro-finance/ |
| História econômica e fontes textuais | domains/economic-history/ |
| Modelagem teórica e desenho de mecanismos | domains/theory/ |
Doze direções são cobertas. As três primeiras são aquelas em torno das quais este kit foi construído; trabalho, educação e saúde são os três campos que o livro trata juntos sob microeconomia aplicada; o restante foi adicionado para que um leitor fora da microeconomia aplicada ainda encontre uma estante para se apoiar.
Cada direção tem cinco arquivos: institutional.md (contexto e parágrafos prontos para citar), measures.md (como a variável de tratamento é construída), data.md (fontes e nomes de variáveis), pitfalls.md (o que os pareceristas perguntam e como responder) e route.md (como esta direção percorre as oito etapas).
Dados
data-dict/ contém fontes de microdados chinesas: CFPS, CHARLS, o Banco de Dados de Empresas Industriais Chinesas e dados de monitoramento de poluição. Verifique antes de inventar um nome de variável — o conjunto de dados provavelmente já tem um. Se sua fonte não estiver lá, leia data-dict/README.md primeiro: algumas fontes recebem uma entrada e outras deliberadamente não, e um nome de variável adivinhado é pior do que um marcado.
Quando a pergunta não é "como essa variável se chama", mas "existe uma fonte para isso", data-dict/_catalog.md e scripts/lookup_source.py pesquisam um diretório externo de mais de mil fontes com links de acesso e artigos de aplicação. Esses resultados são pistas, não entradas: os arquivos numerados aqui continuam sendo o único lugar onde os detalhes em nível de variável são escritos.
O que este kit não fará
- Não decidirá se sua identificação é crível. Fará você escrever as ameaças.
- Não substituirá a leitura do artigo que você está citando. Referências alucinadas são a falha mais comum da redação assistida por IA;
skills/writing/inclui uma etapa de verificação. - Não será executado sozinho. Os scripts em
scripts/verificam a estrutura; a análise é sua.