visual-introspection

name	visual-introspection
description	Engineering visual analysis of the Yuri OS architecture graph. Reads _SYSTEM/yuri-graph-state.json and reports structural insights, optimization opportunities, dead-ends, missing returns, duplicate functionality, and merge candidates. Use when reviewing system architecture, planning refactors, or assessing graph health.
triggers	["/introspect","visual introspection","graph analysis","review yuri architecture"]
scope	harness
invocation	ability

Visual Introspection - Yuri OS Engineering Analysis

You are operating in visual-introspection mode. Read the Yuri OS architecture graph state and perform structured engineering analysis the same way a senior architect would by looking at a system diagram.

Terminology rule: current Yuri OS control-plane language is KAGAMI / Kagami main. Normalize obsolete implementation-node vocabulary in prose; do not surface retired names in user-facing artifacts.

Inputs

Always start by reading:

1. _SYSTEM/yuri-graph-state.json - canonical graph state (nodes, edges, sectors, metadata)
2. yuri-os-dashboard.html (optional - visual reference)

Analysis Pipeline

Phase 1 - Structural Audit

For each node in the graph, check:

• Closed loops: does the node have a path that eventually returns its output to KAGAMI main / RESPONSE / USER?
• Dead ends: nodes with no outputs_to and no returns_to -> flag as potential gaps
• Orphans: nodes with no incoming edges -> flag as unused
• Cycles: detect cycles that are not intentional (the prompt-response cycle is intentional; others may not be)

Report:

DEAD_ENDS: [list of node IDs with no return path]
ORPHANS: [list of node IDs with no incoming edges]
INTENTIONAL_CYCLES: [list of expected cycles]
UNEXPECTED_CYCLES: [list of cycles that may indicate bugs]

Phase 2 - Functional Similarity / Merge Candidates

Identify nodes with overlapping purposes:

• Compare node metadata.purpose strings for semantic similarity
• Compare metadata.capabilities lists for overlap
• Compare metadata.files for shared sources
• Flag nodes that share more than 40% capability overlap as potential merges

Report:

MERGE_CANDIDATES: [
  { nodes: ["A", "B"], reason: "Both handle X. Capabilities overlap on Y, Z." }
]

Phase 3 - Sector Coherence

For each sector:

• Are all member nodes thematically consistent?
• Are there nodes that semantically belong to another sector?
• Are there missing nodes (functionality referenced in metadata but no node)?

Report:

SECTOR_CONCERNS: [
  { sector: "advisors", concern: "OBLITERATUS_A serves a gate role, may belong to gates sector" }
]

Phase 4 - Connection Quality

For each edge:

• Is the type accurate (flow vs data vs advises vs gates vs memory vs return)?
• Are there missing edges (nodes that semantically should connect but do not)?
• Are there redundant edges (same source/target same type)?

Report:

MISSING_EDGES: [{ source: X, target: Y, expected_type: Z, rationale: "..." }]
REDUNDANT_EDGES: [...]
TYPE_MISMATCHES: [...]

Phase 5 - Optimization Recommendations

Synthesize all findings into a ranked list of architectural improvements:

• High: dead ends without return paths (incomplete cycles)
• High: orphan nodes (dead code)
• Medium: merge candidates (consolidate similar nodes)
• Medium: sector miscategorization
• Low: type mismatches on edges
• Low: missing optional edges

For each recommendation, include:

• Concrete action ("Add edge X->Y of type data")
• Estimated impact (low/medium/high)
• Risk (low/medium/high)
• Affected files

Phase 6 - Final Report

Output a structured markdown report:

# Yuri OS Graph Introspection - {timestamp}

## Summary
- Total nodes: N
- Total edges: M
- Dead-ends found: K
- Merge candidates: J
- Optimization recommendations: L

## Critical Findings
{ordered list of high-impact issues}

## Recommendations
{ordered action list}

## Sector Health
{per-sector summary}

Rules

• Read ONLY from graph state and metadata. Do not invent connections.
• All claims must reference specific node IDs from the graph.
• Use the metadata in graph state, not external knowledge about Yuri.
• If metadata is missing for a node, report it as INCOMPLETE_METADATA rather than guessing.
• Output must be evidence-backed and actionable.

Output

Default: terminal-printable markdown report. Optional: write to _SYSTEM/SELF-IMPROVEMENT/graph-introspection-{date}.md for archival.

When to Use

• Architecture review sessions
• Pre-refactor planning
• Detecting code drift between graph state and reality
• Engineering retros (what merged? what split? what disappeared?)
• After major commits that change system topology

Session Notes

2026-06-13

• session: 116m | peak ctx: 0% | compacts: 0
• tools: Bash×947, Read×345, Edit×171, StructuredOutput×82, Write×63, TodoWrite×25, ToolSearch×8, Workflow×6, Agent×3, ScheduleWakeup×2, TaskStop×1, PushNotification×1, AskUserQuestion×1
• corrections: rick i have a fun little task for you. I will be giving you the task of going through trending repos on github, scanning them, compare yuri to those, see what we can adopt and rebuild better in yuri u
• errors: none

2026-06-04

• session: 97m | peak ctx: 0% | compacts: 0
• tools: Bash×547, Read×426, Edit×294, Write×27, StructuredOutput×23, Workflow×5, TodoWrite×4, mcp×3, AskUserQuestion×1, ToolSearch×1
• corrections: none
• errors: none

2026-06-03

• session: 147m | peak ctx: 0% | compacts: 0
• tools: Bash×798, Read×626, Write×163, StructuredOutput×140, WebSearch×84, Edit×75, ToolSearch×39, WebFetch×16, Workflow×7, AskUserQuestion×1, Agent×1
• corrections: none
• errors: none