# Knowledge

> Use when work surfaces something epistemic worth keeping — "we're assuming / proceeding as if X", "we decided X over Y", "open question worth outliving this session", "we're bound by X", "evidence for/against X", "testable hypothesis", or a stable concept worth naming — and when settling, relating, or surveying such records. Routes capture, settle, and survey intent to the correct `doctrine knowledge` verb.

- Skill: `davidlee/knowledge` (Agent Skill)
- Install (CLI): `npx skillmds@latest add davidlee/knowledge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/davidlee/knowledge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: davidlee (https://skillmd.com/u/davidlee)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/davidlee/knowledge

---


# 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.