docs(meta): seal a blind prediction of the wiki seed structure before reading it
Written before opening wiki/, committed first so the prediction is timestamped and cannot be retrofitted once the answer is known. Contamination declared inline: paths already seen this session via generator_sources.py and visual_scenarios.gd are marked [SEEN] and discounted. Scoring rule fixed in advance, with 'load-bearing thing I did not know existed' as the bucket that decides what gets documented. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,132 @@
|
||||
# Blind prediction: how the wiki seed data is structured
|
||||
|
||||
**Written 2026-08-20, BEFORE opening `wiki/`.** Committed before the exploration
|
||||
pass so the prediction is timestamped and cannot be quietly retrofitted once the
|
||||
answer is known. The findings pass writes a separate document; this one is never
|
||||
edited after commit.
|
||||
|
||||
## Why this exists
|
||||
|
||||
To measure what a Claude session actually knows about the wiki seed data before
|
||||
it starts guessing. The value is the GAP, not the write-up: wrong beliefs predict
|
||||
where a future session burns a day, and "didn't know it existed" predicts it
|
||||
better than "got it wrong". Jeroen's framing (2026-08-20): misaligned conclusions
|
||||
I may already have drawn are themselves valid friction, so this is written as I
|
||||
actually believe it, contamination and all.
|
||||
|
||||
## Contamination declared
|
||||
|
||||
This is NOT a naive prediction. During this session I saw real wiki paths without
|
||||
opening any of them, via `tooling/generator_sources.py`, `visual_scenarios.gd`
|
||||
and CLAUDE.md. Claims resting on those are marked **[SEEN]** — they should be
|
||||
discounted as evidence of understanding. Everything else is inference and is
|
||||
marked with a confidence level.
|
||||
|
||||
## The claims
|
||||
|
||||
### 1. Location and role
|
||||
|
||||
- `wiki/` sits at the repo root, a sibling of `server/`, `client/`, `docs/`,
|
||||
`governance/`. **[SEEN]**
|
||||
- It is the AUTHORED source of world content — the "Phase 1 deliverable" CLAUDE.md
|
||||
describes ("Wiki content complete — all planets, moons, stations, heightmaps,
|
||||
artwork"). **High confidence.**
|
||||
- It is a source, never an output: things are generated FROM it into
|
||||
`server/data/systems.db`, and the asset-pipeline rule ("edit sources, not the
|
||||
DB") means the wiki is one of those sources. **High.**
|
||||
|
||||
### 2. Format
|
||||
|
||||
- Pages are **markdown with YAML frontmatter** — the frontmatter carries the
|
||||
machine-read fields, the body carries prose for humans and for in-game wiki/GTTR
|
||||
popups. **High**, because `import_economics` reads corp frontmatter **[SEEN]**
|
||||
and because `pql` is described as a markdown-vault query tool.
|
||||
- It is an **Obsidian-style vault**: `[[wikilinks]]` between pages, tags, and
|
||||
`pql backlinks`/`related`/`context` work over it. **Medium-high** — pql's vault
|
||||
surface exists and this repo is a pql repo, but I have not confirmed the wiki
|
||||
is the indexed vault rather than, say, `governance/`.
|
||||
- Alongside markdown there are **TOML data files** for tabular content that is
|
||||
awkward as prose — the economics vocabulary/bias tables. **[SEEN]**
|
||||
- And **JSON** for name pools (`markers.json`, names-only per D-223). **[SEEN]**
|
||||
|
||||
### 3. Directory shape (the least certain part)
|
||||
|
||||
Predicted top level:
|
||||
|
||||
```
|
||||
wiki/
|
||||
star-systems/<SYSTEM-ID>/ e.g. GJ-820B (hyphenated) [SEEN]
|
||||
bodies/<BODY-ID>/ e.g. GJ820Bc (NOT hyphenated) [SEEN]
|
||||
heightmap.png 1024x512 16-bit elevation [SEEN]
|
||||
reliefmap.png 1024x512 colour biome [SEEN]
|
||||
markers.json names-only city pool [SEEN]
|
||||
<body>.md the authored page (guess)
|
||||
corporations/*.md + index.md, skipped by the importer [SEEN]
|
||||
economics/*.toml vocabulary + bias tables [SEEN]
|
||||
```
|
||||
|
||||
- The system-vs-body id spelling differs (`GJ-820B` directory, `GJ820Bc` body).
|
||||
**[SEEN]**, and I flag it as a likely papercut: two spellings of the same
|
||||
identifier is exactly the kind of thing that costs an hour.
|
||||
- **Low confidence** on everything else: whether there are `factions/`,
|
||||
`stations/`, `technology/`, `history/`, `culture/` trees; whether bodies nest
|
||||
under systems or are flat; whether moons are bodies or a separate kind.
|
||||
- I would GUESS there are more content trees than the three I have seen, because
|
||||
Phase 1 covers "planets, moons, stations, heightmaps, artwork" and miri's
|
||||
worldbuilding brief covers factions/cultures/technology/history — none of which
|
||||
appear in the paths I have seen. **Medium.**
|
||||
|
||||
### 4. How it reaches the game
|
||||
|
||||
- One generator: `import_economics` (`make regen-db`), which shells out to
|
||||
`generate_brands` first, then reads the TOMLs, the corp pages' frontmatter, and
|
||||
the `markers.json` pool, and writes `systems.db`. **[SEEN]**
|
||||
- `systems.db` is a committed read-only snapshot the client ships with; the
|
||||
wiki is not read at runtime by the game. **High.**
|
||||
- The per-body PNGs are read by the SERVER at runtime (the cascade loads
|
||||
`heightmap.png` per body), not baked into systems.db. **High** — T-1213's work
|
||||
this session read reliefmap.png as the biome input, and heightmap paths resolve
|
||||
through a `BodySourceResolver`.
|
||||
- So there are TWO consumption paths and they behave differently: **TOML/markdown
|
||||
→ build-time → systems.db**, and **PNG → runtime → the cascade**. If that is
|
||||
right it is the most important structural fact here, and I do not think it is
|
||||
written down in one place. **Medium-high.**
|
||||
|
||||
### 5. What I expect to be load-bearing but under-documented
|
||||
|
||||
- Which frontmatter fields are READ versus decorative. My guess: a small set
|
||||
(`corp_specialization`, `headquarters`, `headquarters_body`) is load-bearing and
|
||||
most of the page is prose — so an author can add a field that looks meaningful
|
||||
and nothing consumes it. **Medium.**
|
||||
- The stamp coupling: editing a wiki page that the importer reads must flip the
|
||||
`import_economics` meta stamp, or the pre-push hook rejects. Authors of PROSE
|
||||
probably do not expect a content edit to require `make regen-db`. **High** —
|
||||
`_corporation_pages()` globs all corp pages into the stamped set, so editing
|
||||
any corp page's prose stales the DB even if the frontmatter did not change.
|
||||
I predict this is a real friction and possibly a real bug (prose-only edits
|
||||
forcing a regen).
|
||||
- Whether the wiki has a validation gate at all. I predict **no schema
|
||||
validation** beyond what the importer happens to require, so a typo'd
|
||||
frontmatter key fails silently or at regen time. **Medium.**
|
||||
|
||||
### 6. What I predict I will be wrong about
|
||||
|
||||
- The directory taxonomy — I expect several trees I have not guessed.
|
||||
- Whether bodies have their own markdown pages at all, or exist only as DB rows
|
||||
plus asset files.
|
||||
- The relationship between `wiki/` and `pql`'s vault indexing; I may be assuming
|
||||
an Obsidian vault that is really just a folder of files.
|
||||
- Whether stations/moons are modelled like planets or differently.
|
||||
|
||||
## Scoring rule, fixed in advance
|
||||
|
||||
Three buckets, and the third is the one that matters:
|
||||
|
||||
1. **Right** — claim confirmed.
|
||||
2. **Wrong** — claim contradicted. Cheap: I had a model and it was corrected.
|
||||
3. **Absent** — a load-bearing thing I did not know existed. Expensive: this is
|
||||
what a future session walks into blind, the same way `relief_q` falling off
|
||||
the wire cost eight days this month.
|
||||
|
||||
Artefacts get aimed at bucket 3 first, then at bucket 2 where the existing docs
|
||||
are actively WRONG rather than merely missing.
|
||||
Reference in New Issue
Block a user