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