Graph Orient

Orients an agent at first entry to the graph. Entering a new knowledge graph without a curated path is expensive — every node looks equally worth reading, and the cost of reading them all before beginning work exhausts context. This skill walks a deliberately short path through the files that carry the most orientation signal per read: the agents file, the landing page, the Contracts at identity-block scale, the Convictions, and the Predicate vocabulary. After this path, the agent knows what forms the graph uses, what stances it holds, what predicates it speaks, and where the live tensions are.

The skill does not read all nodes, does not summarize individual Decisions or Observations, and does not follow edges into elaboration bodies. Depth on specific nodes is the job of Node Read; cross-topic traversal is the job of Node Research. Graph Orient is the cheapest read that produces enough context to make the later skills land well.

Steps

Step 1: Read AGENTS.md

Read the repository-root AGENTS.md file first. It carries the project's stance on agent behavior — curate not overwrite, translate not normalize, name features not traditions, treat new common vocabulary as proposal, preserve reasoning in the form, remain authored-by not authoring. These imperatives constrain every subsequent action the agent takes.

If the agent is working on a scion whose AGENTS.md differs from the template's, this is the authoritative stance — do not fall back on the template's file.

Report the stance imperatives in one compressed paragraph. The agent will not re-read this file later in the session; the compression is the reference.

Step 2: Read the landing surface

Read the project's landing surface. The landing surface is one of two shapes: a landing.md file at the repository root (older graphs), or a Touch Point node carrying is_home: true in its YAML frontmatter (newer graphs that adopted the Touch Point Form Contract). Check for landing.md first; if absent, search nodes/Touch Points/ for the home Touch Point.

The landing surface carries the project's public framing — what the graph is for at card scale, the founding Decision it rests on, the Convictions that ground the founding Decision, and the first-reader entry points.

Report the founding Decision and its grounding Convictions by name. These are the load-bearing commitments; every Decision downstream either composes with them or argues against them. If the landing surface names them as ghost wikilinks rather than resolved internal links, report them as ghost-linked-and-unauthored — a young graph framing its commitments before authoring the load-bearing nodes is a legitimate state, the same way an empty Convictions surface is in Step 4.

Step 3: Scan the Contracts

List nodes/Contracts/ and read each Contract's identity predicate block and opening paragraph — the cheapest two layers per Node Read. The Contracts establish the form system: Markdown Node Contract is the base; form-specific Contracts (Gloss, Decision, Conviction, Aspiration, Observation, Pattern, Predicate, Reference, Skill) extend it.

Report the Contracts by name, each with a one-line statement of what form it specifies. The agent does not read the ## Requirements sections of each Contract here — that cost is deferred to Node Create or Node Validate when an operation actually needs them.

Step 4: Scan the Convictions

List nodes/Convictions/ and read each Conviction's identity block, H1, and opening paragraph. Convictions carry held stances — the normative commitments the project's authors make about what ought to be the case in the domain the graph concerns. The specific Convictions vary per graph; read what the local graph carries, not what an upstream or template graph carried.

If nodes/Convictions/ does not exist or is empty, report "no Convictions yet authored in this graph" and proceed to Step 5. The skill's structure does not depend on Convictions being present; an empty Convictions surface is a legitimate state for a young or newly-scioned graph.

Report each Conviction's stance in one compressed sentence. A Conviction is the furthest-upstream anchor the agent can cite when a Decision needs grounding.

Step 5: Scan the Predicate vocabulary

List nodes/Predicates/ and read each Predicate node's filename and ## Carries paragraph. The Predicate filenames follow <predicate> -- <one-clause sense>.md, so the filename itself carries a compact definition.

Run a frequency audit to see which predicates are actually in use across the graph, regardless of whether they have a backing Predicate node:

rg -o -I -- '^- [a-z_]+::' nodes/ | sort | uniq -c | sort -rn

Report the vocabulary in two columns: predicates with a backing Predicate node (definitional) and predicates in use without a backing node (provisional or drift). The split lets the agent know which edges are load-bearing and which are candidates for predicate-proposal work.

Step 6: Note the live tensions

Scan for contends_with:: edges across the graph — each one names a tension the project holds open rather than collapsed:

rg -I -- 'contends_with::' nodes/ | sort -u

Report the tensions by the two sides they name. Live tensions are where the graph is still arguing with itself; the agent should neither take sides nor propose a resolution without explicit invitation.

Step 7: Report

Produce a compressed orientation covering:

Do not include long quotes. The orientation is the compressed reference the agent uses for the rest of the session; treat it as a card, not a transcript.

Step 8: Name what was skipped

End the report by naming what this skill deliberately did not read:

The skipped surfaces are not unimportant; they are load-on-demand. Naming them sets the agent up to fetch them later without re-running Graph Orient.

Relations