# 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`](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.