Context Graph

Context Graph

Concept of the skill

Context discovery is a graph problem: agents start from the current task, then traverse typed edges to find the skills, docs, memory records, scripts, and command surfaces that are relevant but not explicitly named.

Coverage

The architectural model behind navigable context in an AI-coding workspace. Names the four interconnected graphs that any mature workspace accumulates — Skill Knowledge Graph, Document Routing Graph, Memory Index, Script / Command Registry — and the cross-graph edges that connect them (skill → script, skill → memory, doc-routing → doc, script → command). Specifies the three skill-graph edge types (adjacent, boundary, verify_with) and their per-edge-type caps. Defines orphan detection (a node with zero or near-zero incoming edges that agents cannot find by traversal) and the priority order for remediation (security skills first, then financial, integration, infrastructure, then UX). Specifies graph-connectivity metrics with locally calibrated healthy / unhealthy bands: connectivity, average degree, orphan rate, max degree, cluster count, hub-spoke ratio. Names the five deterministic signals that should drive graph synthesis (explicit prose references, manual relations frontmatter, bundle co-membership, shared routing labels, keyword overlap) — never an LLM at synthesis time. Walks the change-propagation checklist that traces a single edit across all four graphs. Catalogs the anti-patterns that quietly destroy graph quality: edge inflation, one-way edges, optional-metadata mindset, AI-inferred edges that drift on rebuild, ignoring cross-graph edges.

Philosophy of the skill

Without a navigable graph, agents cannot discover context they did not already know existed. The original failure mode looks like this: a skill exists, the agent doesn't reference it by name in the current prompt, and the routing layer has no edge to find it from — so the skill might as well not exist. A workspace can ship hundreds of skills and still operate as if it had ten, because the other 290 are unreachable from any traversal an agent actually performs.

Context discovery is therefore a precondition for context quality. If the right skill, doc, or memory file cannot be found by following edges from the current task, content quality is irrelevant. Graph maintenance — adding edges, fixing orphans, capping inflation, keeping cross-graph references current — is a quality gate, not optional metadata. Every new skill enters the system with a question attached: who reaches this from where, by which edges?

The deterministic-signal discipline is the second non-negotiable. Graph synthesis must be a deterministic function of the authored artifacts (frontmatter relations, bundle membership, prose references, shared routing labels, keyword overlap) — not an LLM inference. If the graph drifts on rebuild, agents lose the one stable surface they have. Use AI to suggest edges during authoring; never to generate the live graph at runtime.

1. The Four Context Graphs

A mature AI-coding workspace converges on four interconnected graphs:

Graph 1 — Skill Knowledge Graph

Nodes are skill files; edges are the typed relations declared in skill frontmatter. The job of this graph is what knowledge exists in the workspace, and what knowledge teaches alongside what other knowledge. The graph's vital signs are connectivity (no large isolated components), orphan rate (no skills nobody references), and edge-type discipline (each edge has a typed reason).

Graph 2 — Document Routing Graph

Nodes are documentation targets and change categories; edges express "when this kind of code changes, those docs must be updated." The job of this graph is propagation — preventing stale docs by making the doc-update obligation visible at the point of code change. The graph is most valuable when it is read by humans during PR review and by agents during the wrap / closeout protocol, not when it is read by no one.

Graph 3 — Memory Index

Nodes are persistent memory topic files (decisions, observations, durable preferences); edges are the index entries that point from a topic table to the underlying file. The job of this graph is cross-session knowledge persistence — the answer to "what did we already decide about X, why, and when did the decision become true." A memory graph that records facts but not the why and how of decisions cannot answer audit questions like "why did the agent choose Y?". Workspaces that need decision provenance extend the memory graph with the Process Knowledge Ontology pattern (modeling decisions, triggers, state transitions, and outcomes as first-class entities).

Graph 4 — Script / Command Registry

Nodes are scripts and commands; edges are the categorisations that group them by purpose. The job of this graph is agent tooling discovery — when an agent needs a deterministic script or a slash command, the registry is what makes it findable without trial-and-error.

Cross-graph edges

The four graphs are interconnected. The cross-graph edges are where most of the propagation value lives:

A workspace that names all four graphs and their cross-graph edges has a complete map. A workspace that names only the skill graph has roughly a quarter of the picture.

2. Edge Types in the Skill Graph

The skill graph uses three relation types. Each has a different meaning and a different cap. Mixing them collapses the graph into noise.

The caps exist to prevent edge inflation. A skill with 12 adjacent relations is not "well-connected" — it is a hub that pulls every adjacent traversal toward itself, hiding more specific signals. Edge discipline beats edge volume.

boundary is exclusion, not adjacency

The most common edge-type confusion: putting "topical neighbour" skills in boundary. Boundary edges tell the router "if both this skill and the boundary skill match, route AWAY from the boundary skill" — they are exclusion-with-a-reason, not "see also." Putting a skill in boundary that should be in related will hijack the boundary skill's positive cases and depress its routing-eval pass rate. When in doubt, prefer related and only promote to boundary when the two skills genuinely compete for the same prompt with different correct answers.

3. Orphan Detection

An orphan is a node with zero (or near-zero) incoming edges. Nothing points at it, so traversal cannot reach it; agents have to know its exact name to find it. In a healthy graph, the orphan rate is below 10%. In an unhealthy graph it is the majority — and adding more skills makes the problem worse, not better, because each new skill is also unreachable.

Orphan-detection recipe

1. Rebuild the graph from authored artefacts (deterministic synthesis).
2. Walk every node, count its degree (incoming + outgoing).
3. Flag every node with degree ≤ 1 as an orphan candidate.
4. For each orphan: identify its domain cluster (layer, keywords, examples) and find 3–5 sibling skills that should reference it.
5. Add relations to the orphan and reciprocal references to its siblings — bidirectionally. A one-way edge from the orphan does not solve discovery, because the existing skills are where traversal starts.

Remediation priority

Fix orphans in order of blast radius, not alphabetically:

1. Security and compliance skills — data exposure risk if agents miss them
2. Correctness-critical skills — financial, accounting, time, irreversible mutations
3. Integration skills — webhook signature verification, idempotency, retry
4. Infrastructure skills — operational impact (deploy, migrate, rollback)
5. UX / display skills — lower blast radius; fix once higher-priority orphans are gone

4. Graph Connectivity Metrics

These are the vital signs of a skill graph. Run them after every batch of skill additions or edge edits.

Five deterministic signals for graph synthesis

Synthesise the skill graph from these signals only — never from an LLM at runtime:

1. Explicit prose references — patterns like "Do NOT use X — use skill-name" in skill bodies
2. Manual relations frontmatter — author-declared edges
3. Bundle co-membership — skills declared in the same routing bundle
4. Shared routing labels / triggers — overlapping triggers or label declarations
5. Keyword overlap — shared keywords via the routing-config map

A graph built from these signals is reproducible: rebuild today and tomorrow and the edges are identical. A graph that uses LLM inference at synthesis time will drift on every rebuild and the routing layer cannot trust it.

5. Change-Propagation Analysis

When a single artefact changes, trace the propagation across all four graphs. This is the discipline that prevents silent staleness.

Propagation checklist

Each step exercises a different edge type. Skipping a step leaves a stale edge somewhere in the system, and the staleness compounds — the next change inherits a wrong baseline.

6. Anti-Patterns

Verification

• All four graphs in the workspace are named and have an authoritative source-of-truth file
• Cross-graph edges are explicit (skill → script, skill → memory, doc-routing → doc, script → command) — not implicit
• Graph rebuild is deterministic — same input artefacts produce identical edge set on every run
• Orphan-rate, average-degree, max-degree, and cluster-count thresholds have been calibrated from this workspace's graph history, then enforced consistently
• Edge-type discipline is enforced — adjacent ≤ 5, boundary ≤ 5, verify_with ≤ 3 per skill
• boundary is used for routing-exclusion only, not for "see also"
• The change-propagation checklist has been applied for the most recent significant change, end-to-end across all four graphs
• CI (or an equivalent gate) fails the merge when connectivity, orphan rate, or max degree breaches the healthy bands

Do NOT Use When