awesome-copilot/skills/mini-context-graph/references/ontology.md

Ontology Instructions

This file defines the rules for maintaining and evolving the dynamic ontology used by the Context Graph.

---

Core Principle

The ontology is NOT fixed. Types and relations emerge from documents as they are ingested. However, the ontology must remain compact, consistent, and reusable.

---

Entity Type Rules

Normalization

When assigning an entity type, apply these transformations:

1. Convert to lowercase
2. Strip leading/trailing whitespace
3. Replace underscores and hyphens with spaces
4. Merge synonymous types using the mapping table below

Synonym Mapping (Entity Types)

Variant	Canonical Type
component, module, class, function	component
bug, defect, fault, error, failure	issue
server, host, machine, node	infrastructure
user, person, operator, admin, actor	actor
app, application, service, program, software	software
database, datastore, db, storage	storage
api, endpoint, interface, connection	interface
event, incident, occurrence, trigger	event
concept, idea, principle, theory	concept
process, thread, task, job, workflow	process

Adding New Types

If an entity does not match any existing type:

• Create a new type if it is genuinely distinct
• Keep the label short (1–3 words, lowercase)
• Consider whether an existing type is close enough before creating a new one

Constraint

• Maximum ~50 distinct entity types across the entire ontology
• If the limit is approached, merge similar types rather than creating new ones

---

Relation Type Rules

Normalization

When assigning a relation type:

1. Convert to lowercase
2. Strip whitespace
3. Use verb phrases in present tense (e.g., "causes", "contains", "uses")
4. Merge synonyms using the mapping table below

Synonym Mapping (Relation Types)

Variant	Canonical Relation
triggers, leads to, results in, produces	causes
is part of, belongs to, lives in, sits in	contains
depends on, requires, needs	depends on
uses, calls, invokes, consumes	uses
affects, impacts, influences	affects
creates, instantiates, spawns	creates
connects to, links to, references	connects to
inherits from, extends, subclasses	extends
reads from, queries, fetches	reads from
writes to, stores in, persists to	writes to

Adding New Relations

• Only add new relation types if no existing type accurately describes the relationship
• Prefer canonical relations over creating new ones

---

Ontology Update Protocol

When processing extracted entities/relations from ingestion.md:

1. For each entity type:

   • Run through the synonym mapping
   • Call ontology_store.normalize_type(type_name) to get the canonical form
   • Call ontology_store.add_type(canonical_type) to register it

2. For each relation type:

   • Run through the synonym mapping
   • Call ontology_store.normalize_relation(relation_name) to get the canonical form
   • Call ontology_store.add_relation(canonical_relation) to register it

3. Use the canonical type/relation names when creating nodes and edges in the graph.