graph-writer

name	graph-writer
description	SGR-guided knowledge graph node creation with canonical schema validation. Use when creating new nodes, updating existing nodes, or auditing graph health. Enforces closed vocabularies for node types, clusters, and relation types to prevent taxonomy drift. Triggers on: "create node", "add to graph", "new insight", "graph audit", "validate graph", "taxonomy check".

graph-writer — SGR-Guided Knowledge Graph Writer

Purpose

Create and validate KG nodes using Schema-Guided Reasoning. Prevents taxonomy drift via Pydantic schemas with Literal (closed) vocabularies.

When to Use

• Creating any new node in 02_distill/
• Updating frontmatter of existing nodes
• Running graph health audits
• Validating that relation targets exist

Canonical Vocabularies

Node Types (9)

Type	Use for
knowledge	factual content, documentation, reference
insight	analytical observation, recommendation
task	actionable item (+ optional deadline)
project	multi-task initiative with scope
direction	strategic cluster / thematic area
process	operational procedure, runbook
decision	recorded decision with rationale
person	collaborator, contact
longterm	long-horizon goal or vision

Clusters (10 canonical)

Cluster	Scope
operations	Agent stack, infra, skills, tools, openclaw
research	academic, papers, experiments
domain_a	Healthcare domain example
teaching	courses, lectures, educational content
domain_b	Legal domain example
clients	client engagement meta-cluster
client_alpha	specific client
system_integration	cross-system integration, APIs
archive	deprecated or historical
restricted_domain	НДІ ЗСУ — closed contour, NEVER leak

Relation Types (10 canonical)

Type	Meaning
IMPLEMENTS	A implements/realizes B
EXTENDS	A extends/builds upon B
BUILDS_ON	A inspired by / builds on B
PART_OF	A is component of B
DEPENDS_ON	A requires B
COMPLEMENTS	A and B are complementary
VALIDATES	A validates/confirms B
SUPERSEDES	A replaces/obsoletes B
CONTRADICTS	A contradicts B
RELATED_TO	general (when no stronger type fits)

Status Values

draft → active → ready → done → archived (also: on_hold)

Sensitivity

public | internal (default) | restricted

Required Fields for Every New Node

id: lowercase_with_underscores_and_hyphens
type: <from 9 types above>
clusters: [<from 10 clusters above>]
summary: "10-500 chars"
status: draft
retrieval_hints:
  - "search phrase for finding this node"

Recommended Fields

primary_direction: <one cluster>
sensitivity: internal
when_to_read:
  - "condition when lazy loader should fetch this"
tags: [<prefer canonical tags>]
relations:
  - target: existing_node_id
    type: <from 10 types above>
links: [node_id1, node_id2]

Process: Creating a New Node

1. Reason (SGR step): what is the content, what type, which clusters, what relates?
2. Check existing: python3 scripts/graph_node_schema.py — verify target IDs exist
3. Generate frontmatter using canonical vocabularies above
4. Validate: run python3 -c "from scripts.graph_node_schema import validate_frontmatter; ..."
5. Write file to 02_distill/ with validated frontmatter
6. Update graph: add node + edges to 02_distill/graphs/context_graph.json
7. Commit

Audit

Run full graph audit:

python3 scripts/graph_audit.py

Reports: invalid types, non-canonical clusters, dangling targets, missing fields, orphans.

Migration Rules (from legacy)

Legacy	→ Canonical
cluster insights	remove (redundant with type=insight)
cluster cards	remove (not a cluster)
cluster openclaw	→ operations
cluster ideal_agent	→ operations
type deadline_task	→ task + add deadline field
relation INSPIRES	→ BUILDS_ON
relation APPLICABLE_TO	→ RELATED_TO or IMPLEMENTS
relation USES	→ DEPENDS_ON
relation SUPPORTS	→ RELATED_TO
relation ANALYZES	→ RELATED_TO
relation SYNTHESIZES	→ BUILDS_ON
relation OPERATIONALIZES	→ IMPLEMENTS

Canonical Tags (suggested, not enforced)

Technology: ai, llm, rag, nlp, genai, embeddings, graph, knowledge-graph, agents, multi-agent, openclaw, sgr, schema-guided-reasoning, function-calling, structured-output, prompt-engineering

Operations: automation, deployment, monitoring, security, delegation, reliability, ops, skills, tools, memory, retrieval, verification

Domains: medical, legal, financial, seo, domain_b, restricted_domain, teaching

Meta: architecture, research, implementation-plan, human-in-the-loop, workflow, taxonomy