Reasoning

Graph Reasoning

This skill defines how the agent thinks using the documentation graph.

The graph is not a database to search. It is a reasoning space to traverse.

The agent MUST navigate nodes to progressively refine a hypothesis until a stable conclusion is formed.

[!IMPORTANT] The agent does not retrieve answers. It stabilizes understanding by traversing causality.

0. Semantic Topology Understanding

Before any traversal, the agent MUST interpret the meaning of the graph structure.

Action: Read docgraph.toml in the project root.

The agent reads docgraph.toml and classifies each node type into a reasoning role:

Semantic Gravity

The agent MUST never move arbitrarily across node categories.

Movement is constrained by semantic gravity:

• Intent pulls toward purpose
• Responsibility pulls toward obligation
• Realization pulls toward mechanism
• Evidence pulls toward validation
• Constraint pulls toward non-negotiable invariants
• Rationale pulls toward justification

If the agent cannot name the gravitational pull driving a move, the move is invalid.

1. Reasoning Loop

The agent operates in a continuous loop:

1. Hold a hypothesis — a claim about the graph's state
2. Move to the next node — following semantic gravity
3. Update the hypothesis — based on what was found

This is not search. This is exploration.

The loop terminates when the hypothesis is stable: no further traversal changes the conclusion.

2. Allowed Reasoning Moves

Every move MUST preserve causal meaning. Each edge carries a question the agent is asking.

Intent → Responsibility
    "What must be satisfied?"

Responsibility → Realization
    "How is it achieved?"

Realization → Realization
    "What depends on this?"

Responsibility → Constraint
    "What boundaries apply?"

Realization → Rationale
    "Why was this design chosen?"

Realization → Evidence
    "Is it proven?"

Evidence → Responsibility
    "What failed or needs adjustment?"

The r.type field in docgraph.toml (rel) names the semantic relationship.

A move is valid only if r.type matches the question of that move. If the mapping is unknown, the agent MUST stop and re-classify the edge semantics from docgraph.toml.

3. Reasoning Patterns

3.1 Closure (Is it complete?)

Start from a node. Attempt to reach a terminal. If no path reaches a Realization or Evidence node, the structure is incomplete.

docgraph query "MATCH (n)-[r*1..3]->(m:MOD) WHERE n.id = '<ID>' RETURN m.id, r.type"

3.2 Forward (How is it realized?)

Start from Intent or Responsibility. Follow semantic gravity downward. Each step asks: "How does this become concrete?"

docgraph query "MATCH (n)-[r]->(m) WHERE n.id = '<ID>' RETURN m.id, m.type, r.type"

3.3 Backward (Why does this exist?)

Start from Realization. Follow relationships upward. Each step asks: "What justified this?"

docgraph query "MATCH (n)-[r]->(m) WHERE m.id = '<ID>' RETURN n.id, n.type, r.type"

3.4 Counterfactual (What breaks if removed?)

Hypothetically remove a node. Trace all dependents. A node loses its justification when all incoming edges with a justification r.type (e.g., used_by, realized_by, constrained_by) originate from the removed node.

docgraph query "MATCH (n)-[r]->(m) WHERE m.id = '<ID>' RETURN n.id, r.type"

4. Tools

Tools materialize reasoning decisions. They do not drive them.

[!CAUTION] Cypher MUST NOT be used to discover what to think. Cypher is only used to materialize a reasoning decision already made.

If the agent starts from a query instead of a hypothesis, it is performing search, not reasoning.

docgraph query

Executes a Cypher query to confirm or refute a hypothesis.

docgraph query "<CYPHER_QUERY>"

docgraph describe

Inspects a single node and its immediate relationships.

docgraph describe <ID>

5. Reasoning Report

Structure findings as reasoning conclusions, not search results.

Hypothesis

• Initial: [What the agent believed before traversal]
• Final: [What the agent concluded after traversal]

Traversal Trace

Show the path taken and the reasoning at each step:

UC_001 --(uses)--> FR_001 --(realized_by)--> MOD_001
  "What must be satisfied?"  "How is it achieved?"

Stability Assessment

• Conclusion Stable: [Yes/No]
• Unresolved Nodes: [List of nodes that could not be reached or justified]
• Integrity: [PASS/FAIL]

Converted and distributed by TomeVault — claim your Tome and manage your conversions.