AppleDev879/ramp-claude-skill

ramp

Turn a topic in an unfamiliar repo into an interactive map: grouped nodes, labelled edges, a click-through detail panel, and a numbered walkthrough that traces the real runtime sequence.

The pipeline is deliberately split. A static pass finds which code matters, you decide what it means, and a renderer draws it. Skipping the static pass and free-reading the repo is slower and misses files; skipping your pass produces a call graph nobody learns anything from.

Workflow

1. Scan

node ~/.claude/skills/ramp/scripts/scan.js <repo> --topic "<topic>" --max 30 --out /tmp/scan.json

Paths are absolute because you will be running from the target repo, not from here.

Run it with no --topic first if you don't yet know the repo's shape — that prints an overview with language mix, biggest directories, and the most-imported files (hubs), which is usually enough to pick a good topic.

The topic scan returns ranked nodes (files, with score, matched terms, and extracted defs) plus edges between them. seed: true marks a direct topic match; the rest arrived by graph expansion and are the callers and callees that complete the picture.

If it returns nothing, the topic terms don't appear in the code. Try the vocabulary the codebase uses rather than the vocabulary the user used.

2. Read

Read the seed files, and any expanded node with a suggestive name. Read them properly — the map's whole value is the explanation, and you cannot write a useful detail from a file listing.

While reading, hunt specifically for:

• the entry point — where does this flow start at runtime?
• the non-obvious — the guard that prevents a bug, the config flag that does the real work, the thing that would surprise a newcomer
• the actual sequence — what calls what, in what order, at runtime

3. Model

Write a model JSON (schema below). This is the part that takes judgment.

4. Render

node ~/.claude/skills/ramp/scripts/render.js /tmp/model.json -o /tmp/<repo>-<topic>.html

It validates strictly and refuses to render a broken model — unknown node ids in edges, duplicate ids, dangling walkthrough refs. Warnings about unexplained or orphaned nodes are worth fixing rather than ignoring.

5. Publish

Publish the rendered file with the Artifact tool and give the user the link. Do not load artifact-design first — the template is already designed; publish it as-is.

Model schema

{
  "title": "Sign-in Flow",
  "repo": "my-app",
  "summary": "One or two sentences: the shape of the thing, and the single most useful fact about it.",
  "groups": [{ "id": "boot", "label": "App boot", "hint": "optional tooltip" }],
  "nodes": [{
    "id": "provider",
    "label": "AuthProvider",
    "group": "provider",
    "role": "Owns session state",
    "detail": "The paragraph a newcomer actually needs.",
    "files": ["src/context/AuthContext.jsx:12"],
    "symbols": ["AuthProvider", "signInWithGoogle"]
  }],
  "edges": [{ "from": "provider", "to": "supabase", "label": "getSession, OAuth" }],
  "walkthrough": [{ "node": "provider", "text": "What happens at this step." }]
}

groups are columns, left to right, in dependency order — entry points on the left, primitives on the right. Edges are drawn from importer to imported, so a model whose groups follow that order lays out cleanly. Up to six groups get distinct colors.

walkthrough is optional but it is the feature that teaches. Order it by runtime sequence, not file structure. A node may appear more than once — flows loop back, and showing that is the point.

What separates a good map from a useless one

Nodes are concepts, not files. Two files that are one idea (AuthContext.jsx + AuthContextValue.js) can be one node; a file holding two unrelated responsibilities can be two. Put every real file in files regardless.

6–14 nodes. A map with 40 nodes is the hairball the user was already staring at. Cut to what carries the flow — the scan's score ordering tells you what to keep. Say what you left out in the summary.

role is a job, not a restatement. "Owns session state" — not "Auth provider component".

detail earns the click. Put the thing that isn't obvious from the name: why it's split this way, the flag that matters, the failure it prevents, the assumption it makes. If a detail only paraphrases the label, delete the node or find out what it really does.

Label every edge with the actual relationship — "gates on user", "getSession, OAuth" — not "uses" or "imports".

Cite lines. path/to/file.ts:42 in files points the reader at the exact spot.

Say what's load-bearing and what isn't. A newcomer most needs to know which parts they can ignore.

Notes

• The scan is zero-dependency Node and needs no install. It respects .gitignore when the target is a git repo.
• Swift, and same-package Java/C#, have no file-level imports; for those the scan infers edges from unique type references instead. Treat those edges as strong hints rather than certainties.
• Import resolution is regex-based, not a type checker. It resolves relative paths, bundler aliases (@/), and package-style specifiers by path suffix. Dynamic and generated imports are missed — if a file you expect is absent, add it to the model yourself.