ln-022-researchgraph

Paths: File paths are relative to this skill directory.

Research Graph

Type: Standalone Utility Category: 0XX Dev Environment

Indexes and queries canonical project research files through hex-research-mcp: hypotheses, goals, tasks, sources, source library entries, benchmark run manifests, evidence links, derived goal metrics, lineage, generated research maps, and audit gaps.

Mandatory Read

MANDATORY READ: Load references/researchgraph_mcp_usage.md

Inputs

| Input | Required | Source | Description | |-------|----------|--------|-------------| | project_path | yes | args or CWD | Project root containing research graph files | | command | no | args | Specific action: audit, inspect H##, goal G##, runs, evidence, lineage, progress, proposed, canvas |

When to Use

Use this skill when the project has any of:

• docs/hypotheses/*.md
• docs/goals/*.md
• benchmark/runs/*/manifest.yaml

Use it when the user asks about research status, live or pending hypotheses, goal readiness, benchmark evidence, source quality, evidence depth, proposal readiness, implementation gaps, drift, field-level changes, or a visual/generated research map.

Do not use this skill for code symbol ownership, call graphs, references, or edit blast radius. Use ln-021-codegraph or host hex-graph policy for semantic code questions.

MCP Availability

Use hex-research when available. If unavailable, manually read the split research files with Glob/Grep/Read, answer from direct file evidence, and mark confidence as degraded.

Treat STALE as actionable graph debt or missing project metadata, not as a tool failure. Treat INVALID from verify_index as diagnostic unless a write/index operation fails.

Workflow

Phase 1: Detect Graph Layout

Check for the canonical layout:

• docs/hypotheses/*.md
• docs/goals/*.md
• benchmark/runs/*/manifest.yaml

If none exist, stop and report that the project does not expose a research graph yet. Do not invent hypotheses or goals.

Phase 2: Verify or Index

Start read-only:

verify_index({ path: "{project_path}" })

Rebuild only when the index is missing, stale, explicitly requested, or the task requires current graph state:

index_hypotheses({ path: "{project_path}" })

The local index is stored under .hex-skills/researchgraph/ in the target project.

Phase 3: Route Intent

| User intent | Tool | |-------------|------| | live, pending, rejected, mixed, not-started hypotheses | find_hypotheses | | inspect H## | inspect_hypothesis | | inspect G## or goal status | inspect_goal | | evidence, sources, benchmark proof | find_evidence | | targeted or comprehensive benchmark runs | find_runs | | parent/child hypothesis chain | trace_lineage | | graph hubs, disconnected nodes, shape | analyze_topology | | missing goals, sources, task gaps, drift | audit_orphans | | goal tree | trace_goal_tree | | goal readiness, derived metrics, and metric coverage | inspect_goal, audit_goal_alignment | | source quality or evidence depth | inspect_hypothesis, find_evidence, analyze_proposed | | changed research files and field-level deltas in current diff | analyze_progress | | readiness of proposed next hypotheses | analyze_proposed | | JSON Canvas export | export_canvas | | generated docs/research-map.md export | export_research_map |

Phase 4: Present Results

Report:

1. tool status (OK, STALE, INVALID, ERROR)
2. key hypotheses/goals/runs with IDs
3. actionable graph debt separately from tool failures
4. follow-up tool calls when the graph points to a narrower next question

For export_canvas and export_research_map, run dry-run first. Write only after dry-run output is useful and the user requested the file. Treat split files as canonical; generated research-map.md is not a second manual source of truth.

Manual Fallback

When MCP is unavailable:

1. Read docs/goals/.md and docs/hypotheses/.md frontmatter first.
2. Read benchmark/runs/*/manifest.yaml only after narrowing by H/G IDs or status.
3. Prefer exact IDs (H04, G1) over broad scans.
4. State that lineage, topology, and drift findings are manual approximations.

Definition of Done

• [ ] Graph layout detected or absence reported
• [ ] Index verified or rebuilt when needed
• [ ] User intent routed to the smallest relevant tool
• [ ] STALE / graph debt separated from MCP/tool failure
• [ ] Manual fallback confidence stated when MCP was unavailable
• [ ] Canvas writes use dry-run before write

Version: 0.1.0 Last Updated: 2026-05-08