Index to artifacts

Output of the research review defined in prompt.txt. Started 2026-10-02.

Three top-level folders: review/ holds one folder per project (what the agents write, Markdown and JSON); site/ is the generated HTML the reader uses and the only folder to publish; work/ holds working files that are not deliverables.

Each project folder review/{project}/ holds the same set of files:

File Step What it is
_text/ 0 Extracted text of every source document (tools/textprep.py): full text with page markers, OCR for scanned pages, audio/video transcripts, chunks/ for digesting, and manifest.json listing every document or why it was skipped.
digest/ 1a Haiku section-by-section summaries of every chunk: 1-3 sentences per 2-3 paragraphs, with page numbers. Summary, not evaluation.
deep/ 1b / QE Sonnet or Opus deep reads of documents that carry central claims, data or derivations, each answering a specific question.
facts.json 1 Catalogue of every source document: summary, key claims, how it was read, source tags.
claims.md 1 The project's central claims, one sentence each. Superseded by the corrected claim list in arbiter.md.
physicist.md 2 PhD physicist review: questions a-d and a verdict per claim, corrections to Step 1.
mathematician.md 2 PhD mathematician review: derivations, units, notation, hidden assumptions.
contrarian.md 2 Science Contrarian review: strongest honest case for the claims, how they were received, same rigour applied to the researcher.
arbiter.md 3 Reconciles the three reviews; final verdicts, corrected claim list, open questions, what would settle it.
primer.md 4 The study document, written for an undergraduate-level reader. Start here.
example.py 4 Runnable check of the primer's worked example. Run from altsci/: .venv/bin/python review/<project>/example.py.
qe.md 4b Quality engineering report: coverage, shortcuts, missed material, spot checks, verdict (PASS / MINOR / MAJOR), remediation and recheck.
sites.md I Investigator's running log of web sites searched: queries, positive/negative/partial/blocked results, recheck flags, keywords tried, leads for review.
research/ I Investigator's notes per site visit ({date}-{site}.md) and downloaded documents (files/). STEP F adds {date}-followup-Q{NN}.md, the research behind each follow-up answer.
followups.json F The owner's follow-up questions (Q{NN}, ids global across projects) and their answers (A{NN}): status; the answer as a short answer, Known / Inferred / Open lists, optional key equations and key points (supports / contradicts); sources and a link to the research notes. Shown in the project's card as "User follow-ups". Only present once a question has been asked. An answer may also carry a step-by-step procedure box (linking to its own page, research/{date}-followup-Q{NN}-procedure.md, required for how-to and experiment questions) and orchestrator Notes. Theme follow-ups use the same format in work/themes/followups/{theme}.json, shown in the theme's card; their notes are in work/themes/research/.

Shared

  • aaa-progress.md — current state, records the owner must obtain, next steps, and how to resume.
  • aaa-privacy.md — STEP P: the latest privacy review of the built site (owner privacy and source-document disclosure), with a history line per review. Local only: never rendered into site/.
  • aaa-index-to-artifacts.md — this file.

Site (site/, generated by STEP R; never edit by hand)

  • index.html — the latest Interesting Rankings run: one card per top-20 project ("Ranked Projects"), then the "Selected Projects" cards (from selected.json, alphabetical), then "Themes at a glance" with the "Ranked Themes" and "Selected Themes" cards (STEP 5c), in a fixed format; every card shows when it was last updated (each with a "User follow-ups" box from followups.json); every other ranked project is one line under "Other ranked projects"; what changed and the run history.
  • rankings/{date}-runNN.html — one page per rankings run, kept as history.
  • {project}/ — HTML of primer, arbiter, physicist, mathematician, contrarian, qe, sites and claims; sources.html (the facts.json catalogue, sortable); example.html and example.py; research/ (the Investigator's notes). Folder names with spaces are hyphenated.
  • artifacts.html, progress.html — these two shared files. overview.html once STEP 6 has run.
  • assets/ — the shared stylesheet and script (from tools/site_assets/).
  • Not published: _text/, digest/, deep/ and research/files/ (source documents and their extracted text).

Work (work/)

  • rankings/runs/{date}-runNN.json — STEP 5a: the ranking of every reviewed project for one run, with moves and what changed.
  • rankings/entries/{project}.json — STEP 5b: the current rank entry (card) of each ranked project.
  • rankings/selected.json — the owner's list of projects that always get a full card, shown under "Selected Projects" after the top 20.
  • themes/themes.json — the owner-curated theme list: id, name, scope, boundary, and which are the owner's Selected Themes.
  • themes/maps/{date}-mapNN.json — STEP 5c: theme membership (core or related projects) and the ranking of the Ranked Themes, one per run.
  • themes/entries/{id}.json — STEP 5c: the current card of each theme (timeline, core propositions and verdicts, people, key evidence, lineage, pitfalls).
  • themes/qe/{id}.md — STEP 5c: the Theme QE check of each card.
  • rankings/archive/{date}-runNN/ — the entries as they were for each run (written by STEP R), so earlier run pages can be rebuilt.
  • aaa-interesting-index.md — the last Markdown index (2026-10-04), the starting point for rankings run 01.
  • _merged/ — single-folder reviews superseded by a combined project (Kassner-EEW-Ternion and Ternion-Research, now TernionAG).
  • _pilot-v1/ — the first pilot run (Bearden, Heaviside, Maxwell, before the prompt fixes), kept for comparison.
  • _textprep.log — log of an early text-extraction run.
  • rankings-mockup.html, 2026-10-05-deliverable-format-design.md — the design of the HTML deliverables.

Tools and environment

  • tools/textprep.py — Step 0 text extraction (pdftotext, tesseract OCR, textutil, whisper; unpacks zip archives; several sources for a combined project).
  • tools/workflows/ — the Workflow scripts that run the pipeline (see aaa-progress.md); history/ holds superseded one-off run records.
  • tools/followups.py — STEP F: add PROJECT "question" (or add theme:ID "question") records a follow-up with the next Q id; open lists unresolved ones; check validates followups.json.
  • tools/render_site.py — STEP R: builds site/ and checks its links (--check FILE validates rankings data). tools/site_assets/ holds its stylesheet and script.
  • .venv/ — Python venv with sympy, numpy and markdown.