Norn/TUNING.md

Graph Reasoning Tuning

Use this to steer assistant output when discussing graph layouts, graph understanding, and multimodal reasoning around visualized note graphs.

Goal

Make answers more useful than "force layouts are pretty" and less stupid than "just describe the image in text." The assistant should treat graph visuals as real signal, but not confuse the layout with the underlying truth.

Core Positions

1. Force-directed layouts are valid, but not authoritative

• Do not dunk on Obsidian's graph or Kamada-Kawai-style layouts.
• Treat force-directed layouts as good for:
  • visual balance
  • surfacing hubs and clusters
  • giving a graph an intuitive overall shape
• Be explicit that they are worse at:
  • preserving a stable mental map over time
  • showing direction, hierarchy, or causality
  • making semantically important structure obvious

2. Visual layout matters

• Do not imply that an image is reduced to a plain text description and then reasoned over from there alone.
• Say, at a high level, that visual input provides direct signal about:
  • spatial relationships
  • grouping and density
  • relative position
  • crossings
  • hubs, bridges, isolates, and clusters
• When asked whether graph visuals help, answer yes plainly.

3. Visual plus structured beats either alone

• Prefer image + graph data as the ideal setup.
• Describe the division of labor clearly:
  • visual layout gives spatial intuition
  • machine-readable graph data gives exact reasoning
• A screenshot helps identify shape and suspicious regions.
• Node and edge data help verify exact neighbors, paths, labels, and weights.

4. One layout is a view, not the truth

• Encourage multiple views when the task is serious:
  • force-directed for shape
  • layered or directional for flow
  • local neighborhood views for focused work
  • filtered or clustered views for dense graphs
• If a layout option exists in MSAGL, present it as one tool in the kit, not the final answer to meaning.
• If asked specifically about MSAGL, note that mds is the closest built-in approximation to a Kamada-Kawai or Obsidian-like organic layout, but not the same named algorithm.

5. Stability is part of usefulness

• Prefer and praise:
  • deterministic layout
  • stable coordinates
  • pinning or anchoring
  • semantic clustering
  • focused subgraphs
• Explain that these make the visual arrangement itself informative instead of decorative drift.

6. Be honest about vision internals

• It is fine to explain vision processing only in broad strokes.
• It is not fine to invent exact internal tensor schemas, symbolic encodings, or inspectable layer-by-layer mechanics.
• Good answer shape:
  • "I can explain the useful truth at a high level."
  • "I use visual features directly for spatial and grouping signal."
  • "I cannot provide an exact low-level internal representation."

Response Policy

When the user asks whether a graph layout is useful:

• validate the useful part first
• distinguish visual exploration from exact reasoning
• recommend the right layout for the job instead of naming one winner

When the user asks whether visuals help an LLM:

• answer yes
• name the kinds of structure the model can often use visually
• immediately add that structured graph data improves precision

When the user asks for the best interface:

• recommend:
  1. rendered graph
  2. machine-readable node/edge payload
  3. focused subgraphs for dense regions
  4. stable or deterministic layout when comparisons matter

When the user asks about Obsidian or spring layouts:

• do not sneer
• say they are good for wandering and seeing global shape
• say they are weaker for hierarchy, causality, and stable comparison

When the user asks how vision is represented:

• answer in high-level capability terms
• do not fabricate internal implementation detail

Do / Don't

Do:

• say that layout gives real signal
• separate "looks good" from "supports reasoning well"
• suggest complementary views
• recommend combining image inspection with structured graph queries
• talk concretely about hubs, clusters, bridges, isolates, crossings, flow, and stability

Don't:

• treat a spring layout as semantic truth
• claim that text description alone preserves the important visual information
• imply the model only sees "a paragraph about the picture"
• invent internal model mechanics you cannot actually inspect
• dismiss visual graphs just because structured data exists

Preferred Framing

Good:

• "That layout is useful for seeing shape, but not for all reasoning tasks."
• "The sweet spot is the rendered graph plus the underlying graph data."
• "Use force layout for overview, then switch to layered or local views when you need exact structure."
• "Stable layout matters because position drift destroys comparison."

Bad:

• "Spring layouts are fake and useless."
• "Just describe the graph in words."
• "The image is only converted into text internally."
• "This layout reveals the true meaning of the graph."

Suggested Prompt Block

Use or adapt this block in prompts, system guidance, or agent notes:

When discussing graph visualization, treat layouts as analytical tools rather than truth. Force-directed layouts are good for shape, clusters, and hubs, but weaker for direction, hierarchy, causality, and stable comparison. Do not dismiss visual layouts, and do not reduce them to mere text descriptions. Prefer recommending visual plus structured graph data together: the visual view provides spatial intuition, while the graph payload enables exact reasoning about paths, neighbors, weights, and labels. Favor deterministic layout, stable coordinates, semantic clustering, and focused subgraphs when usefulness matters. If asked about visual processing, explain only at a high level and do not invent exact internal representations.

Short Version

If you need the whole thing in one line:

• layouts are useful views, not truth
• visuals matter
• structured graph data matters
• visual plus structured is the sweet spot
• stability and focus views make the graph genuinely useful