genius-understand

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 ..).

1. Resolve PLUGIN_ROOT (echo "$CLAUDE_PLUGIN_ROOT") and PROJECT_ROOT (pwd).
2. Set today (YYYY-MM-DD) and a relative runDir in the current project: genius-runs/<today>_understand.
3. 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).
4. If the result is { park: ... }, report the reason and stop.
5. Persist immediately (before presenting to the user). Write TWO files under <runDir>/:
   • understand-map.json — the raw returned object { map, critique, facet_summaries } as JSON.
   • understand-map.md — a human-readable rendering with sections:

     # Project map: <map.project>
     **Goal:** <map.goal>
     **Success metric:** <map.success_metric>
     **Current state:** <map.current_state>
     
     ## Technical routes
     | Route | Status | Note |
     |-------|--------|------|
     <one row per map.technical_routes entry>
     
     ## Core blocker
     <map.core_blocker>
     
     ## Leverage points (candidate sub-problems for /genius-focus)
     <map.leverage_points as a numbered list>
     
     ## Open questions
     <map.open_questions as a numbered list>
     
     ## Computable for EVOLVE
     <map.computable_for_evolve.is_computable> — <map.computable_for_evolve.note>
     
     ## Critique (adversarial pressure-test)
     **Gaps:** <critique.gaps as list> (omit section if critique is null)
     **Misread risks:** <critique.misread_risks as list>
     **Real blocker hypothesis:** <critique.real_blocker_hypothesis>
     **Recommended sub-problems:** <critique.recommended_sub_problems as list>
     

   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.
6. 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).