Say what the old 'knowledge base' meant, now that the word names the module (issue 430)
The record and the records module for symptom search, the constitution page by its own name.
This commit is contained in:
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: canonical
|
||||
updated: 2026-08-23
|
||||
derives: knowledge-base constitution page
|
||||
derives: the constitution page
|
||||
decisions:
|
||||
- "ADR 0020"
|
||||
---
|
||||
@@ -198,8 +198,8 @@ declaration was never wrong. Nothing ever asked the system.
|
||||
### Search the record before forming a hypothesis
|
||||
|
||||
The first action on any error message, failing service or unexpected behaviour is to search the
|
||||
operational memory for the literal error text — before a hypothesis, not after one fails. The
|
||||
knowledge base is indexed on symptoms.
|
||||
record for the literal error text (`records.records_search`) — before a hypothesis, not after one fails.
|
||||
The record is indexed on symptoms.
|
||||
|
||||
This fires hardest on *familiar* ground, where a confident trail feels like progress. Two
|
||||
entries were each rediscovered from scratch over several hours in a single session because the
|
||||
|
||||
@@ -8,15 +8,15 @@ design permits.
|
||||
|
||||
## What belongs here, and what does not
|
||||
|
||||
| Belongs in `04-ISSUES` | Belongs in the knowledge base |
|
||||
| Belongs in `04-ISSUES` | Belongs in the operational lessons |
|
||||
|---|---|
|
||||
| The design permits a failure to be silent | How to fix one occurrence of it |
|
||||
| A documented rule is enforced by nothing | A command that works around it |
|
||||
| A stated invariant is false in practice | A node-specific quirk |
|
||||
| The owning component is unknown and finding it needs the whole mesh in view | Symptom → fix, once the answer is known |
|
||||
|
||||
The knowledge base already holds the operational record and is indexed on symptoms. This
|
||||
folder is not a second copy of it. An issue here is a question HQ must **answer**, not an
|
||||
The operational lessons (symptom → fix) are found by their literal symptom text through the records
|
||||
module (`records.records_search`). This folder is not a second copy of them. An issue here is a question HQ must **answer**, not an
|
||||
incident someone must **clear**.
|
||||
|
||||
## The issue tracker holds the number and the status
|
||||
@@ -109,8 +109,8 @@ import read, which every imported issue names (`imported.commit` in `issue-track
|
||||
- A number never moves. A folder carries the number the tracker gave; a folder whose number collides with
|
||||
another (one numbered before the tracker, or by hand) is a fault, and `cycle.py` refuses two records
|
||||
sharing a number.
|
||||
- An issue whose answer is a general lesson should also be written to the knowledge base, so
|
||||
the next person searching a symptom finds it. Both, not either.
|
||||
- An issue whose answer is a general lesson also says that lesson in its resolution, in the symptom's
|
||||
own words, so the next person searching that symptom finds it. Both, not either.
|
||||
- `wontfix` is legitimate and requires a sentence saying why; the tracker refuses it without one.
|
||||
- **An agent says when it starts work on an issue**, by moving it to `diagnosing` or `fixing` with `by`. Two agents
|
||||
never start the same work without knowing: the second is refused, naming the first.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Playbook 05 — Constitution sync
|
||||
|
||||
Implements ADR 0021: HQ is
|
||||
the source of the constitution, and the knowledge-base page is derived, never edited.
|
||||
the source of the constitution, and the constitution page is derived, never edited.
|
||||
|
||||
**Trigger.** [`how-we-build.md`](../how-we-build.md) changed a rule that the mesh enforces at
|
||||
runtime.
|
||||
@@ -24,7 +24,7 @@ and, per the repository's own rule, it is how the rule "HQ is the source" is che
|
||||
the derived page carries the rule alone.
|
||||
2. Record the change as a decision — a rule the mesh enforces is architecturally significant.
|
||||
Playbook [02](02-graduation.md).
|
||||
3. Publish the derived page to the knowledge base under the constitution slug, replacing its
|
||||
3. Publish the derived page where the mesh keeps the constitution page, under its slug, replacing its
|
||||
body. Keep the section numbering stable: the meeting orchestrator and the review fragments
|
||||
cite sections by number.
|
||||
4. Verify the derived page reads back with the change present. A publish that reported success
|
||||
|
||||
@@ -77,8 +77,8 @@ in running prose; a quotation keeps its words.
|
||||
that exists; [`03-DESIGN/01-to-be/`](03-DESIGN/01-to-be/) describes the one being built
|
||||
toward. Every design doc says which it is in `layer:`. A statement about the future does not
|
||||
belong in an as-is document, and an as-is document is never edited to describe an intention.
|
||||
- **`00-META/how-we-build.md` is the source of the mesh constitution.** The knowledge-base
|
||||
constitution page is derived from it — see playbook
|
||||
- **`00-META/how-we-build.md` is the source of the mesh constitution.** The constitution page
|
||||
is derived from it — see playbook
|
||||
[`05-constitution-sync.md`](00-META/process/05-constitution-sync.md). Never edit the
|
||||
derived page directly.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user