Graph Engineering

Overview

Model a project as evidence-backed knowledge, not a pile of files. Build only the graph needed for the current decision, keep facts separate from inference, and persist only durable knowledge.

Core Contract

1. Define the question and the smallest useful scope.
2. Inspect existing documentation before source code, tests, configuration, and history.
3. Attach a repository path, symbol, sanitized command result, or commit to every important claim.
4. Classify each claim as observed, inferred, proposed, or unknown.
5. Represent relevant entities and connections with the vocabulary in knowledge-schema.md.
6. Apply update-policy.md before changing durable documentation.
7. Report impact, risk, unresolved questions, and the evidence that supports each conclusion.

Do not require a graph database, MCP server, external API, or special runtime. A compact Markdown table or diagram is enough when it preserves the required semantics.

Output Contract

Return these sections in order:

1. Scope — question, boundaries, and audited revision when available.
2. Evidence — strongest sources and any contradictions.
3. Knowledge map — relevant nodes and directed relations.
4. Impact — affected components, interfaces, constraints, and decisions.
5. Risks and unknowns — consequences, missing evidence, and validation needed.
6. Persistence decision — no change, update an existing document, or propose a new durable location.

Example map:

Durable Knowledge Guardrail

Default to read-only analysis. Edit project knowledge only when the user explicitly requests documentation changes or the authorized task clearly includes them.

Never persist:

• chain-of-thought, hidden reasoning, scratch notes, or loop transcripts;
• raw command output or logs; persist a sanitized conclusion and command reference instead;
• unverified guesses presented as facts;
• secrets, credentials, personal data, or environment-specific identifiers;
• temporary status that will be obsolete when the current task ends.

Common Mistakes