Epistemic knowledge graph for collaborative human-LLM knowledge management. Built on the llm.kb pattern. Models what we believe, why, how confidently, and where it comes from.
The five collections
Collection
What it holds
questions.kb/
Open inquiries that structure investigation
claims.kb/
Propositional assertions — observed or hypothesized
Question : someone asks something that needs investigation
Claim : someone asserts something that may or may not be true
Deduction : premises entail or contradict a conclusion (claim or deduction) — the body text explains why
Source : citing where claims originate
Definition : establishing what a term means, independent of claims about it
Scoping and hierarchy
Elaboration uses the standard llm.kb nesting convention: $ITEM.kb/ as a sibling of $ITEM.md. Sub-scopes contain the same five collection types (only those needed). The project root is itself an implicit scope.
When to elaborate
Multiple claims supporting/countering the same parent
Sub-questions arising from a question or claim
A deduction complex enough to need its own sub-claims
Most nodes should NOT have elaboration. A few sentences of body text with frontmatter references to other nodes is the normal case.
Roll-up
The parent node IS the summary. When a sub-scope resolves (e.g. a question is answered), update the parent node's status and body accordingly.
Path resolution
Cross-references use collection-relative paths: claims.kb/conways-law.md. Resolution walks up ancestor scopes until a match is found, up to project root.
Hoisting is non-breaking
Local files shadow ancestors with the same name
Content lives at the narrowest scope containing all its uses
Prefer moving a node down over reaching in with explicit paths — upward resolution handles outer references naturally
Schemas
Five $COLLECTION.jsonschema.yaml files, placed alongside the collections they govern. See schemas/ in this skill directory.
Relations and metadata
Cross-references are paths in YAML frontmatter (claims.kb/x.md). Epistemic metadata (status, likelihood, kind) tracks the standing of each node. Questions derive their state from field presence: resolved means answered, candidate-resolutions means under investigation, neither means new/open. See the schemas for the complete field definitions.
The core wiring pattern
Questions are answered by claims. Claims are supported by deductions. Deductions draw on other claims as premises.
candidate-resolutions points to claims , not deductions
conclusion points to a claim or deduction , not a question
depends expresses "needs context from" without implying support or refutation
Creating a discourse graph
Create a scope directory with CLAUDE.md declaring this skill
Link or copy $COLLECTION.jsonschema.yaml schemas from schemas/
Create collections as needed — start with sources.kb/ and questions.kb/
Populate nodes as markdown files with YAML frontmatter
Wire questions to claims via candidate-resolutions, claims to deductions via conclusion/premises
Elaborate nodes into sub-scopes when they outgrow a single file
Decomposition workflow
When extracting a discourse graph from a source document:
Source — create the provenance node first
Questions — identify the inquiries the source addresses
Claims + Deductions — interleaved, not separate passes. Each claim is either justified by a deduction or fundamental.
Wire — link questions to their candidate-resolutions, add depends
Scope — identify strictly inner questions and nest them
Reading a discourse graph
ls */ # What collections exist
grep -rL "resolved:" questions.kb/*.md # Open questions
cat claims.kb/some-claim.md # Read a claim
ls claims.kb/some-claim.kb/ # Has elaboration?
grep -l "status: contested" claims.kb/*.md # Find contested knowledge
Design rationale
See docs/dev/adr/ for decision records covering collection types, lexical scoping, elaboration conventions, terminology, similarity groups, and the open world assumption.
