# NEWS — Design Decisions and Methodological Evolution > **What this file is**: A reverse-chronological log of design decisions, methodological shifts, and schema changes in the process tracing database. This is *not* a Git changelog — it records *intellectual* changes: why the schema changed, what epistemological commitment drove the change, and what was gained or lost. > **O que é este arquivo**: Log em ordem cronológica reversa de decisões de design, mudanças metodológicas e alterações no esquema do banco de dados. Registra mudanças *intelectuais*: por que o esquema mudou, qual compromisso epistemológico motivou a mudança, e o que foi ganho ou perdido. --- ## 2026-05-26 (evening) — `llm_conversations_database-development/` subfolder structure and HISTORY.md **What changed**: - Inside `llm_conversations_database-development/`: - Renamed `xlxs_templates/` → `xlsx_templates/` (typo fix). - Created subfolders `conversations/`, `references/`, `drafts/`. - Moved the four conversation exports into `conversations/` (filenames preserved; proposed normalized names in `conversations/rename-suggestions.md`, pending researcher decision). - Moved the six reference PDFs into `references/`, normalizing filenames to `Authors-Year_Short-Title.pdf`. - Moved the generated draft README into `drafts/` and added a provenance comment block at its top flagging it as a pre-v3-pivot framing (advocated decibel weighting, since rejected). - Wrote `llm_conversations_database-development/README.md` as a folder-level guide. - At repo root: - Created `HISTORY.md` — narrative chronology of database evolution from 2 May 2026 (first Perplexity literature search) through 26 May 2026 (v7 working database). Explains the v3 radical pivot (drop of numerical likelihoods + symmetry of hypotheses + passage-level localization + de-manifestoed READ_ME), the two methodological turning points inside the Claude bayesian-tests conversation on 23 May 2026 (the v3→v4 explaining-outcome redesign and the retraction of the Git-as-pre-registration argument), and the start of the V5 Fairfield & Charman 2022 deep-read on 24 May 2026. - Archived prior `README.md`, `NEWS.md`, `METHODOLOGY.md`, `REPOSITORY_PLAN.md` as `md_documentation_previous_versions/{NAME}-v{N}.md` per the documentation-versioning policy in `REPOSITORY_PLAN.md` §6. - Patched `README.md` and this `NEWS.md` to reflect the new layout and to cross-link `HISTORY.md`. **Why**: The earlier 2026-05-26 reorganization (see entry below) consolidated everything under `llm_conversations_database-development/` but left a flat structure: conversations, PDFs, templates, and drafts at the same level. With 12 items at that level — including a typo (`xlxs_templates`) and a stray duplicate xlsx — the folder lost legibility. The subfolder split is a hygiene move. `HISTORY.md` exists because `NEWS.md` is a decision log, not a narrative; the *story* of the database — the dead ends, the LLM-induced reversals, the moments where the researcher dismantled a beautiful but misaligned design — required its own document. The dates inside the conversation file headers also corrected an earlier misperception: the work begins on **2 May 2026**, not 3 May and not 5 May. **Affected files**: `HISTORY.md` (new); `llm_conversations_database-development/README.md` (new); `llm_conversations_database-development/conversations/rename-suggestions.md` (new); `llm_conversations_database-development/xlsx_templates/` (renamed); `llm_conversations_database-development/conversations/`, `references/`, `drafts/` (new subfolders, populated); `README.md`, `NEWS.md`, `REPOSITORY_PLAN.md` (patched); `md_documentation_previous_versions/{README,NEWS,METHODOLOGY,REPOSITORY_PLAN}-v{N}.md` (archived). --- ## 2026-05-26 — Full commitment to Fairfield & Charman (2022): numerical probabilities adopted, Van Evera tests dropped **What changed**: `METHODOLOGY.md` rewritten to reflect full alignment with Fairfield & Charman (2022) — the book, not just the 2017 article. Key changes: (1) adopted the verbal probability scale (quase_certa → 0.95, ..., quase_impossivel → 0.05) and the decibel weight-of-evidence system from Ch. 3; (2) dropped the Van Evera tests (Hoop, Smoking Gun, Straw-in-the-Wind, Doubly Decisive) entirely — not even as communicative vocabulary; (3) documented the two-stage evidence workflow (raw → analysis) as implemented in v7. **Why**: The v3 template (and the earlier version of METHODOLOGY.md) occupied an intermediate position: qualitative Bayesian reasoning without numbers, Van Evera tests retained as vocabulary. This was based primarily on the 2017 article's permissive language ("transparency does not require assigning numerical values"). The v7 working database moved past this position by implementing the 2022 book's more developed operationalization — verbal probability scale, likelihood ratios, and decibel weights. This entry records the decision to align METHODOLOGY.md with v7 and with the full framework of the 2022 book. The Van Evera tests are superseded by the likelihood ratio: evidentiary confirmation is a matter of degree (captured by the LR and dB), not of type (captured by categorical labels). **Affected files**: `METHODOLOGY.md` (major rewrite), `NEWS.md`. **Key reference**: Fairfield & Charman (2022), Ch. 3, especially §3.6.1 ("Inhabit the World of Each Hypothesis"). --- ## 2026-05-26 (morning) — Repository documentation creation and methodological-development reframing **What changed**: Created `README.md` (v1), `NEWS.md` (v0), `METHODOLOGY.md` (v0), and `REPOSITORY_PLAN.md`. Preserved original README as `md_documentation_previous_versions/README-v0.md`. Reframed the repository purpose from "research data repository" to "methodological development repository." The conversation logs, reference PDFs, and template schemas were initially consolidated under `llm_conversations_database-development/` (with a flat structure that was later split into subfolders the same day — see the entry above). **Why**: The repository's core contribution is the database *design*, not the data it holds. The previous README described the repo as a research data project. The new documentation positions it as a record of methodological reasoning — how to structure evidence for abductive process tracing under imperfect theories. The `METHODOLOGY.md` synthesizes the epistemological premises (drawn from Fairfield & Charman, 2022) to guide any collaborator or AI assistant. **Affected files**: `README.md`, `NEWS.md`, `METHODOLOGY.md`, `REPOSITORY_PLAN.md`, `md_documentation_previous_versions/README-v0.md`. --- ## Pre-2026 — v3: Adoption of Fairfield & Charman as epistemological foundation **What changed**: Removed numerical probability fields (`prob_evidencia_dado_h`, `prob_evidencia_dado_nao_h`, `likelihood_ratio`, `forca_inferencial`) from `TB_EVIDENCIAS`. Replaced with qualitative Bayesian reasoning: `discriminacao_H_vs_rivals` (analytically primary field) and `hipotese_favorecida_id` (FK). Removed QualCoder fields. Added `url`, `arquivo_local`, `pagina_trecho` for passage-level auditability. **Why**: Fairfield & Charman (2022): "transparency does not require assigning numerical values to probabilities." The numerical fields suggested false precision. The new `discriminacao_H_vs_rivals` captures the inferential core — "mentally inhabiting the world of each hypothesis" — without it. **Key reference**: Fairfield & Charman (2017, §3.3.1). **Affected files**: `llm_conversations_database-development/xlsx_templates/banco_pt_process_tracing_v3.xlsx`. --- ## Pre-2026 — v3: Symmetry of hypotheses **What changed**: Removed `tipo_hipotese` (principal/alternativa) from `TB_HIPOTESES`. All hypotheses now have equal structural status. Added `justificativa_prior` for qualitative prior reasoning. Replaced `favorece_H_principal` with neutral `hipotese_favorecida_id` FK. **Why**: Fairfield & Charman require comparing rival hypotheses without privileging any as "the main hypothesis." The `justificativa_prior` field follows F&C (2017, §3.1): "We can specify priors that aim to reflect our background information as best as possible." **Affected files**: `llm_conversations_database-development/xlsx_templates/banco_pt_process_tracing_v3.xlsx`. --- ## Pre-2026 — v3: Van Evera tests retained with transparent tension **What changed**: `teste_bayesiano` field retained (Hoop, Smoking Gun, Straw-in-the-Wind, Doubly Decisive), but READ_ME tab rewritten to explain them as communicative vocabulary, not formal procedure — with explicit note on disagreement with Fairfield & Charman. **Why**: F&C argue these tests are unnecessary in a Bayesian framework (confirmation is degree, not type). This project retains the labels as communicative shorthand (Bennett 2015, Mahoney 2012) while declaring the tension openly. The `discriminacao_H_vs_rivals` field is analytically primary. **Affected files**: `llm_conversations_database-development/xlsx_templates/banco_pt_process_tracing_v3.xlsx` (READ_ME tab). --- ## 2026-05-23 — v4: Explaining-outcome redesign + numerical likelihoods reinstated **What changed**: Inside the Claude bayesian-tests conversation (`llm_conversations_database-development/conversations/2026-05-03_claude_bayesian-tests_v1-through-v4.md`), the schema was reorganized around three first-class concepts that v3 lacked: (a) `TB_EPISODIOS` — episodes as distinct causal stories with their own actors and counterfactuals (the project has three: PSDB / private sector, ProUni vs. Quotas Law, FIES expansion); (b) explicit rival accounts at the episode level, with partisan theories as foils to be falsified episode-by-episode; (c) a distinction between *diagnostic* evidence (showing the partisan mechanism does not operate) and *confirmatory* evidence (supporting the alternative). Simultaneously, the v3 deletion of numerical likelihoods was reversed: v4 reintroduced `p_num_h1`, `p_num_h2`, `razao_verossimilhanca`, `peso_db` (weight of evidence in decibels), and `peso_categoria` with conditional formatting — Fairfield & Charman's 2017 operationalization in full. The same day, the researcher caught Claude in an unrelated overstatement: the prior framing of Git-commit-before-fieldwork as "epistemological protection" was retracted as a theory-testing leftover, and reframed as audit-trail value only. **Why**: Even after v3 removed the explicit theory-testing framing, the schema still felt single-mechanism in use because it lacked an `EPISODIOS` table. The three-episode reorganization closed that gap. The decibel-weighting reintroduction was *not* requested — it was the LLM defaulting to its training-data-heavy F&C 2017 operationalization once given a redesign opening. See [`HISTORY.md`](HISTORY.md) §3.4 for the full analysis of this oscillation; [`METHODOLOGY.md`](METHODOLOGY.md) §8 documents this as a recurring AI-misalignment pattern. **Affected files**: `llm_conversations_database-development/xlsx_templates/v4_banco_process_tracing_baesiano_abdutivo.xlsx`; `llm_conversations_database-development/drafts/Genereted README_v2 about the database generation an objectives.qmd` (intermediate README reflecting the same v4 framing — carries a provenance note flagging it as pre-final). --- ## 2026-05-05 — v3: Adoption of Fairfield & Charman as epistemological foundation (This entry was previously listed as "Pre-2026". The actual date is 2026-05-05 — file mtime of `banco_pt_process_tracing_v3.xlsx`. Triggered by Q11 of the v1/v2 Perplexity session at 2026-05-05 12:02.) --- ## 2026-05-05 — v2: Schema normalization and fingerprint formalization **What changed**: Introduced normalized tables: `TB_HIPOTESES`, `TB_ETAPAS_MECANISMO`, `TB_FONTES`, `TB_FINGERPRINTS`. Added `fingerprint_esperado` field. Added `evidencia_presente` boolean. Added `TB_REVISOES` for audit trail. Added numerical probability fields (later removed in v3, then reinstated in v4 — see entry above and [`HISTORY.md`](HISTORY.md) §3.4). **Why**: The v1 flat structure could not answer relational queries ("which evidence supports M2 against H_alt1?"). Normalization enabled SQL JOINs and separated concerns. The `fingerprint_esperado` field formalized Beach & Pedersen's (2019) "core inferential logic": defining expected observable implications *before* evaluating whether they were found. **Affected files**: `llm_conversations_database-development/xlsx_templates/banco_pt_process_tracing_v2.xlsx`. --- ## 2026-05-03 — v1: Initial flat database schema **What changed**: Created first evidence database schema — flat structure with 16 fields: `id_evidencia`, `etapa_mecanismo`, `teste_bayesiano`, `direcao_evidencia`, `hipotese_alvo`, `confiabilidade_fonte`, among others. **Why**: Starting point based on Beach & Pedersen's (2019) theory-testing framework. Assumed a well-specified theory with identifiable fingerprints — an assumption relaxed in later versions as the project moved toward explaining-outcome abductive PT. Generated via Perplexity AI conversation (`claude46sonnetthinking` in COPILOT mode) at Q6 of the v1/v2 Perplexity session on 2026-05-03 at 09:04, after preceding literature-search questions Q1–Q5 starting 2026-05-02 at 23:09. **Affected files**: `llm_conversations_database-development/xlsx_templates/banco_pt_process_tracing.xlsx`; `llm_conversations_database-development/conversations/2026-05-02_perplexity_pt-literature-and-v1-v2-schema.md`.