Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jbarrasa/goingmeta/llms.txt

Use this file to discover all available pages before exploring further.

Season 3, Episode 8 of Going Meta closes the season by turning the lens on ontology engineering itself. Every ontology embodies hundreds of small decisions — why is Encounter a subclass of Event rather than Activity? Why was Medication excluded? Why was a three-level taxonomy chosen instead of two? In practice these decisions are rarely recorded, making ontologies opaque artifacts that are hard to review, extend, or hand off. This session demonstrates how to capture design decisions as a meta-graph stored directly in Neo4j — a “graph behind the graph” that makes ontology reasoning transparent and queryable.

Watch the Recording

Season 3, Episode 8 — May 2026

Session Code

PDF presentation slides
The session46 repository contains only the PDF presentation (Going Meta - The Graph Behind the Graph: Tracing Ontology Design Decisions.pdf). No code files are published for this session. The Cypher examples shown below are illustrative of the decision-graph patterns discussed in the recording.

​
The Problem: Ontologies Are Black Boxes

An OWL ontology file tells you what was modelled — the classes, properties, and axioms — but nothing about why those choices were made. Typical questions that go unanswered include:
  • Why was this class included when a similar concept was excluded?
  • What competency question drove the choice to make X a subclass of Y rather than a sibling?
  • Who made this decision, and was it reviewed?
  • Which design choices were considered and rejected, and for what reasons?
When ontologies evolve over months or years, the absence of decision records leads to repeated debates, inconsistent extensions, and loss of institutional knowledge.

​
Design Decisions as Graph Nodes

The solution is to represent each design decision as a first-class node in Neo4j, connected to the ontology elements it affected, the evidence and requirements that motivated it, and any alternatives that were considered and rejected. A minimal decision node captures: 
CREATE (d:DesignDecision {
    id: "DD-001",
    title: "Model Encounter as a subclass of Event",
    rationale: "Encounter represents a temporal occurrence (clinical contact), not an agent, and all included classes must sit under exactly one top-level branch. Event is the appropriate grounding class.",
    decidedBy: "ontology-builder-assistant",
    decidedAt: datetime("2026-04-07T14:23:00"),
    status: "accepted"
})
Decisions are linked to the ontology elements they affect: 
MATCH (d:DesignDecision {id: "DD-001"})
MATCH (cls:OntologyClass {uri: "https://w3id.org/goingmeta/ccs#Encounter"})
CREATE (d)-[:AFFECTS]->(cls)
And to the competency questions or requirements that drove them: 
MATCH (d:DesignDecision {id: "DD-001"})
MATCH (cq:CompetencyQuestion {id: "CQ-03"})
CREATE (d)-[:MOTIVATED_BY]->(cq)

​
Recording Rejected Alternatives

One of the most valuable things the decision graph captures is alternatives that were considered but rejected: 
CREATE (alt:DesignAlternative {
    id: "ALT-001-A",
    description: "Model Encounter as a subclass of Activity instead of Event",
    rejectionReason: "Activity implies agency; Encounter is primarily a temporal framing of a clinical contact, not an action performed by an agent. Using Event keeps the taxonomy consistent with the temporal/non-temporal split."
})

MATCH (d:DesignDecision {id: "DD-001"})
MATCH (alt:DesignAlternative {id: "ALT-001-A"})
CREATE (d)-[:CONSIDERED_ALTERNATIVE]->(alt)

​
Linking Decisions to Evidence

Decisions can be traced back to the sample data or supporting evidence that justified inclusion: 
CREATE (ev:Evidence {
    id: "EV-001",
    type: "SampleDataPattern",
    description: "15 of 20 clinical case sheets contain an explicit admission or presentation event with a date, location, and patient reference",
    sourceFile: "clinical_cases_sample.txt"
})

MATCH (d:DesignDecision {id: "DD-001"})
MATCH (ev:Evidence {id: "EV-001"})
CREATE (d)-[:SUPPORTED_BY]->(ev)

​
Querying the Decision Graph

Once decisions are stored in Neo4j, they become queryable. Find all decisions that affected a specific class: 
MATCH (d:DesignDecision)-[:AFFECTS]->(cls:OntologyClass)
WHERE cls.uri CONTAINS "Encounter"
RETURN d.id, d.title, d.rationale, d.decidedAt
ORDER BY d.decidedAt
Find decisions motivated by a specific competency question: 
MATCH (d:DesignDecision)-[:MOTIVATED_BY]->(cq:CompetencyQuestion)
WHERE cq.id = "CQ-03"
RETURN d.id, d.title, d.rationale
Find all rejected alternatives across the ontology: 
MATCH (d:DesignDecision)-[:CONSIDERED_ALTERNATIVE]->(alt:DesignAlternative)
RETURN d.id, d.title, alt.description, alt.rejectionReason
ORDER BY d.id
Trace the full provenance chain for a class — from the competency question through the decision to the evidence: 
MATCH (cq:CompetencyQuestion)<-[:MOTIVATED_BY]-(d:DesignDecision)-[:AFFECTS]->(cls:OntologyClass),
      (d)-[:SUPPORTED_BY]->(ev:Evidence)
WHERE cls.uri CONTAINS "Patient"
RETURN cq.text, d.title, d.rationale, ev.description

​
Integrating with the Agent Skills Workflow

The decision graph integrates naturally with the ontology-builder-assistant skill from Session 45. The skill’s output contract — CQ-to-ontology mapping, class definitions with inclusion justifications, exclusion records — maps directly to the decision graph schema:
Skill output sectionDecision graph node type
CQ-to-ontology mapping(:DesignDecision)-[:MOTIVATED_BY]->(:CompetencyQuestion)
Inclusion justification(:DesignDecision)-[:SUPPORTED_BY]->(:Evidence)
Exclusions(:DesignDecision {status: "rejected"})
Alternative considered(:DesignDecision)-[:CONSIDERED_ALTERNATIVE]->(:DesignAlternative)
Class definition(:OntologyClass) node enriched from the decision
An LLM agent running the ontology-builder-assistant skill can be extended to emit design decisions as a Cypher CREATE block alongside the Turtle serialisation, populating the decision graph as a by-product of the normal ontology creation workflow.
The decision graph does not need to live in the same database as the operational knowledge graph. It can be held in a dedicated decisions database or Neo4j Workspace and linked by URI references to the ontology elements in the main database.

​
Why This Matters

Auditability

Every modeling choice is recorded with a rationale, timestamp, and author — making the ontology auditable and compliant with governance requirements.

Reproducibility

New team members or LLM agents can reconstruct the reasoning behind the current model by querying the decision graph rather than guessing from the Turtle file.

Conflict Resolution

When two engineers disagree on a modeling choice, the existing decision graph surfaces prior art, previous considerations, and the evidence that settled earlier debates.

Ontology Evolution

When the ontology needs to change, the decision graph shows which competency questions would be affected by a modification, enabling impact analysis before edits are made.
Start small: record decisions only for the ten most consequential modeling choices in your ontology. The value of the decision graph is proportional to the quality of the rationale captured, not the number of nodes created.

Build docs developers (and LLMs) love

Get started for freeTalk to us