REPOSITORY PLAN — Design Rationale and Organization

This document records why the repository is organized the way it is, what problems the current structure solves, and what decisions were made during the 2026-05-26 reorganization.

1. Central Purpose

This repository is a methodological development project. Its intellectual product is the database schema design for abductive process tracing — not the data that populates it.

The templates in llm_conversations_database-development/xlsx_templates/ represent successive attempts to answer: given imperfect theories, how should evidence be structured for Inference to the Best Explanation? Each version embodies a design decision documented in NEWS.md. The v7 working database at root is a live test of the current schema with real data, not the final research deliverable.

2. Problems Diagnosed Before Reorganization

# Problem Solution applied
1 README.md referenced METHODOLOGY.md and NEWS.md, but neither existed Created both files
2 README framed the repo as a research data project Rewritten to reflect methodological development purpose
3 No documentation versioning Created md_documentation_previous_versions/ with README-v0.md; future doc versions go here
4 Design reasoning was trapped inside conversation logs, not synthesized Created METHODOLOGY.md (living synthesis) and NEWS.md (decision log)

3. Current Structure (post-reorganization, 2026-05-26 evening)

process-tracing-database-design/
├── README.md                               <- project overview
├── NEWS.md                                 <- methodological decision log
├── METHODOLOGY.md                          <- epistemological premises (living document)
├── HISTORY.md                              <- narrative chronology of database evolution
├── REPOSITORY_PLAN.md                      <- this file (organization rationale)
├── process-tracing-database-design.Rproj
│
├── md_documentation_previous_versions/      <- archived documentation versions
│   ├── README-v0.md, README-v1.md
│   ├── NEWS-v0.md
│   ├── METHODOLOGY-v0.md
│   └── REPOSITORY_PLAN-v0.md
│
├── llm_conversations_database-development/ <- AI conversations, references, templates, drafts
│   ├── README.md                            (folder-level guide)
│   ├── conversations/                       (LLM conversation exports + rename-suggestions.md)
│   ├── references/                          (methodological reading — PDFs)
│   ├── xlsx_templates/                      (successive abstract schemas v1–v4)
│   └── drafts/                              (intermediate outputs from conversations)
│
├── Database Process Tracing...xlsx         <- populated database
└── v7_banco_...xlsx                        <- live working database (DO NOT RENAME)

4. What Was NOT Changed (and why)

Item Reason for keeping as-is
v7_banco_process_tracing_baesiano_abdutivo_manual.xlsx Active working database — researcher’s explicit instruction not to touch
Database Process Tracing Reforming Tertiary Education.xlxs.xlsx Populated database, kept at root for quick access
All .xlsx template files Original naming preserves version lineage
Conversation .md files inside llm_conversations_database-development/conversations/ Original export names preserved by researcher’s request; rename proposals tracked in conversations/rename-suggestions.md
Templates/ removed at root Replaced by llm_conversations_database-development/xlsx_templates/ (typo xlxs fixed during evening reorganization)
Reference PDFs renamed Normalized from mixed conventions to Authors-Year_Short-Title.pdf during evening reorganization

5. Naming Conventions Going Forward

Item Convention Example
Root-level documentation UPPERCASE .md README.md, NEWS.md, METHODOLOGY.md, HISTORY.md
Directories lowercase, no spaces md_documentation_previous_versions/, conversations/, references/, xlsx_templates/, drafts/
Reference PDFs Authors-Year_Short-Title.pdf Fairfield-Charman-2022_Social-Inquiry-Bayesian-Inference.pdf
R scripts (future) snake_case xlsx_to_sqlite.R
Documentation versions {FILENAME}-v{N}.md in md_documentation_previous_versions/ README-v0.md, NEWS-v0.md

6. Documentation Versioning Strategy

When a major revision is made to README.md, NEWS.md, or METHODOLOGY.md:

  1. Copy the current version to md_documentation_previous_versions/ with a version suffix (e.g., METHODOLOGY-v0.md)
  2. Make the revision in the root file
  3. Add an entry to NEWS.md explaining what changed and why

Git tracks line-level diffs automatically, but md_documentation_previous_versions/ provides snapshot-level preservation — useful for seeing the document as a coherent whole at each stage.

7. Relationship Between Documentation Files

README.md          — "What is this?"            → entry point, points to all other docs
METHODOLOGY.md     — "What do we believe?"      → epistemological premises (living document)
NEWS.md            — "What changed and when?"   → structured design decision log
HISTORY.md         — "How did we get here?"     → narrative chronology with lessons learned
REPOSITORY_PLAN.md — "Why is it organized?"     → this file (meta-documentation)

NEWS.md and HISTORY.md are companions: NEWS is the decision log (date-keyed, structured: what / why / affected files), HISTORY is the narrative (story of dead ends, methodological reversals, what each iteration learned). A reader who wants facts about a specific change reads NEWS; a reader who wants to understand the arc reads HISTORY.

Back to top