UFOpedia

Reference

Conventions & Methodology

Conventions & Methodology

How this knowledge base is structured, sourced, and how credibility is rated. This page is the reference for anyone reading the repo or contributing to it. If you only read one thing, read The credibility framework.

The governing principle of the whole project: separate verified facts from unverified claims, and make the basis for every credibility judgment explicit. Testimony is recorded as testimony, primary documents as primary documents, and the gap between "someone said this" and "this is established" is never silently collapsed.

Directory structure

DirectoryWhat lives hereAnalytical level
sources/Source-of-record files — one analytical writeup per person, program, document, event, or report. The curated, interpreted layer.High (synthesis + judgment)
topics/Cross-cutting analyses that connect multiple sources — patterns, debates, timelines, the credibility framework itself.High (synthesis across sources)
raw/Primary material, captured verbatim. Subdivided by medium (below). The evidentiary substrate that sources/ and topics/ cite.Low (capture + light framing)
queries/Dated question-answer notes — a specific question worked through against the sources at a point in time (e.g. "how good was the AARO report?"). Named YYYY-MM-DD-slug.md.Medium (focused reasoning)
scratch/Working notes, audits, in-progress lists not meant for the published site.n/a
scripts/Triage tooling (e.g. the Reddit triage.py).n/a

raw/ subdirectories

SubdirContents
raw/articles/News articles, blog posts, Wikipedia captures, web pages (extracted to markdown)
raw/transcripts/Podcast / YouTube / video transcripts (with timestamps where available)
raw/reports/Government reports, FOIA productions, hearing transcripts, declassified PDFs (+ extracted text)
raw/reddit/Reddit post + comment captures (JSON + analytical markdown), plus the triage DB
raw/papers/Academic / self-published papers (PDF + extracted text)
raw/extracts/Standalone primary extracts saved with the extract tools
raw/data/Datasets (CSV, structured data)
raw/media/Images and other media

The three-layer model

The repo distinguishes three altitudes, and the distinction is load-bearing:

  1. raw/ — what was said/written. Verbatim capture. A transcript, an article, a PDF's text. No judgment beyond a header documenting provenance. When you source something new, the raw extract is saved here even if you also write it up in sources/ — the raw layer is not optional.

  2. sources/ — what a specific person/program/document is and how much weight it carries. One file per entity. Synthesizes the raw material about that entity and renders an explicit credibility judgment.

  3. topics/ — what the sources mean together. Patterns across entities: the credibility framework, the 2017 watershed, the amnesty debate, the contactee tradition, etc.

A claim should be traceable downward: a topics/ assertion cites sources/ files, which cite raw/ primaries. Don't let a sources/ or topics/ claim float without a raw/ anchor.

Copyright posture. Third-party material is captured in full, verbatim, in raw/, with a provenance header and attribution (an archival/fair-use posture). This is the default — there is no longer a "summary-only because copyrighted" tier. content/private/ (gitignored + Quartz-excluded) is not the default home for copyrighted text anymore; it is reserved for the few highest-risk items only — e.g. the full text of an in-copyright book. The detailed publishing policy is being defined separately.

File header convention

Every sources/ file opens with a record_types: frontmatter block (for record-kind identification - see below) followed by a metadata block:

---
record_types: [person]
---

# <Title>

- Type: <testimony | report | article | named-figure source-of-record | ...>
- Author / Subject: <who>
- Date: <ISO dates; incident vs. publication distinguished>
- Credibility: <rating — see framework below>
- <primary URLs, archive links, related wikilinks>

raw/ files open with a lighter header documenting provenance: source URL, date, author/outlet, extraction method (e.g. pymupdf4llm, Gemini CLI OCR, requests+readability), date sourced, and [[wikilinks]] to the analytical files that cite it.

Record types

Every sources/ file carries a record_types: frontmatter line classifying what kind of record it contains. Zola generates a browsable index page per type (for example, /record-types/person/ lists every person record). This is the canonical way to identify people and other record kinds in the source tree, and the public browse facet for them.

Record type is not the canonical identity of a source record. A source keeps one stable, reviewed human slug at /source/<slug>/. Its types provide readable convenience aliases such as /person/<slug>/ or /event/<slug>/, and a record with more than one type may have more than one such alias. Old descriptive singular and plural URLs remain redirects to the canonical source route.

Zola emits a no-JavaScript static alias page as a portable fallback. Every production compatibility alias must also have a matching 301 rule in static/_redirects; canonical pages must link directly to the source route, never through an alias.

Controlled vocabulary (one or more per file):

TagUse forCount
personAn individual whose claims/credibility are the subject18
reportGovernment/official reports3
documentArticles, compilations, leaked documents, papers3
mediaFilms, video evidence, fiction3
caseA specific sighting/incident3
organizationAn entity/archive/group2
lawLegislation2
eventA hearing or discrete happening2
programA government program1

A file may carry more than one when it genuinely spans kinds (e.g. [person, case] for Fravor/Nimitz, [person, organization] for Graves/ASA). When adding a new source, tag it before anything else — it is the entity's primary classification.

The credibility framework

This is the spine of the project. Full role-grouped roster lives in topics/community-credibility-assessment; the conventions for applying it are here.

The scale

Ratings are ~0–100, expressed with a tilde (~35) to signal they are judgments, not measurements. Rough bands:

BandMeaningExample
~70–85Credentialed insiders / operators making narrow, testable, institutionally costly claimsGallaudet (~75), Mellon (~72)
~50–70Real credentials or real access, but advocacy posture or unverified specificsGrusch (~50), Coulthart (~45)
~30–50Mixed: real background, but pattern of low-evidence or escalating claimsElizondo (~35), Davis (~30)
~10–30Discredited or fabulist, or claims with no falsification mechanismDoty (~25), Greer (~10)
~0–10Fabricated biography / fantasistSchneider (~5)

The core principle

People making the narrowest, most testable, most institutionally costly claims are the most credible. People making the broadest, most narrative-shaped, most career-aligned claims are the least.

A claim's evidentiary weight scales with the claimant's willingness to substantiate it. Withholding ("I know things I can't share") is a credibility-deferring move, not a credibility-enhancing one.

Where the rating lives

The numerical rating lives in the entity's own sources/ file (in the front-matter Credibility: field and/or a ## Credibility section), and every source with the person record type must also appear in the topics/community-credibility-assessment roster - as a roster entry and in the at-a-glance index. The roster is the full set of rated people, not a curated subset.

This invariant is enforced at build time. scripts/check-person-ratings.mjs (wired into npm run build, deploy, and check via check:content) scans every person record under content/sources/ and fails the build if any is not wikilinked from the roster. So a newly-added person page that hasn't been rated-and-rostered will block deployment. (Roster entries that have no source page - e.g. Lacatski, Doty, politicians - are fine; the check only runs source-page to roster, never the reverse.)

Build-time content gates

The site keeps one project-specific editorial check before every build/deploy and in check:

  • check:roster — the credibility-roster invariant above.

Zola is the sole internal-link authority. Its source-aware resolver and [link_checker] policy in zola.toml fail the native build on unresolved internal links. Deliberate forward links belong in allowed_missing_wikilinks; do not add a second JavaScript resolver.

The ## Credibility assessment section format

Match this structure (see sources/davis-career-and-claims and sources/buchanan-stargate-career-and-claims for worked examples):

  1. What raises X's credibility — numbered list
  2. What lowers X's credibility — numbered list
  3. Net assessment — the numerical rating + one-paragraph justification
  4. Position relative to other UAP figures — above/below comparisons to anchor the number
  5. Role-category placement — which category from topics/community-credibility-assessment applies

Bimodal / component ratings

When credibility varies dramatically by claim, a single number is misleading — break it down by component. This is the strongly preferred treatment for split-track-record figures.

The composite number is a convenience; the component breakdown is the honest representation.

Ratings move

Ratings carry their history when they change: ~42, down from ~48, originally ~55 (Kirkpatrick). Record the direction and the trigger for the update.

Sourcing workflow

Capture every relevant high-quality source that materially bears on the subject. This includes
primary, secondary, secondhand, and contested material. Preserve its provenance and state its
reliability limits rather than excluding it merely because it is not a pure primary.

  1. Resolve the primary. For Reddit share links, resolve to the canonical post; for videos, get channel + title + date; for paywalled/blocked pages, use the current extraction routes in /code/extract/MD_EXTRACT.md and /code/extract/PDF_EXTRACT.md. Use agy for image-scanned PDFs and manual capture only as a last resort.
  2. Save the raw extract into the appropriate raw/ subdir, with a provenance header. Do this even when you also write an analytical file — the rule is that the raw version is saved with the extract tools, not just embedded inside the writeup.
  3. Write or update the analytical file in sources/ (entity) or augment a topics/ file (pattern).
  4. Cross-link both directions — the raw/ file links up to its analytical writeup; the analytical file links down to the primary.
  5. Flag followup items — list under-sourced threads explicitly (a ## Followup items section) rather than silently dropping them.
  6. Pull cited primaries. If a source references peer-reviewed work, pull the actual arXiv/journal primary, not just the secondary characterization.

Full-workup checklist

A "full workup" on a figure/case (do full workup on X) has a recurring failure mode: the rated page gets written but a process step is silently skipped. To prevent that, run this checklist and report the filled-out version at the end of every workup (compact [x] done / [!] skipped — why / [n/a]), so any gap is visible rather than assumed-done. Items 1-5 are the general sourcing workflow above (and apply to plain "source this" too); 6-10 are workup-specific.

  1. Scope — grep existing base coverage; note what's already there and what's net-new.
  2. New sources — actively search for NEW high-quality sources (primary AND secondary); do not just synthesize from base material.
  3. Full raw + verify — capture the actual primary of the load-bearing claim (not a downstream restatement) in full, with a provenance header; verify the facts the rating hinges on (dates, chronology, titles) before asserting them.
  4. Claim integrity — check whether the claim's wording changed across restatements; hardening (open question → flat assertion) or softening is itself a finding to record.
  5. Cross-link — raw/ ↔ page both directions, plus first-occurrence wikilinks to related pages.
  6. Rated page — sources/ page with an explicit, reasoned credibility number; use a component/bimodal breakdown when credibility varies by claim type; anchor with position-relative-to-peers.
  7. Roster - for person records, add both the at-a-glance index line and a paragraph entry in topics/community-credibility-assessment; record rating history if it moved. Other record types don't need the roster.
  8. Followup items — a ## Followup items section listing under-sourced threads and unverified attributions, not silently dropped.
  9. House style — no bold/italics in new prose; plain provenance headers.
  10. Gates — prettier --write → npm run check:content (roster + links) → build pass; commit/deploy only when explicitly asked.

Filing queries

When a substantive analytical or credibility question is worked through against the base (not a quick factual lookup), file the reasoning as a dated note in queries/, named YYYY-MM-DD-slug.md — do not leave it only as a chat answer. Match the existing format: a # Question title, an intro line with the filed date and [[wikilinks]] to the sources/raw it draws on, a ## Short answer, body sections, and a ## Net. Then run the same prettier + check:content + build gates as any other content change. A quick fact lookup or a process/meta question does not need a query file.

Editorial guardrails

  • Answer the question actually asked. Do not add rebuttals to claims the user did not make.
  • Do not infer motive or intent from an evidential gap. State what the record supports, then label
    any psychological explanation as inference.
  • Do not turn a documentary claim into manufactured consensus. Attribute disputed positions to the
    people or camps that hold them.
  • Unconfirmed or unestablished does not mean false. Do not use a tidy “X, not Y” construction unless
    the evidence rules Y out.
  • Check every summary and net-assessment sentence against the body. Remove any rhetorical flourish
    that claims more than the evidence supports.
  • Keep build, generation, and other “how the sausage is made” notes out of published content. Raw
    provenance headers remain required because they document the source rather than the site’s build
    process.

Reddit triage

Triage is a production workflow, not a classification workflow: when triaging posts, source the relevant followup items and update/add topics in the same session, rather than only marking posts reviewed. Status values: untriaged | reviewed | followup | sourced.

  • Internal links use [[path/to/file]] or [[path/to/file|display text]] (Quartz/Obsidian style, no .md).
  • A [[link]] to a not-yet-created file is acceptable; it marks something worth writing.
  • Do not put an aliased wikilink such as [[target|alias]] in a Markdown table cell. Its pipe
    conflicts with the table delimiter: escaping the pipe breaks link resolution, while leaving it
    unescaped lets Prettier corrupt the table. Use plain text or an unaliased [[target]] in the cell,
    and place any aliased link in surrounding prose.

Follow Wikipedia's linking discipline (MOS:DUPLINK + MOS:OVERLINK + WP:SEEALSO):

  1. First-occurrence inline linking. Link the first prose mention of a relevantly-related entity (any figure/program/event/document with a page), inline, in the body — even if the current page isn't about it. Subsequent mentions of the same entity stay plain text. One link per entity per page (front-matter, headers, and a final Related list don't count toward the prose link).
  2. Relevant, not just central. Link an entity that's genuinely relevant in context, not only the page's main subject — but not loose/trivial co-mentions (a name dropped purely for contrast). "Discussed here" → link; "named in passing as a contrast" → skip.
  3. Don't over-link. No linking the same entity on every mention; no linking trivially-related items.
  4. Related / "See also" is curated and non-duplicative. The trailing ## Related list is for pages not already linked inline in the body (primaries the page cites, sibling pages worth surfacing). If an entity is linked inline, it should not also appear in Related.

In short: inline-link the first relevant mention once; keep Related for what the prose didn't already reach. Avoid the surname-collision trap when applying this (e.g. Harry Reid vs. Garry Reid; Eric Davis vs. other Davises) — match the specific person, not the bare surname.

Homepage and index

  • index.md (lowercase) is the Quartz site homepage (has the title: front-matter). Keep its curated entry-point links current.
  • There is no separate hand-maintained index file. The de-facto master index is the build-gated credibility roster (every [person] page must appear there). A stale INDEX.md was retired; do not reintroduce a manual sources-by-category list — it can't keep pace with the corpus.

What this base does NOT do

  • It does not collapse testimony into fact.
  • It does not present a single credibility number where the claim-by-claim reality is bimodal.
  • It does not treat aggregation of testimony as physical evidence (cf. the Age of Disclosure "34 named officials" analysis in topics/community-credibility-assessment).
  • It does not silently truncate coverage — if something is partially sourced or a gap remains, that is stated (see the "Coverage audit" section of topics/community-credibility-assessment).
Backlinks (2)