research

/quasar-graph:research

Answer a natural-language question — or trace a pasted error — by reading the real source code of the relevant projects, using a backend graph as the router: the graph supplies the connections (edges) and the paths (projectPath, repoUrl) needed to scope and locate the code.

This is the read-side counterpart to scan: scan builds the map, research navigates it into the code. It is read-only w.r.t. the graph — it never calls build_graph / push_graph / write_node_manifests / create_graph / pull_graph and writes nothing under .quasar-graph/. The only things it may change on disk are syncing relevant repos under base_dir — cloning the missing ones and fast-forward-pulling the already-present ones (Phase 1, after one confirmation) — and the saved base_dir in ~/.quasar-graph/config.json. It requires the quasar-graph MCP server (the graph lives on the backend — there is no offline mode).

Conventions

Read references/conventions.md at the quasar-graph plugin root before acting. It defines the action vocabulary this skill is written in (dispatch a sub-agent, load a skill, selection prompt, …) with its per-harness degradations, the selection UI rules, the login retry flow, and the repo identity & binding cache rules.

In this skill every gate (Research the current project's graph, Search all <N>, Sync & research) is a fixed-choice selection prompt; an empty backend list means report and stop; free-form inputs (the base_dir path, the research query) stay plain text.

Phase 0 — Bind graph

Goal: choose the backend project + graph, load the graph into context (NOT to disk), and resolve a local base_dir for rebasing project paths.

This runs in the main thread via the bundled quasar-graph MCP server.

1. Confirm the quasar-graph MCP tools are available. If not, report: Research needs the quasar-graph MCP server (the graph lives on the backend). Enable it and retry. Then stop.
2. Authentication. On a Not authenticated with the quasar-graph backend failure, run the login retry flow from the conventions file. If it still fails, stop (research has no offline mode).
3. Working-directory shortcut. Before asking anything, try to resolve the directory research was invoked from to a graph it is already bound to:
   1. Run git remote get-url origin there; no git remote → skip to step 4. Normalize the URL with the graph's own rules ("Repo identity & binding cache" in the conventions file).
   2. Read the binding cache ~/.quasar-graph/cache/bindings.json (shape and ownership in the conventions file — research only reads it, never writes). Missing file or no entry under the normalized URL → skip to step 4.
   3. Dedupe the matched entries by graph_id. One graph → ask with a selection prompt whether to research it (Research the current project's graph, listed first, naming the bound node_name / Pick another project). Several graphs → offer one option per graph the same way (label = node_name + a graph identifier, following the selection UI rules) plus a final Pick another project option.
   4. On accept, capture that entry's project_id and graph_id and continue at step 6 — steps 4–5 are skipped. If step 6's get_graph then fails (stale cache — the graph is gone), fall back to step 4 and leave the cache untouched. On Pick another project, continue with step 4.
4. Call list_workspaces and list_projects. Ask which project to research using the selection UI rules (incl. workspace labeling). If empty, report there are no projects on the backend and stop. Capture project_id.
5. Call list_graphs with project_id. If the list is empty, report that this project has no graphs on the backend (suggest running /quasar-graph:scan first) and stop. Otherwise ask which graph the same way; show name / nodes_count / scanned_at per option. Capture graph_id.
6. Call get_graph with graph_id. Keep the returned graph (nodes[], edges[]) in context only — do NOT write it to disk (that is pull_graph's job, and research does not use it).
7. Ask for the local base_dir (plain text). Default: the saved base_dir from ~/.quasar-graph/config.json if present, else ~/Projects; resolve ~ to an absolute path via $HOME (run echo $HOME if needed). After the user confirms, if the absolute path differs from the stored value, write it back to that config (create the file and its directory if missing; preserve any other keys). Do not create base_dir now. This rebases each node's relative projectPath (abs = join(base_dir, projectPath)).