Apêndice D — Especificação metodológica desta base
Os capítulos desta parte seguem três camadas de autoridade: as normas internacionais (Cochrane, Campbell, JBI, PRISMA, GRADE, CERQual, RAISE e afins), a especificação metodológica desta base e a proposta OQF (Schaefer et al. 2025). A especificação é a camada do meio. Ela corrige fragilidades da proposta OQF, fixa convenções onde as normas deixam escolha e define o contrato da skill revisao-sistematica. Quando um capítulo escreve “especificação desta base” ou marca uma regra com “(E)”, é deste apêndice que está falando.
Este apêndice é um índice das regras, e não a fundamentação delas. Cada item remete à seção onde a regra é discutida com as fontes. Três avisos valem para tudo o que segue:
- As normas prevalecem. Se uma norma for mais exigente que a especificação, vale a norma (exemplo: o mínimo de estudos para testar diferença entre subgrupos, na Seção 8.1).
- Pontos de corte próprios são convenções. Limiares que não vêm de norma externa (por exemplo, ≥ 5 estudos e ≥ 70% na regra de rótulo sem meta-análise, ou a pontuação de implementação) precisam ser declarados no protocolo, com a versão da regra, e podem mudar por emenda justificada (Seção 3.3).
- A skill está em construção. A Seção D.5 descreve o contrato planejado; nomes de arquivos e comandos podem mudar até a primeira versão pública.
D.1 Regras metodológicas
A numeração dos itens é a usada nas remissões dos capítulos (“item 3”, “item 8”).
| Item | Regra | Onde está fundamentada |
|---|---|---|
| 1 | Dicionários etiquetam e ordenam; não excluem. Exclusão por dicionário só se prevista no protocolo e validada por amostra de elusão. Registro sem resumo nunca é excluído por filtro textual. Expressões regulares usam fronteira de palavra e são testadas contra falsos acertos (SEM/sem, ols/bolsa, refis/Refiscalizar). Tipo de documento e idioma não excluem literatura cinzenta sem justificativa. | Seção 5.1 |
| 2 | Direção pelo estimador pontual, relativa à direcao_desejada declarada por desfecho; significância em variável separada. Nenhum “sem efeito” por p > 0,05. Contagem por direção usa teste de sinal (McKenzie e Brennan 2024). |
Seção 7.4; Seção 8.1 |
| 3 | Estudo > relato > efeito, com identificadores próprios; versões preprint (ou working paper) e publicada ligadas como relatos do mesmo estudo desde a deduplicação, nunca fundidas, e os demais relatos ligados depois do texto completo. Revisões sistemáticas e meta-análises nunca entram como estudo primário: alimentam a bola de neve e a validação da busca, ou viram objeto de uma revisão de revisões. | Seção 5.1; Seção 1.1 |
| 4 | Dependência de efeitos. O protocolo fixa a regra de modelo principal. Por análise, um efeito por estudo, ou modelo CHE com variância robusta (CR2); graus de liberdade de Satterthwaite abaixo de 4 indicam resultado não confiável (Pustejovsky e Tipton 2018, 2022). Testes de combinação usam um p por estudo. | Seção 8.1; Seção 8.2 |
| 5 | Testes combinados da proposta OQF são análise secundária, com ressalva obrigatória: Stouffer ponderado com p unilateral na direção declarada; Cooper como teste de sinal exato sobre a direção; Fisher rotulado “não direcional”. Nenhum deles define sozinho o rótulo da caixa de ferramentas. | Seção 8.1 |
| 6 | Conversões de tamanho de efeito por tabela com fórmula e pressupostos em cada linha; conversão fora da tabela é marcada como aproximada e testada em sensibilidade. Faixas de magnitude do campo são fixadas no protocolo, não as convenções genéricas de Cohen. | Seção 7.4; Seção 3.1 |
| 7 | Comparabilidade antes de agregar (família de intervenção, comparador, construto do desfecho, janela, população, estimando; randomizados e não randomizados separados). Mínimos: k ≥ 3 para agregar; τ² e intervalo de predição interpretados com k ≥ 5; ≥ 3 estudos por nível de subgrupo para estimar; cerca de 10 estudos por covariável na meta-regressão; funil, Egger e PET-PEESE com k ≥ 10. Modelo padrão de efeitos aleatórios com REML e HKSJ modificado, τ² com intervalo, I² e intervalo de predição; sensibilidade sem um estudo por vez, sem risco alto ou crítico e sem conversões aproximadas; modelo de seleção de três parâmetros como sensibilidade (Deeks et al. 2024; Page et al. 2024). | Seção 8.1 |
| 8 | Qualidade não é desenho. Escala de Maryland e hierarquias servem para critério de elegibilidade de desenho e para descrever estudos. O risco de viés é julgado por domínio, com a ferramenta do desenho: RoB 2 (Sterne et al. 2019); ROBINS-I V2 com os critérios de Waddington e colegas para quase-experimentos (Sterne et al. 2025; Waddington et al. 2017); critérios EPOC para séries temporais interrompidas e antes e depois controlado (Cochrane Effective Practice and Organisation of Care (EPOC) 2017); CASP ou JBI para qualitativos (Critical Appraisal Skills Programme 2024; JBI 2024); JBI transversal para quantitativos descritivos; MMAT para estudos primários mistos (Hong et al. 2018); AMSTAR 2 ou ROBIS para revisões (Shea et al. 2017; Whiting et al. 2016). O julgamento entra em sensibilidade, estratificação e GRADE, e não em exclusão automática. | Seção 6.1; Seção 6.3 |
| 9 | Busca revisada por pares com PRESS (McGowan et al. 2016); conjunto de estudos-âncora montado sem usar as strings, para estimar recall relativo; alerta quando mais de 25% a 30% dos incluídos vêm de outros métodos; log no formato PRISMA-S (Rethlefsen et al. 2021); alerta quando a última busca tem mais de 12 meses. | Seção 4.2; Seção 4.1 |
| 10 | Fluxograma PRISMA calculado das tabelas do projeto, com somas conferidas; “não revisado” é NA e fica fora do κ (Page et al. 2021). | Seção 5.5 |
| 11 | Etapas que a proposta OQF não prevê: checagem de revisões existentes e registradas; registro no OSF (Akker et al. 2023); checagem de retratações; contato com autores para dados faltantes; viés de relato (ROB-ME); unidade de análise em desenhos por cluster; lente de equidade PROGRESS-Plus (O’Neill et al. 2014); log de desvios do protocolo; pacote de dados e código (PRISMA 2020, item 27); passagem da evidência à decisão com transferibilidade ao Brasil. | Seção 1.1; Seção 3.3; Seção 5.6; Seção 6.3; Seção 2.1; Seção 10.4; Seção B.4 |
| 12 | Ordem das etapas: o protocolo já contém codebook v0, ferramentas de risco de viés, plano de síntese e plano de IA; depois vêm busca, deduplicação, triagem de títulos e resumos, texto completo, ligação de relatos, piloto de extração, extração e risco de viés em paralelo, síntese, certeza e caixa de ferramentas. A bola de neve é triada com a mesma versão dos critérios e entra no ramo “outros métodos” do fluxograma. | Seção 3.1; Seção 5.1 |
D.2 Matriz de tipos de revisão
A matriz completa, com framework, busca, triagem, risco de viés, família de codebook, síntese, certeza, diretriz de relato e portões por tipo, está na Seção 1.1. Os tipos reconhecidos são: efetividade com meta-análise; efetividade sem meta-análise (relato pelo SWiM (Campbell et al. 2020)); revisão mista e sequencial no formato OQF; revisão de escopo; mapa de evidências e lacunas; síntese de evidências qualitativas; revisão realista; revisão de métodos mistos, incluindo QCA; revisão rápida; e revisão guarda-chuva. Revisão narrativa, bibliometria isolada e resumo de literatura feito por IA não contam como revisão sistemática.
D.3 Validação de IA
O protocolo de validação completo (passos A a H), com limiares e remédios, está na Seção 12.1 e na Seção 12.5; a validação da extração, na Seção 12.6. Em resumo:
| Etapa | Regra |
|---|---|
| Calibração humana da triagem | Dupla humana em ≥ 100 registros ou ≥ 10 incluídos; κ ≥ 0,6 e concordância ≥ 75% |
| Prompt | Desenvolvido só no conjunto de desenvolvimento e congelado (prompts/vN.md, modelo, parâmetros e hash) |
| Validação | Amostra nova com dupla humana, enriquecida para ≥ 60 incluídos; sensibilidade, especificidade, precisão, κ, PABAK e WSS com intervalo de Clopper-Pearson |
| Aceitação | Recall ≥ 0,95 com limite inferior do IC 95% ≥ 0,90 |
| Depois da rodada | Amostra de elusão dos excluídos (n ≥ 300 ou todos); reexecução de 5% a 10% para estabilidade |
| Texto completo | O modelo só propõe, com trecho literal e página; a decisão é humana |
| Extração numérica | 100% conferida com âncora de página, ou dupla extração com arbitragem |
| Extração categórica | Segundo codificador cego em ≥ 20% dos estudos (mínimo 10); κ ou PABAK ≥ 0,7 e concordância ≥ 80% por variável |
| Juízos | Risco de viés, temas analíticos, configurações contexto-mecanismo-resultado, calibração de QCA e CERQual são humanos; o modelo pode rascunhar com trecho |
| Declaração de uso | Gerada do log: ferramenta, modelo, versão, datas, parâmetros, papel por etapa, prompts com hash, validação, custo e responsabilidade humana (Thomas et al. 2026; Holst et al. 2025) |
D.4 Caixa de ferramentas e certeza
As regras de rótulo estão na Seção 9.4, e a certeza, na Seção 10.1. A célula da caixa é família de intervenção × construto de desfecho e guarda a versão da regra, os estudos, as estimativas, a certeza e a assinatura de quem aprovou. Como randomizados e não randomizados não se agregam juntos, cada célula tem um corpo de evidência por classe de desenho e uma linha de painel que os resume.
| Linha | Regra resumida |
|---|---|
| Efeito | Positivo ou Negativo (estimativa com IC que exclui zero e certeza ao menos baixa; sem meta-análise, teste de sinal com p < 0,05, ≥ 5 estudos, ≥ 70% na mesma direção e não só estudos de risco alto); Nulo (IC inteiro dentro de ±δ fixado a priori e certeza ao menos moderada); Misto (intervalo de predição cobre benefício e dano relevantes e há explicação por moderador pré-especificado ou achado qualitativo; na versão caixa-3, só com k ≥ 5, δ fixado a priori e achado explicativo com confiança própria, CERQual ou ICEMAN, ao menos baixa); Inconclusivo nos demais casos, inclusive quando a explicação é alegada sem esses requisitos. Ordem de aplicação na versão caixa-3: sem certeza, Pendente; certeza muito baixa, Inconclusivo; depois Misto (ou Inconclusivo por Misto não sustentado), Positivo ou Negativo, Nulo e Inconclusivo |
| Painel | Uma linha por família × construto que resume os corpos por desenho: um só corpo, o rótulo dele; mesmo rótulo, esse rótulo com a maior certeza; rótulos diferentes, o do corpo de maior certeza, com o outro anotado; mesma certeza e rótulos diferentes, Inconclusivo por heterogeneidade entre desenhos; algum corpo pendente, Pendente (Seção 9.4; Seção 11.3) |
| Escala | Faixas de magnitude do campo declaradas no protocolo |
| Força | Certeza GRADE da célula: alta = forte; moderada = moderada; baixa = fraca; muito baixa = insuficiente (Balshem et al. 2011) |
| Implementação | Um ponto por critério presente (mais de dois componentes; mais de um nível de governo ou vários atores; nova infraestrutura ou pessoal; barreiras de fidelidade ou adoção em ≥ 2 estudos; longo tempo até o efeito): 0 a 1, Simples; 2 a 3, Moderada; 4 ou mais, Complexa |
| Mecanismo, moderador, percepção, custo | Enunciados de achado com estudos de suporte e confiança CERQual (Lewin et al. 2018); custo unitário ou custo-efetividade quando houver, senão “não reportado” |
| Certeza | GRADE por célula de efeito, com indireção que inclui contexto institucional, nível de governo e estimando; abordagem de Murad e colegas quando não há meta-análise (Murad et al. 2017); CERQual por achado qualitativo; revisões realistas e QCA recebem enunciado narrativo, sem pseudo-GRADE (Seção 10.3) |
| Da evidência à prática | Critérios de Evidence to Decision reduzidos (benefícios e danos, certeza, custo, equidade, viabilidade, transferibilidade ao Brasil) (Moberg et al. 2018); nenhuma implicação mais forte que a certeza (Seção 10.4) |
Os rótulos se inspiram no EMMIE e no Teaching and Learning Toolkit (Johnson et al. 2015; Education Endowment Foundation 2021). Os testes combinados nunca definem rótulo.
D.5 Contrato da skill
A skill revisao-sistematica operacionaliza as regras acima. O contrato abaixo resume o que os capítulos citam nas seções “Na skill”; o detalhe por etapa está nelas.
Fluxo e portões. 0 configuração e ambiente → 1 pergunta e tipo, com checagem de revisões existentes (G1) → 2 teoria do programa e framework → 3 protocolo com codebook v0, ferramentas de risco de viés, plano de síntese e plano de IA, registrado no OSF (G2) → 4 busca com strings por base, PRESS, estudos-âncora e log PRISMA-S (G3) → 5 importação, deduplicação e funil que etiqueta → 6 triagem de títulos e resumos com validação da IA (G4) → 7 textos completos, elegibilidade, ligação de relatos, bola de neve e retratações (G5) → 8 piloto de extração (G6) → 9 extração e risco de viés em paralelo, com efeitos verificados (G7) → 10 síntese, certeza e caixa de ferramentas (G8) → 11 relato com fluxograma calculado, checklists e declaração de IA (G9).
Modos. No modo de checkpoints (padrão), a skill para em todos os portões. No autopiloto, para só em G1 e G2; as demais validações humanas viram pendências registradas, e relatório e declaração de IA saem marcados como “RASCUNHO NÃO VALIDADO”, com a lista do que falta.
Estado e registro. O estado fica em rs_estado.json, o histórico em rs_log.jsonl (só acréscimo) e as decisões de triagem em dados/decisoes.jsonl. Só o rs.py escreve nesses arquivos; toda sessão começa por rs.py status. Artefatos congelados (protocolo, critérios, prompts, codebook, filtros) guardam caminho, SHA-256 e data. Na consolidação das decisões, a correção humana prevalece sobre o árbitro, e o árbitro sobre o consenso; o resto vai para leitura humana.
Identificadores e deduplicação. Cada linha importada recebe id_registro; cada registro único, id_rs; cada estudo, id_estudo; e a chave de citação liga a revisão às skills de PDFs, fichamento e BibTeX. Junções são sempre por identificador, nunca por título. A deduplicação compara pares dentro de blocos (mesmo DOI, mesmo identificador da fonte, mesmos quatro primeiros caracteres do título normalizado ou mesmo sobrenome do primeiro autor, com diferença de ano de até 1). Funde automaticamente por DOI, identificador da fonte ou título normalizado idêntico com sobrenome compatível; similaridade de título ≥ 95 com o mesmo sobrenome também funde, mas fica marcada para auditoria; similaridade entre 85 e 95, ou conflito de DOI, sobrenome ou ano, vira candidato para decisão humana. Tese e artigo do mesmo trabalho não se fundem: ligam-se como relatos do mesmo estudo. Preprint ou working paper e versão publicada também não: com similaridade ≥ 95, mesmo sobrenome e anos presentes, ligam-se automaticamente no mesmo id_estudo (sem nunca juntar dois relatos publicados no mesmo estudo); nos demais casos, viram candidatos a ligação para decisão humana. Cada relato segue para a triagem com seu id_rs. As regras e exemplos estão na Seção 5.1 e na Seção 5.2.
Harmonização e contagens. Arquivos brutos ficam intocados e com hash; colunas são mapeadas por nome, nunca por posição; idiomas são normalizados. O fluxograma sai das tabelas, e os invariantes (triados = excluídos na triagem + buscados; avaliados = buscados − não recuperados; avaliados = excluídos no texto completo + incluídos + aguardando classificação) encerram o comando com erro se não fecharem (Seção 5.5).
Subagentes e salvaguardas. Triagem em lotes de 20 a 30 registros por id_rs, até quatro subagentes em paralelo, com resposta JSON validada por esquema e trecho literal conferido contra título e resumo; lote inválido é refeito por outro subagente. O resumo que um subagente devolve nunca é prova: só a validação programática confirma. Na extração e no risco de viés, trecho ausente do PDF é rejeitado pelo gate de citação e refeito. Acima de cerca de 1.500 registros recomenda-se o modo API, com dois modelos e árbitro de terceiro provedor que vê revisores anônimos (Seção 12.1).
Pedidos parciais. “Só a triagem” parte de uma exportação ou planilha e segue importação, deduplicação opcional, triagem e validação; “só a meta-análise” parte de uma tabela com médias e desvios, t e graus de liberdade ou coeficiente e erro-padrão e segue analise preparar-efeitos → efeitos.R → meta.R; “só o PRISMA” aceita contagens manuais e imprime “NR” onde o número é desconhecido. Pedidos de PDFs, fichamento ou BibTeX vão direto às skills irmãs.
Acréscimos do contrato (versão 1.1). Os nomes abaixo estão centralizados no esquema da skill (esquema.py) e detalhados em docs/CONTRATOS.md, seção “Contratos v1.1”.
| Tema | O que a skill passou a registrar ou exigir | Onde está a regra |
|---|---|---|
| Busca substituída | importar --substituir <busca> --motivo marca a busca antiga com ativa: false, sem apagar linhas; o dedup marca com a flag busca_inativa os registros únicos que só vinham dela; filtros, triagem (por lotes e via API), amostras de validação, bola de neve e fluxograma deixam esses registros de fora. A importação guarda os metadados do PRISMA-S (--string-id, --executada-em, --n-base, --filtros-na-base, --plataforma) |
Seção 4.2; Seção 4.1 |
| Estudos-âncora | filtrar --ancoras grava 01-busca/recall_ancoras.json com recall combinado, por busca e por base; o portão G3 avisa, sem bloquear, quando o arquivo falta ou quando o recall combinado fica abaixo de 1, com a lista das âncoras não achadas |
Seção 4.2 |
| Texto completo | Decisão final incluir, excluir ou aguardando (no registro de decisões, “aguardando” é um incerto humano na etapa de texto completo); recuperado no inventário, com conferência humana em 03-textos/conferencia_pdfs.csv; textos retratacoes (03-textos/retratacoes.csv) e textos contato-autores (03-textos/contato_autores.csv) |
Seção 5.1; Seção 5.6; Seção 5.5 |
| Validação da triagem | Cada cálculo declara a finalidade (calibração, desenvolvimento, validação, elusão ou estabilidade); só a validação da rodada ativa decide o G4 |
Seção 12.5 |
| Conversões de efeito | formula_id novos para as rotas aproximadas: r_d_n_total (r sem \(n_1\) e \(n_2\)), mediana_iqr_aprox (amplitude interquartil sem quartis; mediana_iqr_wan só com os quartis) e parcial_r_d_gl (correlação parcial sem o número de preditores; com ele, parcial_r_d) |
Seção 7.4 |
| Viés por resultados faltantes | PEESE só com intercepto do PET positivo e p < 0,10; --excluir-rob critico tira da análise principal os resultados com risco crítico e os mantém em sensibilidade |
Seção 8.1 |
| Pendências | Cada comando mantém no máximo uma pendência aberta por tipo e arquivo, atualiza o número de casos sem duplicar e fecha a pendência quando a condição some (conferência de elegibilidade, verificação humana dos efeitos, certeza da caixa, candidatos de duplicata, fila humana da triagem); no autopiloto, só a criação depende do modo | Parágrafo Modos, acima |
| Portões e tipos | portao GN --nao-se-aplica --motivo dispensa portões que o tipo de revisão não usa (escopo: G7 e G8; mapa de evidências: G6 a G8; realista: G4); init --variante rapida registra a revisão rápida como variante do tipo de origem; o G9 avisa, sem bloquear, quando falta o .bib ou quando a declaração de uso de IA é anterior ao último evento do registro |
Seção 1.1; Seção D.2 |
Acréscimos do contrato (versão 1.2). Detalhados em docs/CONTRATOS.md, seção “Contratos v1.2”.
| Tema | O que a skill passou a registrar ou exigir | Onde está a regra |
|---|---|---|
| Estado e retomada | Trava entre processos em todo escritor de estado e registro, com número de sequência único mesmo com comandos em paralelo; estado corrompido encerra com erro e orientação de restaurar do controle de versão; status acha projetos em subpastas e init recusa criar outro por cima; a próxima ação sugerida traz marcadores <...> onde há valor a conferir, em vez de números |
Parágrafos Estado e registro e Modos, acima |
| Protocolo (G2) | O portão exige, além do protocolo, o codebook v0 e o codebook de elegibilidade, e bloqueia com marcadores de modelo não preenchidos; o codebook v0 de efetividade é o bloco comum mais o bloco b2 do codebook OQF; os identificadores dos critérios são os mesmos no protocolo, na triagem e no codebook (C4 desenho, C5 estudo primário, C6 retratação, esta só no texto completo) | Seção 3.1 |
| Busca (G3) | O portão exige PRESS registrado (ou pendência de revisão por pares no autopiloto) e bloqueia com busca de teste truncada ainda ativa, que também deixa o fluxograma como rascunho; buscar openalex --substituir troca a busca de teste pela completa; o número de resultados declarado de uma busca do OpenAlex é conferido com o total informado pela API |
Seção 4.2; Seção 4.1 |
| Deduplicação | Preprint e versão publicada viram relatos ligados, sem fusão (item 3); decisões humanas sobre pares exigem o papel de quem decidiu | Seção 5.1 |
| Triagem (G4) | Planilhas preenchidas por humanos são lidas com vírgula, ponto e vírgula, tabulação ou em .xlsx; a fila humana nunca é regravada com decisões ainda não aplicadas; exclusão humana exige um critério que exista na rodada; validação reprovada só pela largura do intervalo (sem falsos negativos) orienta ampliar a amostra ou, com menos de 36 incluídos possíveis, a dupla humana completa com aprovação humana forçada; na revisão rápida com o atalho aprovado no G1, o G4 aceita dupla humana em ≥ 20% dos registros, κ calculado e segunda leitura de todos os excluídos pela IA no lugar do recall ≥ 0,95 |
Seção 12.5; Seção 1.1 |
| Texto completo | Fila humana gerada por comando (triagem fila --etapa tc), com critério obrigatório nas exclusões; pendência de retratação fechada por humano não reabre enquanto os retratados forem os mesmos |
Seção 5.1; Seção 5.6 |
| Risco de viés (G7) | qualidade consolidar mede a concordância de dois avaliadores por domínio, gera a fila de desacordos, exige consenso humano e aplica o algoritmo da ferramenta ao consenso (pior domínio no RoB 2 e no ROBINS-I V2, pior critério no EPOC); fora de escopo e mapa, o G7 só aprova com o risco de viés consolidado e com os arquivos da consolidação inalterados; a concordância da extração categórica gera aviso; o codebook do ROBINS-I V2 usa os códigos de resposta oficiais, com as versões fraca e forte do sim e do não |
Seção 6.11; Seção 6.3 |
| Desfechos binários | Proporções por grupo, efeitos em pontos percentuais de modelo de probabilidade linear, DiD ou RDD, e razão de riscos convertidos a d pelo log da razão de chances com a proporção do controle (dif_prop_contagens, dif_prop_lpm, rr_logit); as rotas de modelos ajustados e de razão de riscos são aproximadas e vão para a sensibilidade (Chinn 2000; Zhang e Yu 1998) |
Seção 7.4 |
| Síntese quantitativa | PET-PEESE na variante de mínimos quadrados ponderados com erro multiplicativo e teste t, registrada no resultado; --excluir-rob critico também na síntese sem meta-análise e nos testes combinados, sempre depois de escolhido o efeito, a direção ou o p de cada estudo |
Seção 8.1; Seção 8.7 |
| Caixa e certeza (G8) | Versão de regra caixa-3 (Misto só com k ≥ 5, δ e achado explicativo com confiança própria) e linha de painel por família × construto (tabela acima); o G8 exige o arquivo de certeza com uma linha por célula de efeito e, em revisão OQF, a caixa |
Seção 9.4; Seção 10.1 |
| Relato (G9) | A atualidade da declaração de uso de IA é conferida pelo evento que a gerou (último evento coberto), e não pelo texto; reexecuções sem mudança não contam | Seção 11.1 |
Licenças. O código da skill é distribuído sob MIT, e os textos de referência, modelos e codebooks, sob CC BY 4.0; nenhum dado ou código do material didático do MAPE/IESP-UERJ é empacotado. Segredos (chaves de API) só por variável de ambiente.