davidlee Knowledge
Knowledge records are the epistemic home — typed, citable entities for what the project believes, chose, wonders about, observes, or is bound by. Records shape work; they are never work items themselves.
Four homes, one line: work intent → backlog; epistemic state → knowledge
record; architectural decision → ADR; agent guidance → memory. See
using-doctrine.md § Which home for which record.
The CLI is the source of truth for exact flags and each kind's status
vocabulary: doctrine knowledge --help.
Which kind
| phrase shape | kind |
|---|---|
| "proceeding as if X" (unvalidated premise) | assumption (ASM) |
| "we chose X over Y" (scoped/operational) | decision (DEC) |
| "unresolved — X?" (needs an answer) | question (QUE) |
| "bound by X" (externally imposed limit) | constraint (CON) |
| "observed — X" (citable observation) | evidence (EVD) |
| "testable claim X" (awaiting evidence) | hypothesis (HYP) |
| "stable mental model / term X" | concept (CPT) |
DEC or ADR? Project-global with architectural consequences →
doctrine adr new; scoped or operational → DEC.
Verbs
| intent | verb |
|---|---|
| capture | doctrine knowledge new <kind> [title] |
| survey | doctrine knowledge list |
| read one | doctrine knowledge show <ID> |
| settle / transition | doctrine knowledge status <ID> <STATE> |
| relate to the work it shapes | doctrine link <REC-ID> shapes <TARGET> (spawns for work it caused) |
| evidentiary edge | doctrine link EVD-n supports <REC-ID> (or disputes) |
| replace with a successor | doctrine supersede <NEW-ID> <OLD-ID> |
Wrong home?
- Work intent (bug / improvement / chore / risk / idea) →
/backlog. - Reusable agent guidance, recipe, or gotcha →
/record-memory.
Discriminator: a knowledge record is a citable epistemic entity in the
relation graph — relatable, gateable, supersedable; a memory is
retrieval-layer guidance for agents. The same line splits CPT from a memory
concept: a CPT names a stable project concept other entities will cite; a
memory explains how to think or work.
Gating — association is not gating
shapes influences; it never blocks. To gate work on an unsettled record,
the dependent work item authors the edge — doctrine needs SL-42 QUE-7 —
and settling the record (knowledge status to a terminal state) unblocks it;
no unlink needed. Records never author needs/after themselves.
Rules
- The id prefix (
ASM-/DEC-/QUE-/CON-/EVD-/HYP-/CPT-) resolves the kind on read and transition — no kind flag needed. - Capture seeds the kind's default state (held, proposed, open, active, …).
- Don't hand-edit record TOML — use the verbs. The prose body (
*.md) is hand-edited.