docs(meta): fork-for-sidequests rule + wiki skill corrections from the cold test

The cold test worked as an experiment: a fresh agent with Skill(wiki) cited it first, refused to hand-edit body frontmatter, knew the corp regen-db stamp trap, and knew corp_specialization is missing from its own template. It also found four things the skill had wrong or missing, all verified before folding in: body frontmatter is a MIDDLE layer (atlas CLI -> systems.db -> scaffold writes the page -> import_economics reads it back), not the origin GOVERNANCE.md implies; the four empty categories are Q-118, an open scope question rather than an invitation; some bodies are visual-regression goldens and nothing in wiki/ says so; and status is editorial, not an import gate. Also: check current state before editing, since the test's own task described a change that was already true.

T-1244 corrected in the same pass — tectonics is derived from planet_class via a lookup (body_definition_parser.py:563), so the measured 68% 'low' is a projection of the class distribution, not an authoring choice. The ticket's question changed accordingly.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-20 00:46:04 +02:00
co-authored by Claude Opus 5
parent 9fb74bdf22
commit 0dc68dc1b8
4 changed files with 151 additions and 3 deletions
+50
View File
@@ -0,0 +1,50 @@
# Fork for side quests
A side quest is work that is worth doing but is not the task in hand: filing a
ticket, writing up a finding, chasing a tangent, a docs pass. Doing it inline
costs the main thread its context — which is why forward intent tends to go
unrecorded at all (T-1245).
**Default: fork it.** Spawn an agent from the frozen context, keep working.
## Fork when
- Writing or appending a ticket, especially a long one.
- Recording a finding that is real but off the current path.
- An investigation whose ANSWER matters but whose SEARCH does not — "does X
exist", "who else calls this", "is this documented anywhere".
- Anything you catch yourself deferring with "I'll note that later". Later is
where notes die.
## Do NOT fork when
- It is on the critical path — if the current task blocks on the answer, do it
inline and keep the reasoning visible.
- It needs a judgement only the lead has context for (a design call, a trade-off
the user has been steering).
- It is one command. A fork costs more than the work.
## The report contract — required, and brief
Every fork returns exactly this, in this order. Long reports defeat the purpose;
the lead is mid-task.
1. **STATUS** — one line: done / blocked / partial, and the outcome.
2. **FILES TOUCHED** — every path created or modified, or `none`. This is not
optional. The lead has to know what is in the working tree before staging,
and an unreported edit turns into a mystery diff at commit time.
3. **ISSUES** — anything found that is wrong, missing or surprising. One line
each. `none` is a valid and welcome answer.
4. **FRICTION** — what was hard to find, misleading, or only found by luck. This
is the docs/skills feedback loop; a fork that hit a wall silently wastes the
evidence.
## Git discipline
Forks do not commit. `.claude/hooks/git-centralize-guard.sh` already blocks
`.git`-mutating commands for teammates, so this is enforced rather than trusted —
but the FILES TOUCHED line is what makes it workable, because the lead is the one
who stages and has to know what changed and why.
If a fork's work should not land in this branch at all, say so in STATUS rather
than leaving the lead to discover it in `git status`.
+43 -3
View File
@@ -32,8 +32,24 @@ atlas sync alongside.
**Never hand-edit:**
- anything inside a `<!-- READ-ONLY -->` block (System Profile, Topology,
Celestial Bodies, Stations & Facilities)
- `bodies/*/index.md` frontmatter — it IS the body definition and it is
machine-owned
- `bodies/*/index.md` frontmatter — machine-owned
**Body frontmatter is a MIDDLE layer, not the origin.** GOVERNANCE.md calls it
"the body definition", which is true of its role downstream and misleading about
where it comes from. Actually:
1. The bodies catalog in `server/data/systems.db` is the origin, authored through
the atlas CLI (`tooling/atlas add-body` / `author-system`) — atlas-CLI-owned
and surviving `make regen-db` (`Skill(atlas)`).
2. `scaffold_bodies.py` + `body_definition_parser.py` WRITE the page frontmatter
from that, deriving fields as they go — e.g. `tectonics` is a lookup off
`planet_class` (`body_definition_parser.py:563`), with an override hook, not
an independently authored value.
3. `import_economics` then READS some of those fields back.
So it is output of one stage and input to the next, which is exactly why hand
edits are both reverted AND wrong. To change a body's identity, go to the atlas
CLI, not the page.
**Do author**, in place, and it survives regeneration:
- the named prose sections of a system page: Supply Dependency, Faction Notes,
@@ -58,7 +74,14 @@ empty scaffolding:
| `technology/` | 7 | |
| `contraband/`, `concepts/` | 4 each | |
| `triangles/` | 2 | relationship structures |
| `institutions/`, `species/`, `cultural-groups/`, `lore/` | **0** | templates exist, no content yet |
| `institutions/`, `species/`, `cultural-groups/`, `lore/` | **0** | templates exist — but see Q-118 |
**Those four empty categories are an OPEN QUESTION, not an invitation.**
`governance/questions/scope.md` Q-118 (2026-06-12, unresolved) asks whether they
should be populated at all or retired: Phase 1 closed as done without them,
because the cultural layer shipped structurally instead (D-232 trait catalog +
D-237 system pins as TOML). Surface Q-118 before authoring into them — the
template's existence is not scope approval.
To add one: copy the matching `_templates/` file, fill ALL frontmatter, write a
one-line `description`, set `status: proposed`, follow the template's structure.
@@ -115,6 +138,23 @@ source set, so a typo fix in body text trips the pre-push stamp check. Run
before loading full files". Read frontmatter descriptions and load selectively —
this tree is 11,864 files and will eat a context window whole.
**Check the current state before editing anything.** A task can describe a change
that is already true. Ferrath was asked to be made "arid with low tectonics" and
already was, in all four places it is recorded — acting on the framing would have
hand-edited a machine-owned, already-correct file. Read the target first; the
rules below only protect you if you look before you touch.
**Some bodies are visual-regression goldens.** Ferrath (`GJ820Bc`) appears in
`tests/visual.json` and `tests/atlas_shots.json` (Global, District, and the
descent-ladder set) precisely because of its current terrain. Regenerating its
terrain is legitimate under every rule here and will silently break goldens —
re-capture them if you do. Nothing in `wiki/` says so; check `tests/` for the
body id before regenerating any body.
**`status` is editorial, not a gate.** `import_economics` has no status filter,
so a `proposed` corp imports into the live economy exactly like a `canonical`
one. Do not assume `proposed` means inert.
**Absent variance is often deliberate.** Fields can be forward-reservations or
staged gates, not gaps. `chemosynthetic: false` on every body reserves the
namespace for dextro-DNA-style biochemistry once geology and nature spawn to the