ideation

<what-to-do> # Ideation Transform unstructured brain dumps into implementation artifacts through a conversational interview that builds shared understanding before writing anything. HTML is for interactive decision-making (visualizations, comparisons, the contract); Markdown is for reference documents (specs, PRDs). ## Workflow ``` INTAKE → INTERVIEW LOOP → CONTRACT.HTML → PHASING → SPEC.MD GENERATION → HANDOFF ↓ ↓ ↓ ↓ ↓ Accept the mess One question Mission Repeatable? Phase track at a time, Brief with ↓ + copy buttons explore code gates + Template + in contract + show HTML scope per-phase examples tiers deltas ``` ## Phases 1-2: Interview Read and follow `${CLAUDE_PLUGIN_ROOT}/references/interview-engine.md` for the full intake and interview loop; complete every phase there before Phase 3. Read `${CLAUDE_PLUGIN_ROOT}/references/confidence-rubric.md` for the evidence-gate criteria. **Resumed project:** when the user points ideation at an existing `docs/ideation/{slug}/`, the engine's resume path runs ahead of the intake sweep (it decides which gates get interviewed at all): it reads persisted gate state and `openQuestions` from `contract-data.json`, leaves gates already `ready` alone, and interviews only the open questions whose blockers have closed. Each type dispatches to a move the engine already has: `research` to an `Agent` with `subagent_type: "Explore"` and never a question to the user, `prototype` to the spike, `decision` to an `AskUserQuestion` once the missing input exists, `task` to a checklist a human works through out of band. (Agent names differ by harness — see `${CLAUDE_PLUGIN_ROOT}/references/harness-compat.md` § 2.) ## Phase 3: Contract (HTML) When no gate can move — all 5 `ready`, or every remaining gate blocked on a written open question (or the user ended the interview) — generate the contract. The all-ready path is the only one eligible for the express finish (step 7): 1. **Name the project yourself and say so** — the interview just produced the evidence for every gate, so the name is inferable; kebab-case it into the `slug`. State it in one line (`Calling this "{name}" → docs/ideation/{slug}/`) rather than asking. The user corrects it in passing if it's wrong, and a rename here costs one `git mv` before anything references the slug. Ask only when the brain dump genuinely covers two separable projects and the split decides what gets built. 2. Create `./docs/ideation/{slug}/`. (**Resumed project:** the slug and directory already exist. Reuse both, don't re-name the project, and let the generator's lineage rules handle the re-render: a Draft is replaced in place, an Approved contract is snapshotted to `contract-{date}.html` with the supersedes link set.) 3. **Write `contract-data.json`** there. The schema is the types in `${CLAUDE_PLUGIN_ROOT}/scripts/contract-gen.ts` — read them when unsure; the generator also validates at render time and rejects a malformed file naming the exact criterion, before writing anything. Minimal shape: ```json { "projectName": "Human-Readable Name", "slug": "kebab-case-name", "date": "YYYY-MM-DD", "status": "Draft", "gates": { "dimensions": [ { "key": "problem", "label": "Problem Clarity", "status": "ready", "evidence": "One sentence citing the artifact" } ] }, "problem": ["paragraph"], "goals": ["Measurable goal"], "successCriteria": [ { "criterion": "Pass/fail criterion", "check": { "cmd": "npx vitest run src/auth", "expect": "exits 0" } }, { "criterion": "Judgment-only criterion", "check": { "judgment": "who looks at what" } } ], "scope": { "mvp": [{ "item": "Core feature", "reason": "Why it's MVP" }], "outOfScope": [{ "item": "Excluded item", "reason": "Why excluded" }] }, "decisions": [{ "decision": "What was chosen", "rejected": "The alternative", "reason": "Why it lost" }], "openQuestions": [{ "id": "idp-token-ttl", "question": "What TTL does the identity provider allow?", "gate": "criteria", "type": "research" }], "execution": { "strategy": "Sequential", "phases": [{ "title": "Phase name", "risk": "low", "blocking": true, "specPath": "docs/ideation/slug/spec-phase-1.md", "notes": "What this phase covers" }] } } ``` Semantics no schema can express: the five gate `dimensions` are exactly the rubric's gates with their canonical keys/labels (`${CLAUDE_PLUGIN_ROOT}/references/confidence-rubric.md`) — a real file carries all five, each with one-sentence `evidence`; proceed only when all 5 are `ready`, recording not-ready gates only on an early-stopped interview. Write `openQuestions` only when the interview left a gate open on work it couldn't do itself: one entry per question the engine wrote, each `gate` matching a `dimensions` key, and `blockedBy` carrying the ids of other entries, omitted entirely when the question is takeable now. A resumed interview drops the entries it closed and rewrites that gate's evidence to cite what closed them. An open question never marks a gate `ready`; it is the reason the gate is open. **`check` is a union**: `{cmd, expect}` whenever a command can verify the criterion — `scripts/verify.mjs` executes every `cmd` at acceptance time — or `{judgment}` naming who looks at what (rendered with a visible "judgment call" tag, printed but never counted by verify; the success-criteria critic challenges any judgment where a command is plausible). Never author the legacy plain-string check form. Record each `decisions` entry **at the moment** the user rejects an alternative, not reconstructed later; `rejected` is optional when no concrete alternative was on the table. `scope.full`/`stretch`/`future` and `supersedes` are optional; phase fields also allow `kind: "gate"` (human checkpoint) and `prereqs` (phase titles). Two top-level fields belong to the express finish and are written only when step 7's routing chooses it: `approvalMode` (`"express"`) and `branch` (isolation branch autopilot re-asserts). `status` stays `"Draft"` here — run commands appear when Phase 5 flips it to `"Approved"`. 4. **Fan out the plan critics** (before rendering — fixing a blocker is a one-line JSON edit at this stage, not a regenerate loop). Issue all four `Agent` calls in one message so they run concurrently: `subagent_type: ideation:plan-critic`, prompt = per-invocation inputs only (`contract-data.json` path, project directory, and the **lens** — one of `scope-creep`, `over-engineering`, `hidden-dependency`, `success-criteria`); workflow/format/read-only `tools` come from the registered definition and are platform-enforced. **Agent names differ by harness** — see `${CLAUDE_PLUGIN_ROOT}/references/harness-compat.md` § 2: in pi, issue **one** `dispatch` call with four tasks, each carrying the lens in its `task`, the body of `${CLAUDE_PLUGIN_ROOT}/agents/plan-critic.md` as `systemPrompt`, and the default read-only tools. Same agent, same prompt, same lens. Act on findings: each `blocker` → revise `contract-data.json` to resolve it (re-tier a scope item, add a phase prereq, rewrite a criterion); if a blocker exposes a genuine unknown rather than a fixable defect, return to the interview loop for that gate. Each `notable` → fold in if clearly right, else carry to the digest with a one-line dismissal. `nit` → digest mention only. Every critic-blocker fix that changes the plan also appends a `decisions` entry recording what changed and what the pre-fix approach was — otherwise critic-driven revisions evaporate after the transient digest. **Failure tolerance:** a failed critic or an unregistered `ideation:plan-critic` (older Claude Code) → warn, proceed without that lens, note the gap in the digest. Critics amplify quality; never block the contract on a critic failure. **Run-once rule:** critics run exactly once per contract — re-run only if a revision changes goals or scope _fundamentally_, not for wording. The "Needs changes" approval loop does **not** re-trigger them. 5. **Run the generator** (it handles lineage — an existing **Approved** `contract.html` is renamed to `contract-{date}.html` with the supersedes link set; a Draft is replaced in place, so interview revisions and the Draft→Approved flip don't accumulate snapshots): ```bash node ${CLAUDE_PLUGIN_ROOT}/scripts/contract-gen.ts \ --input ./docs/ideation/{slug}/contract-data.json \ --output ./docs/ideation/{slug}/contract.html ``` (Plain `node` works on Node ≥ 22.18 via type stripping; `npx --yes tsx` remains a fallback on older Node — but `npx` is denied in unattended runs, so prefer `node`.) After the `Generated …` line the generator prints **`{N} criteria ({M} cmd, {K} judgment)`** — capture it; the routing steps below read this count instead of eyeballing the criteria. The generator is the **only** renderer for `contract.html`. There is no fallback template — never hand-write the contract HTML or "render it from a template" if the generator can't run. **If the command is denied by permissions** (common when the plugin root is outside the current repo — the classifier flags an out-of-repo script as untrusted code), do not work around the denial and do not hand-render — the denial message may say you "may attempt other tools to accomplish this goal"; for this step that does not apply, since any other tool means hand-authoring the contract. Instead show the user the exact command and ask them to run it themselves by typing `! node …` in the prompt, then continue once `contract.html` exists. Run the generator and `open` as **separate** Bash calls — never chained with `&&` — so a denial of one is visible and doesn't silently skip the other. 6. Open it: `open ./docs/ideation/{slug}/contract.html` (macOS) or `xdg-open` (Linux). 7. **Present the Critic digest and a contract summary, then ask for approval and routing in one call.** Only ask once `contract.html` was actually generated and opened — never ask the user to approve a contract they haven't seen. Present in the terminal, in order: - **Critic digest** — one line per lens: `found N (B blockers folded in, M notables, dismissed X — reasons)`; note any skipped lens; if all four returned SOUND, say so. - **Summary block** — counts, not tables: quote the generator's printed `{N} criteria ({M} cmd, {K} judgment)` line; then the top checks (up to 3) verbatim; then scope tier counts (`{a} MVP · {b} Full · {c} Stretch · {d} out of scope`). Do **not** render the full criteria table in the terminal — the opened contract shows every criterion with its check; point the user at it for the detail. - **Routing recommendation** — derived from the interview's evidence, with the reason named in the option description. Recommend the **express finish** when all 5 gates went ready without an early stop AND the generator's count has `cmd > judgment`; anything else, recommend **full review** and say why in one line, citing the count (e.g. "9 criteria (3 cmd, 6 judgment) — unattended verification can't certify them", or "the interview ended early with Scope not-ready"). The user always chooses. Then ONE `AskUserQuestion` call carrying two independent questions (when the routing answer was pre-committed by the `/ideation:express` alias, ask the Express finish path's run-mode question in its place, keeping the one consolidated confirmation): ``` Question 1: "Which scope tier should we target?" Options: - "Full (Recommended)" - Build MVP + Full tiers - "MVP" - Ship the minimum viable version first - "Stretch" - Include MVP + Full + Stretch tiers Question 2: "Approve the contract — and how should we finish?" Options: - "Approve — express finish" - One-pass finish: specs generate with no further approval questions and execute immediately on an isolation branch. {reason, when recommended} - "Approve — full review" - Interactive review continues: spec approval, then the handoff menu. {reason, when recommended} - "Needs changes" - Some parts need revision before approving ``` **Early-stopped interview:** when the user ended the interview with not-ready gates, **omit** the express-finish option entirely — don't merely de-recommend it. The full path records not-ready gates for a human to weigh during review; an express finish would implement a known-unresolved gate headlessly. A contract carrying `openQuestions` is omitted the same way — an open question exists only where a gate is open. Say what that gate now holds (the open questions naming what would close it, plus what each one waits on) and how to pick it up: point ideation at `docs/ideation/{slug}/` and the interview resumes on the open questions alone. Open questions are contract-level state read at review; they do not travel into specs. The approved tier determines what goes into specs; items outside it move to "Future Considerations". **If "Needs changes":** revise (fundamental misunderstanding → back to the interview loop; otherwise edit `contract-data.json`, re-run the generator, re-open) and re-ask both questions, iterating until approved. **Do not proceed until explicitly approved.** On "Approve — full review", continue to Phase 4. On "Approve — express finish", follow the **Express finish** path below. ### Express finish The fast path chosen at step 7 (or pre-committed by the `/ideation:express` alias). It deletes the remaining approval ceremony, never the artifacts: contract, specs, `contract.html`, and `contract.md` are all still written — the express finish changes _when_ a human reads them, not whether they exist. State alongside the run-mode question, not as more questions: execution commits to branch `ideation/{slug}`, and this is the **last artifact approval** — what remains are execution-time gates only (autopilot's failure gate, or execute-spec's escalations in a single-phase watch run), or nothing until completion on the walk-away path. 1. **Clean-tree check — at routing time, not before the interview.** Run `git status --porcelain`. The user's uncommitted changes would otherwise ride along on phase commits. Dirty tree → ask via `AskUserQuestion`: they stash/commit first, they accept the risk, or they abort. A clean tree proceeds silently. (The `/ideation:express` alias runs this check at intake instead — don't repeat it here.) 2. **Mark the contract express.** In `contract-data.json`, set `"approvalMode": "express"` and `"branch": "ideation/{slug}"` (autopilot re-asserts this checkout on every entry, so the isolation guarantee survives fresh sessions), and apply the chosen tier. 3. **Run mode** — one `AskUserQuestion` (skip if it was already folded into step 7's call by the alias). Which option carries `(Recommended)` comes from the advisor, never from this file — run `node ${CLAUDE_PLUGIN_ROOT}/scripts/verify.mjs ./docs/ideation/{slug}/contract-data.json --advise` and follow § 5.4's rule for reading it, including the two session-level overlays it can't see: - "Watch it run" — execute now; execution-time gates stay interactive. - "Start it and walk away" — emits a `/goal` wrapper to paste. **Omit** this option when the advisor reports `watch` for a verifiability reason (judgment-dominant criteria, or mostly file-inspecting checks) — a walk-away run can only trust what `scripts/verify.mjs` mechanically verifies, and would complete phases nothing checked. A `watch` caused by a high-risk phase is a recommendation, not an exclusion: keep the option, and say which phase drove it. - "Just generate the artifacts" — full generation, then no branch and no execution: hand off exactly per 5.4. The contract keeps `approvalMode: "express"` and `branch`, so a later `/ideation:autopilot` run still gets the isolation branch and strict semantics. 4. **Generate everything (no loops).** Run 4.2's phasing (small-project shortcut, template + delta for repeatable phases; skip PRDs entirely), then 4.4's specs — same templates and disciplines. The Spec Feedback Quality self-review (4.5) is a **hard gate** here, not a presentation note: Weak → fix before proceeding; there is **no spec approval question** — no human reviews these specs before execution. Then 5.1/5.2: orchestration analysis, `"status": "Approved"` (keep `approvalMode` and `branch` — provenance and isolation: no per-artifact human review happened), execution plan populated, and the 5.2 re-render emitting `contract.html` and `contract.md` together. **Permission denial does not block the express finish:** print the exact `! node …` command so the user can render the record whenever they like, note the skipped render, and continue — execution consumes `contract-data.json` and `contract.md`, not the HTML. If it did render, open it for ambient visibility, not approval. Skip 5.4's menu. **"Just generate the artifacts" stops here:** hand off per 5.4 (echo the per-phase and autopilot commands); the remaining steps do not run. 5. **Isolation branch.** Re-check the tree: changes **outside** `docs/ideation/{slug}/` are foreign (the artifacts just written are expected, and untracked files travel with `git switch`) — foreign changes mean the user worked mid-flow: stop and ask, same options as the clean-tree check above. Then create or switch (**watch routes**; on walk-away the `/goal` carries the branch clause itself — `contract-gen`'s `buildGoal` includes it when the contract has `branch` — so running the switch here too is a harmless re-assert): - **Branch doesn't exist:** `git switch -c ideation/{slug}`. - **Branch exists:** check it for prior phase commits (`git log --oneline ideation/{slug} -F --grep="docs/ideation/{slug}/"` — phase commit bodies carry the slug-qualified spec path, so this fixed-string match doesn't false-positive on commits that merely mention the project). None → switch and proceed. Some → this is either a resume or a stale run; ask (`AskUserQuestion`): "Resume" (switch; autopilot's pre-pass skips committed phases), "Fresh run" (`git branch -D ideation/{slug}`, then create anew), or "Abort". A walk-away re-entry (no interactive user) defaults to Resume — that path's intended semantics. - Every phase commits here. Post-run review is the branch diff; a bad run is **deleted, not reverted** — autopilot's git-log skip pre-pass matches commit messages, so _reverted_ phase commits still register as complete on a re-run. 6. **Dispatch** by phase count and run mode: - **Single phase, watch:** orchestration adds nothing (5.4) — read and follow `${CLAUDE_PLUGIN_ROOT}/skills/execute-spec/SKILL.md` with the single spec path `docs/ideation/{slug}/spec.md` (the small-project shortcut emits a bare `spec.md`, no phase number), interactively, with **one override**: on reviewer failure/empty/no verdict, do NOT use the validation-only fallback — escalate via `AskUserQuestion` ("Retry review" / "Commit with validation only" / "Abort, leave unstaged"). That fallback is calibrated for human-reviewed specs; this spec had none.