repo-dependency-graph

# repo-dependency-graph

Turn a skill repo (or a whole campaign package) into a clean, interactive
**use-dependency graph**: read the original `SKILL.md` + design docs, reconstruct
the real `use` edges, and render one offline HTML per repo that looks and behaves
like an Obsidian graph (force-directed, draggable, neighbourhood-highlight, HTML
hover tooltips).

This skill exists because a repo's frontmatter alone gives a broken graph — real
routing lives in prose, in `references/*-index.md`, and in same-layer escalation
handoffs. Reconstructing the true graph takes a careful read of each repo, then a
deterministic render. This skill captures both halves so the result is consistent
every time and reusable across all repos.

## The model (read `references/layer-rules.md` for the full rules)

- **5 vertex types**: `campaign` (red) · `strategy` (cyan) · `tactic` (yellow) ·
  `sop` (purple) · `references` (gray dashed, = a `.py`/`.md` helper file).
- **One edge type `use`**: `A -->|use| B` = A invokes/orchestrates B (caller → callee).
- **Layer comes from frontmatter `type:` / `layer:`** (NOT `execution:`). Infer
  from body+README only if absent, and record the reasoning.
- **Escalation = same-layer `sop → sop` use edge** (locked decision): "escalate to
  X" / "for deeper analysis use X" / "import X" are all drawn as `use` edges. Do
  NOT promote a skill's layer just to make the edge look legal — same-layer
  handoff is a first-class edge here.

## Workflow

### 1. Read the repo and reconstruct the dependencies

For each `skills/*/SKILL.md`: read the **full body + frontmatter** (layer field,
and any prose that invokes/escalates to another skill or points at a
`references/` helper). Also read `README.md`, `docs/`, `assets/`, and any
`*-index.md` — real routing often lives there, not in frontmatter.

Only draw an edge the design files actually justify. If two skills are
independent siblings, leave them unconnected — do not invent edges. A pointer to
an external MCP tool (`alphaxiv`, `brave`) is a tool, not a vertex. A broken /
never-used file pointer does not justify a `references` vertex — verify the live
reference.

**For a large package (50+ skills), dispatch one subagent per package** to read
its `skills/` + `docs/` and return the reconstructed nodes/edges — they are
independent and parallelize cleanly. Give each subagent `references/layer-rules.md`
and `references/graph-schema.md` so its output is consistent and directly usable.

### 2. Write the graph JSON

Emit one JSON file per repo following `references/graph-schema.md`:

```json
{
  "name": "<repo-name>",
  "nodes": [ {"id": "<full-skill-name>", "layer": "sop", "desc": "<bilingual hover>"} ],
  "edges": [ {"from": "...", "to": "...", "tip": "<trigger scenario hover>"} ]
}
```

- **Node IDs are full skill names — never abbreviate.**
- `desc` (中英混合) = what the SKILL does + its depth / HARD-GATE. HTML allowed.
- `tip` = the condition under which the caller hands off to the callee; quote the
  source skill's own escalation language where possible. HTML allowed.
- Both `desc` and `tip` are optional — omit and the tooltip falls back to
  `name [layer]` / `use`.

### 3. Render the HTML

```
python scripts/render_graph.py --data <repo>.json --out <repo>.html
# or batch a whole directory of graph JSONs:
python scripts/render_graph.py --data-dir ./data --out-dir ./graphs
```

The script prints a `[warn]` for any edge that breaks layer legality
(`sop → sop` escalation never warns). It produces a fully offline HTML
(vis-network inlined, external CDN stripped) with:

- 5 vertex-type colors, dashed border for `references`.
- Force-directed, draggable, scroll-zoom, click-to-highlight neighbourhood.
- A self-managed `#dare-tip` hover layer that renders the HTML in `desc`/`tip`
  (vis's native tooltip shows a string title as plain text, leaking `<b>` tags —
  the script bypasses it with an event-driven layer; this is why HTML renders).
- No navigation buttons, no bootstrap card frame — just the graph on a dark canvas.

### 4. Verify

Open the HTML in a browser and confirm: nodes colored by layer, edges arrow
caller→callee, hovering a node/edge shows the bilingual tooltip with HTML
rendered (bold + `<hr>` divider, not raw tags). Requires `pyvis` (>=0.3.2).

## Key constraints

- **HTML directly, no intermediate mermaid `.md`.** The HTML is the deliverable.
- **Full skill names** as node IDs and labels — no abbreviations.
- Privacy: the HTML embeds only node names + layer + the desc/tip you write. Never
  emit filesystem paths, log paths, or session IDs into the graph data or output.
- Read-only on the source repo — reconstructing a graph never edits skills.

See `examples/literature-engine.json` for a complete, working graph JSON.