jpmschweitzer/settled-reach
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(meta): record the mechanism behind the roadmap gap on T-1245

Browse Source 
Jeroen: 'I tend to restrict future side quests to not confuse your context.' A reasonable practice with a bad side effect — intent stays conversational and reaches the repo by accident. Resolution recorded as two channels rather than more sharing: working context stays narrow, forward intent gets FILED. Carries a design constraint into the initiative's form investigation — weight options by cost-to-APPEND, since these facts surface mid-bug and a ritual will not get used.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-08-20 00:40:21 +02:00
co-authored by Claude Opus 5
parent 4de90529ae
commit 9fb74bdf22
2 changed files with 356 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.pql/changelog/ticket_history/2026-08.sql
+227
View File
@@ -869,3 +869,230 @@ ACCEPTANCE — the artefact earns its keep if:
RELATED: D-166 (cascade order), T-745 (the cascade initiative), and this
session''s docs/wiki-structure-findings.md, whose root-cause finding was the same
shape — the information existed and nothing pointed at it.', NULL, '2026-08-19 22:38:30', '2026-08-19 22:38:30.455', '2026-08-19 22:38:30.455', NULL, '7df91010f7424dc9077d495186872d27', 2) ON CONFLICT(hash) DO NOTHING;
INSERT INTO ticket_history (ticket_record_id, field, old_value, new_value, changed_by, changed_at, created_at, updated_at, deleted_at, hash, canonical_version) VALUES ('06G1RB7GSJA4379EAQDZPQQDN8', 'description', 'The project has a work breakdown and calls it a roadmap. The cascade owns ORDER, the ticket tree owns DECOMPOSITION, the DQR tree owns individual RULINGS — and none of them answer what the game is going to be, what the big unsolved problems are, or what is deliberately deferred. Pick-up instructions are in the appended body: the first pass is harvest/interview/investigate-form/propose-with-options, and EPICS ARE AN OUTPUT of that pass, not an input. Do not open this by inventing an epic list.
---
WHY THIS EXISTS
The project has a work breakdown and calls it a roadmap. It is not one.
What exists today, and what each is good at:
- The Development Cascade (T-745 -> six phase epics, D-166): strict ORDER. It
says what must be finished before what, and it is enforced. It does not say
what the thing being built is, or why a phase is worth its cost.
- The ticket tree (initiative/epic/story/task): decomposition of work already
decided on. It answers "what is left in this batch", never "is this batch the
right thing".
- The DQR tree (governance/decisions|questions|rejected): individual rulings with
rationale, each excellent in isolation. 260+ D-records do not compose into a
direction; a reader can know every decision and still not know where the game
is going.
- Briefings, workshops, discussions: rich, but point-in-time and per-agent.
None of these answer the questions someone actually asks about a roadmap: what is
this game going to BE, what are the big unsolved problems between here and that,
in what order do they unlock each other, what does "done" look like for each, and
what is deliberately not being solved yet.
THE EVIDENCE THAT THIS IS A REAL GAP, not a tidiness urge:
On 2026-08-20, in one conversation, three roadmap-level facts surfaced that exist
in NO artefact in this repo:
1. The economics tree is not just trade-sim data — once geology and nature
spawn to the 1x1 m pixel, the economics information GENERATES WORLD CONTENT.
Production chains decide what is physically on the ground.
2. `chemosynthetic: false` on every body is a namespace RESERVATION for
dextro-DNA-style biochemistry at that same future tier — not a dead field.
3. `enabled: false` on ~65% of bodies is staged rollout: learn the clean planet
types first, then add generator scripts for the other types and the playable
count rises.
Two of those three were written up as suspected DEFECTS by an agent reading the
repo carefully, because nothing recorded them as intent. That is the cost, and it
recurs: the roadmap lives in one person''s head and leaks out only when someone
happens to ask the right question.
WHAT THIS INITIATIVE IS FOR
Produce a roadmap artefact that carries INTENT and SHAPE, in a form that survives
being read by someone (or something) with no memory of the conversations that
produced it — and that stays honest as the project moves.
Explicitly NOT: another ticket hierarchy, a Gantt chart, dates, or a restatement
of the cascade. The cascade already owns order; this owns meaning.
HOW TO PICK THIS UP — READ THIS BEFORE CREATING ANY EPICS
The first work is INVESTIGATION AND PLANNING, not implementation, and not
epic-cutting. Do not open this initiative by inventing a list of epics; the epic
list is an OUTPUT of the first pass, not an input to it. Sequence:
1. HARVEST. Mine what already exists for roadmap-shaped content that was never
collected: docs/workshops/, docs/discussions/, docs/design/, the briefings,
the D-records'' "why" sections, the phase-epic descriptions, and the
conversational hints that only appear in commit messages and ticket notes.
Expect the good material to exist and be scattered — this project documents
heavily. The gap is composition, not absence.
2. INTERVIEW. Whatever the harvest cannot answer, ask Jeroen — directly and in
batches. The three facts above emerged from ordinary questions; assume more
are waiting behind questions nobody has asked. Record the answers as they
are given, before interpreting them.
3. INVESTIGATE FORM. Do not assume markdown-in-docs/ is right. Options worth
weighing: a single narrative document; a per-phase "what this buys and why"
layer attached to the existing phase epics; a D-record class for direction
rather than decisions; something queryable through pql alongside the DQR
tree; a visual map. Judge each against the failure mode this exists to
prevent — a reader who knows every decision and still cannot state the
direction — and against staying current without ceremony.
4. PROPOSE, WITH OPTIONS. Bring 2-3 concrete shapes with trade-offs and a
recommendation. This is a design decision about the project''s own memory;
it deserves a D-record and Jeroen''s ruling, not an agent''s unilateral pick.
5. ONLY THEN CUT EPICS, against the chosen shape and what the harvest showed is
missing. Epics come last because the work is unknown until steps 1-4 have
run.
ACCEPTANCE — the artefact earns its keep if:
- A fresh session can read it and state, without asking, what the game is
trying to be and what the next three big problems are.
- Facts of the kind listed above (forward reservations, staged gates, "this
system is really for that future thing") have an obvious home, so the next
one gets written down instead of surfacing years later in a chat.
- It is cheap enough to keep current that it actually gets updated. A roadmap
that rots is worse than none, because it lies with authority.
- It does not duplicate the cascade, the ticket tree, or the DQR records. If a
section restates any of those, it belongs there instead.
RELATED: D-166 (cascade order), T-745 (the cascade initiative), and this
session''s docs/wiki-structure-findings.md, whose root-cause finding was the same
shape — the information existed and nothing pointed at it.', 'The project has a work breakdown and calls it a roadmap. The cascade owns ORDER, the ticket tree owns DECOMPOSITION, the DQR tree owns individual RULINGS — and none of them answer what the game is going to be, what the big unsolved problems are, or what is deliberately deferred. Pick-up instructions are in the appended body: the first pass is harvest/interview/investigate-form/propose-with-options, and EPICS ARE AN OUTPUT of that pass, not an input. Do not open this by inventing an epic list.
---
WHY THIS EXISTS
The project has a work breakdown and calls it a roadmap. It is not one.
What exists today, and what each is good at:
- The Development Cascade (T-745 -> six phase epics, D-166): strict ORDER. It
says what must be finished before what, and it is enforced. It does not say
what the thing being built is, or why a phase is worth its cost.
- The ticket tree (initiative/epic/story/task): decomposition of work already
decided on. It answers "what is left in this batch", never "is this batch the
right thing".
- The DQR tree (governance/decisions|questions|rejected): individual rulings with
rationale, each excellent in isolation. 260+ D-records do not compose into a
direction; a reader can know every decision and still not know where the game
is going.
- Briefings, workshops, discussions: rich, but point-in-time and per-agent.
None of these answer the questions someone actually asks about a roadmap: what is
this game going to BE, what are the big unsolved problems between here and that,
in what order do they unlock each other, what does "done" look like for each, and
what is deliberately not being solved yet.
THE EVIDENCE THAT THIS IS A REAL GAP, not a tidiness urge:
On 2026-08-20, in one conversation, three roadmap-level facts surfaced that exist
in NO artefact in this repo:
1. The economics tree is not just trade-sim data — once geology and nature
spawn to the 1x1 m pixel, the economics information GENERATES WORLD CONTENT.
Production chains decide what is physically on the ground.
2. `chemosynthetic: false` on every body is a namespace RESERVATION for
dextro-DNA-style biochemistry at that same future tier — not a dead field.
3. `enabled: false` on ~65% of bodies is staged rollout: learn the clean planet
types first, then add generator scripts for the other types and the playable
count rises.
Two of those three were written up as suspected DEFECTS by an agent reading the
repo carefully, because nothing recorded them as intent. That is the cost, and it
recurs: the roadmap lives in one person''s head and leaks out only when someone
happens to ask the right question.
WHAT THIS INITIATIVE IS FOR
Produce a roadmap artefact that carries INTENT and SHAPE, in a form that survives
being read by someone (or something) with no memory of the conversations that
produced it — and that stays honest as the project moves.
Explicitly NOT: another ticket hierarchy, a Gantt chart, dates, or a restatement
of the cascade. The cascade already owns order; this owns meaning.
HOW TO PICK THIS UP — READ THIS BEFORE CREATING ANY EPICS
The first work is INVESTIGATION AND PLANNING, not implementation, and not
epic-cutting. Do not open this initiative by inventing a list of epics; the epic
list is an OUTPUT of the first pass, not an input to it. Sequence:
1. HARVEST. Mine what already exists for roadmap-shaped content that was never
collected: docs/workshops/, docs/discussions/, docs/design/, the briefings,
the D-records'' "why" sections, the phase-epic descriptions, and the
conversational hints that only appear in commit messages and ticket notes.
Expect the good material to exist and be scattered — this project documents
heavily. The gap is composition, not absence.
2. INTERVIEW. Whatever the harvest cannot answer, ask Jeroen — directly and in
batches. The three facts above emerged from ordinary questions; assume more
are waiting behind questions nobody has asked. Record the answers as they
are given, before interpreting them.
3. INVESTIGATE FORM. Do not assume markdown-in-docs/ is right. Options worth
weighing: a single narrative document; a per-phase "what this buys and why"
layer attached to the existing phase epics; a D-record class for direction
rather than decisions; something queryable through pql alongside the DQR
tree; a visual map. Judge each against the failure mode this exists to
prevent — a reader who knows every decision and still cannot state the
direction — and against staying current without ceremony.
4. PROPOSE, WITH OPTIONS. Bring 2-3 concrete shapes with trade-offs and a
recommendation. This is a design decision about the project''s own memory;
it deserves a D-record and Jeroen''s ruling, not an agent''s unilateral pick.
5. ONLY THEN CUT EPICS, against the chosen shape and what the harvest showed is
missing. Epics come last because the work is unknown until steps 1-4 have
run.
ACCEPTANCE — the artefact earns its keep if:
- A fresh session can read it and state, without asking, what the game is
trying to be and what the next three big problems are.
- Facts of the kind listed above (forward reservations, staged gates, "this
system is really for that future thing") have an obvious home, so the next
one gets written down instead of surfacing years later in a chat.
- It is cheap enough to keep current that it actually gets updated. A roadmap
that rots is worse than none, because it lies with authority.
- It does not duplicate the cascade, the ticket tree, or the DQR records. If a
section restates any of those, it belongs there instead.
RELATED: D-166 (cascade order), T-745 (the cascade initiative), and this
session''s docs/wiki-structure-findings.md, whose root-cause finding was the same
shape — the information existed and nothing pointed at it.
---
THE MECHANISM THAT CREATES THIS GAP, from Jeroen (2026-08-20):
"I tend to restrict future side quests to not confuse your context. I should have
you file tickets at least."
That is the root cause, and it is a REASONABLE practice producing a bad outcome.
Withholding forward-looking intent keeps a working session focused — a real
benefit, not a mistake. But the intent then exists only in conversation, and
conversations are not artefacts. Every fact in the list above reached this repo
by accident: someone happened to ask, on a day when it happened to be relevant.
The resolution is not "share everything" — that would trade focus for memory.
It is to SEPARATE THE TWO CHANNELS:
- Working context stays narrow. Unchanged.
- Forward intent gets FILED, not discussed. A ticket, a note on an existing
ticket, or a roadmap entry — written at the moment it surfaces, without
pulling the current task sideways.
So whatever form this initiative lands on must be CHEAP TO APPEND TO from inside
an unrelated session. If recording "this field is reserved for a future tier"
requires opening a planning ritual, it will not happen while someone is midway
through a rendering bug — which is exactly when these facts surface.
Design implication, carried into step 3 (INVESTIGATE FORM): weight the options by
cost-to-append, not just by cost-to-read. An artefact that is pleasant to read
and expensive to update will rot, and this project already has heavily-documented
trees that stayed accurate precisely because updating them was one line.', NULL, '2026-08-19 22:39:34', '2026-08-19 22:39:34.248', '2026-08-19 22:39:34.248', NULL, 'e74c0f651c9053b62e256b0201f77d9a', 2) ON CONFLICT(hash) DO NOTHING;
.pql/changelog/tickets/2026-08.sql
+129
View File
@@ -953,3 +953,132 @@ ACCEPTANCE — the artefact earns its keep if:
RELATED: D-166 (cascade order), T-745 (the cascade initiative), and this
session''s docs/wiki-structure-findings.md, whose root-cause finding was the same
shape — the information existed and nothing pointed at it.', 'backlog', 'high', NULL, 'meta', NULL, '2026-08-19 22:38:22.412', '2026-08-19 22:38:30.454', NULL, 'f787c3a0250b47f88079efda1b22bb97', 2) ON CONFLICT(record_id) DO UPDATE SET type=excluded.type, parent_record_id=excluded.parent_record_id, title=excluded.title, description=excluded.description, status=excluded.status, priority=excluded.priority, assigned_to=excluded.assigned_to, team=excluded.team, decision_ref=excluded.decision_ref, updated_at=excluded.updated_at, deleted_at=excluded.deleted_at, hash=excluded.hash, canonical_version=excluded.canonical_version WHERE excluded.updated_at >= tickets.updated_at;
INSERT INTO tickets (record_id, type, parent_record_id, title, description, status, priority, assigned_to, team, decision_ref, created_at, updated_at, deleted_at, hash, canonical_version) VALUES ('06G1RB7GSJA4379EAQDZPQQDN8', 'initiative', NULL, 'Roadmap that carries intent — where the game is going, not just what order the work runs in', 'The project has a work breakdown and calls it a roadmap. The cascade owns ORDER, the ticket tree owns DECOMPOSITION, the DQR tree owns individual RULINGS — and none of them answer what the game is going to be, what the big unsolved problems are, or what is deliberately deferred. Pick-up instructions are in the appended body: the first pass is harvest/interview/investigate-form/propose-with-options, and EPICS ARE AN OUTPUT of that pass, not an input. Do not open this by inventing an epic list.
---
WHY THIS EXISTS
The project has a work breakdown and calls it a roadmap. It is not one.
What exists today, and what each is good at:
- The Development Cascade (T-745 -> six phase epics, D-166): strict ORDER. It
says what must be finished before what, and it is enforced. It does not say
what the thing being built is, or why a phase is worth its cost.
- The ticket tree (initiative/epic/story/task): decomposition of work already
decided on. It answers "what is left in this batch", never "is this batch the
right thing".
- The DQR tree (governance/decisions|questions|rejected): individual rulings with
rationale, each excellent in isolation. 260+ D-records do not compose into a
direction; a reader can know every decision and still not know where the game
is going.
- Briefings, workshops, discussions: rich, but point-in-time and per-agent.
None of these answer the questions someone actually asks about a roadmap: what is
this game going to BE, what are the big unsolved problems between here and that,
in what order do they unlock each other, what does "done" look like for each, and
what is deliberately not being solved yet.
THE EVIDENCE THAT THIS IS A REAL GAP, not a tidiness urge:
On 2026-08-20, in one conversation, three roadmap-level facts surfaced that exist
in NO artefact in this repo:
1. The economics tree is not just trade-sim data — once geology and nature
spawn to the 1x1 m pixel, the economics information GENERATES WORLD CONTENT.
Production chains decide what is physically on the ground.
2. `chemosynthetic: false` on every body is a namespace RESERVATION for
dextro-DNA-style biochemistry at that same future tier — not a dead field.
3. `enabled: false` on ~65% of bodies is staged rollout: learn the clean planet
types first, then add generator scripts for the other types and the playable
count rises.
Two of those three were written up as suspected DEFECTS by an agent reading the
repo carefully, because nothing recorded them as intent. That is the cost, and it
recurs: the roadmap lives in one person''s head and leaks out only when someone
happens to ask the right question.
WHAT THIS INITIATIVE IS FOR
Produce a roadmap artefact that carries INTENT and SHAPE, in a form that survives
being read by someone (or something) with no memory of the conversations that
produced it — and that stays honest as the project moves.
Explicitly NOT: another ticket hierarchy, a Gantt chart, dates, or a restatement
of the cascade. The cascade already owns order; this owns meaning.
HOW TO PICK THIS UP — READ THIS BEFORE CREATING ANY EPICS
The first work is INVESTIGATION AND PLANNING, not implementation, and not
epic-cutting. Do not open this initiative by inventing a list of epics; the epic
list is an OUTPUT of the first pass, not an input to it. Sequence:
1. HARVEST. Mine what already exists for roadmap-shaped content that was never
collected: docs/workshops/, docs/discussions/, docs/design/, the briefings,
the D-records'' "why" sections, the phase-epic descriptions, and the
conversational hints that only appear in commit messages and ticket notes.
Expect the good material to exist and be scattered — this project documents
heavily. The gap is composition, not absence.
2. INTERVIEW. Whatever the harvest cannot answer, ask Jeroen — directly and in
batches. The three facts above emerged from ordinary questions; assume more
are waiting behind questions nobody has asked. Record the answers as they
are given, before interpreting them.
3. INVESTIGATE FORM. Do not assume markdown-in-docs/ is right. Options worth
weighing: a single narrative document; a per-phase "what this buys and why"
layer attached to the existing phase epics; a D-record class for direction
rather than decisions; something queryable through pql alongside the DQR
tree; a visual map. Judge each against the failure mode this exists to
prevent — a reader who knows every decision and still cannot state the
direction — and against staying current without ceremony.
4. PROPOSE, WITH OPTIONS. Bring 2-3 concrete shapes with trade-offs and a
recommendation. This is a design decision about the project''s own memory;
it deserves a D-record and Jeroen''s ruling, not an agent''s unilateral pick.
5. ONLY THEN CUT EPICS, against the chosen shape and what the harvest showed is
missing. Epics come last because the work is unknown until steps 1-4 have
run.
ACCEPTANCE — the artefact earns its keep if:
- A fresh session can read it and state, without asking, what the game is
trying to be and what the next three big problems are.
- Facts of the kind listed above (forward reservations, staged gates, "this
system is really for that future thing") have an obvious home, so the next
one gets written down instead of surfacing years later in a chat.
- It is cheap enough to keep current that it actually gets updated. A roadmap
that rots is worse than none, because it lies with authority.
- It does not duplicate the cascade, the ticket tree, or the DQR records. If a
section restates any of those, it belongs there instead.
RELATED: D-166 (cascade order), T-745 (the cascade initiative), and this
session''s docs/wiki-structure-findings.md, whose root-cause finding was the same
shape — the information existed and nothing pointed at it.
---
THE MECHANISM THAT CREATES THIS GAP, from Jeroen (2026-08-20):
"I tend to restrict future side quests to not confuse your context. I should have
you file tickets at least."
That is the root cause, and it is a REASONABLE practice producing a bad outcome.
Withholding forward-looking intent keeps a working session focused — a real
benefit, not a mistake. But the intent then exists only in conversation, and
conversations are not artefacts. Every fact in the list above reached this repo
by accident: someone happened to ask, on a day when it happened to be relevant.
The resolution is not "share everything" — that would trade focus for memory.
It is to SEPARATE THE TWO CHANNELS:
- Working context stays narrow. Unchanged.
- Forward intent gets FILED, not discussed. A ticket, a note on an existing
ticket, or a roadmap entry — written at the moment it surfaces, without
pulling the current task sideways.
So whatever form this initiative lands on must be CHEAP TO APPEND TO from inside
an unrelated session. If recording "this field is reserved for a future tier"
requires opening a planning ritual, it will not happen while someone is midway
through a rendering bug — which is exactly when these facts surface.
Design implication, carried into step 3 (INVESTIGATE FORM): weight the options by
cost-to-append, not just by cost-to-read. An artefact that is pleasant to read
and expensive to update will rot, and this project already has heavily-documented
trees that stayed accurate precisely because updating them was one line.', 'backlog', 'high', NULL, 'meta', NULL, '2026-08-19 22:38:22.412', '2026-08-19 22:39:34.248', NULL, '69d785aeb9a77c4c9296c6b404237dfb', 2) ON CONFLICT(record_id) DO UPDATE SET type=excluded.type, parent_record_id=excluded.parent_record_id, title=excluded.title, description=excluded.description, status=excluded.status, priority=excluded.priority, assigned_to=excluded.assigned_to, team=excluded.team, decision_ref=excluded.decision_ref, updated_at=excluded.updated_at, deleted_at=excluded.deleted_at, hash=excluded.hash, canonical_version=excluded.canonical_version WHERE excluded.updated_at >= tickets.updated_at;