| name | genius-understand |
| description | Use when the user runs /genius-understand or asks GENIUS to map/diagnose the current project. Runs the bundled understand workflow and presents the grounded map. Persists understand-map.md and understand-map.json to the runDir immediately after the workflow returns. |
GENIUS — understand (project mapper)
Plugin paths. This is a globally-installed plugin; bundled files live under the plugin root, NOT
the current working directory. Resolve the absolute plugin root once: echo "$CLAUDE_PLUGIN_ROOT"
(Bash) → PLUGIN_ROOT. The current project root is the cwd → PROJECT_ROOT (pwd). runDir goes
in the user's CURRENT project as a RELATIVE path (the workflow safety guard rejects absolute paths
and ..).
- Resolve
PLUGIN_ROOT (echo "$CLAUDE_PLUGIN_ROOT") and PROJECT_ROOT (pwd).
- Set
today (YYYY-MM-DD) and a relative runDir in the current project:
genius-runs/<today>_understand.
- Launch the Workflow tool:
scriptPath: "<PLUGIN_ROOT>/workflows/understand.js",
args: { projectRoot: "<PROJECT_ROOT>", depth: "full" }. Use depth: "quick" when the user passed
--depth quick in the command (or otherwise wants a fast pass) — it skips the adversarial critique.
The full run is heavy (≈5 parallel readers + synthesis + critique, file-heavy, several minutes); it
runs in the background. If a transient error aborts it, re-launch (optionally with resumeFromRunId).
- If the result is
{ park: ... }, report the reason and stop.
- Persist immediately (before presenting to the user). Write TWO files under
<runDir>/:
Write both files BEFORE displaying anything to the user (so an interrupted session still leaves
artifacts on disk). The workflow writes nothing itself — so YOU create the directory first
(mkdir -p <runDir>) and then write the two files into it after the workflow returns.
- Present the map to the user: goal, current state, technical routes + status, core blocker,
leverage points / recommended sub-problems (these are candidate targets for
/genius-focus),
open questions, and the critique (if present). Note where artifacts live (understand-map.md,
understand-map.json).