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:
@@ -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`.
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user