genius-understand

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