# Post-Ideation Workflow

Read this file after Phase 2 ideation roles return and the orchestrator has merged and deduped their outputs into a master candidate list. Every dispatch instruction in this reference inherits the main Skill's Dispatch Authorization Boundary; inline/serial execution must keep the matching reason code and must not claim fresh-context or independent coverage. Do not load before Phase 2 completes.

## Phase 3: Adversarial Filtering

Review every candidate idea critically. Critique has two roles — basis verification, then orchestrator arbitration. Only authorized, capable dispatch makes the first role a fresh-context verifier; inline fallback is an orchestrator self-check with the explicit coverage limitation from the main Skill.

1. **Basis verification (generation-tier role — see SKILL.md Model Tiers).** When `worker_dispatch_authorization: authorized` and `worker_dispatch_capability: available`, dispatch a verifier whose payload is only the consolidated grounding summary (including evidence gists and dossier file paths) plus the merged candidate list, with none of the generation history. Otherwise run the same refutation rubric inline or serially, record `dispatch_authorization_missing`, `subagent_capability_missing`, or `worker_capability_unproven` according to the main Skill's boundary, and do not describe the result as independent or fresh-context. Check that each stated basis supports the move, that `direct:` quotes exist where cited, that `external:` prior art is real and relevantly analogous, that `reasoned:` arguments hold, and that the idea passes the meeting-test. A dispatched verifier returns sound/weak/refuted verdicts; only that fresh-context verdict may supersede generator self-attestation. Under `go deep`, a second ceiling-tier critic is eligible only through the same gate; inline fallback applies the second rubric serially without upgrading coverage.

2. **Orchestrator arbitration.** The orchestrator makes the final cut, weighing verifier verdicts without being bound by them — overrule a verdict when evidence in context contradicts it, and say so in the rejection reason.

If an authorized verifier dispatch fails, fall back to orchestrator-only filtering, record the capability/failure reason, and note the degradation in the rejection summary.

Do not generate replacement ideas in this phase unless explicitly refining.

For each rejected idea, write a one-line reason.

Rejection criteria:
- too vague
- not actionable
- duplicates a stronger idea
- not grounded in the stated context
- too expensive relative to likely value
- already covered by existing workflows or docs
- interesting but better handled as a brainstorm variant, not a product improvement
- **unjustified — no articulated basis** (sub-agent failed to provide `direct:`, `external:`, or `reasoned:` justification, or the stated basis does not actually support the claimed move)
- **basis refuted by verification** (the verifier found a cited quote absent, prior art mischaracterized, or a reasoned argument unsound — and the orchestrator concurs)
- **below ambition floor** (fails the meeting-test: would not warrant team discussion — except when Phase 0.5 detected tactical focus signals, in which case this criterion is waived)
- **subject-replacement** (abandons or replaces the subject of ideation rather than operating on it — e.g., "pivot to an unrelated domain," "become a different organization")
- **scope overrun** (expands beyond the asked scope rather than ideating within it — e.g., proposes changes to the whole product when the user asked about one flow, stage, or section). Allowed only when the basis explicitly justifies the expansion; default is reject or downgrade.

Score survivors using a consistent rubric weighing: groundedness in stated context, **basis strength** (`direct:` > `external:` > `reasoned:`; none excluded, but direct-evidence ideas score higher all else equal), expected value, novelty, pragmatism, leverage on future work, implementation burden, overlap with stronger ideas, and **axis spread** (when Phase 1.5 produced an axis list) — survivor sets that cover the topic's surface outscore sets that cluster on one axis, all else equal.

**Axis coverage as a list-level concern.** When axes were defined, axis spread is evaluated across the survivor set, not per-idea. After per-idea filtering, check the survivor set: if axis coverage is uneven and stronger candidates exist on under-represented axes, prefer the spread when promoting borderline candidates. Phase 2's recovery dispatch should already have surfaced candidates for empty axes; this is a polish step on the survivor selection. If an axis ends up with zero survivors despite recovery (or because recovery hit the 2-axis cap), note it in the rejection summary as a deliberate gap rather than an oversight.

Target output:
- keep 5-7 survivors by default
- if too many survive, run a second stricter pass
- if fewer than 5 survive, report that honestly rather than lowering the bar

## Phase 4: Write and Present the Deliverable

The ideation artifact is produced **automatically** — persistence is not opt-in. After filtering, write the deliverable, show a concise summary, and open it. The full content lives in the file; the session shows only an orienting summary, so the rich format is what the reader actually engages with.

**Checkpoint B (V17).** Before writing the deliverable, write `<scratch-dir>/survivors.md` (absolute path from Phase 1) containing the survivor list plus key context (focus hint, grounding summary, rejection summary). Best-effort: if the write fails, log a warning and proceed; the checkpoint is not load-bearing. Reuses the same `<run-id>` / `<scratch-dir>` generated in Phase 1.

### 4.1 Write the Deliverable (automatic, both modes)

`OUTPUT_FORMAT` (resolved in SKILL.md Phase 0.0; default `html`) sets the extension. Write the file every run — do not wait for the user to ask.

1. **Resolve the target directory and extension.**
   - Extension follows `OUTPUT_FORMAT` (`.html` default, `.md` on override).
   - **Repo mode:** ensure `docs/ideation/` exists (create if absent).
   - **Elsewhere mode with `docs/ideation/` already present:** use it.
   - **Otherwise (no repo, or elsewhere with no `docs/ideation/`):** return the complete deliverable inline and offer to write it only after the user selects a durable destination. Do **not** use run-local scratch as the only deliverable, write into an arbitrary current working directory, or create a `docs/ideation/` tree for a subject unrelated to the repo.
2. **Choose the file path:** `<dir>/YYYY-MM-DD-<topic>-ideation.<ext>` (or `<dir>/YYYY-MM-DD-open-ideation.<ext>` when no focus exists).
3. **Load the section contract and rendering reference** (deferred from Phase 0.0): read `references/ideation-sections.md` and the format-rendering reference matching `OUTPUT_FORMAT` — `references/markdown-rendering.md` for `md`, `references/html-rendering.md` for `html`.
4. **Write the document** per those references. `ideation-sections.md` defines the section contract (metadata, Grounding Context, Topic Axes, Ranked Ideas with per-idea fields, Rejection Summary); the rendering reference defines how the resolved format presents it. Content is identical across formats; only presentation differs.
   - **On write failure** (no writable path, permissions): announce the failure and offer a custom path (validate writable; create parent dirs). Never lose the survivors silently.

**Resume:** update the existing file in place, in its existing format (per SKILL.md Phase 0.1 format precedence); carry the prior ideas and rejection summary forward, adding to them rather than overwriting.

### 4.2 Present a Concise Summary (not the full deliverable)

The full cards, rationale, downsides, diagrams, and the rejection table live in the file. Do **not** reproduce them in the session — reprinting the whole deliverable as chat text defeats the rich format and leads the reader through plain text before they ever see it. Show a tight orientation instead:

- One line with counts and the path: e.g. `Wrote 7 ranked ideas (36 raw, 13 cut) across 5 axes → <absolute path>`.
- A ranked list, **one line per survivor**: `1. <Title> · <axis> · Conf <High/Med/Low> · Cx <S/M/L>`.
- The top pick called out in a sentence.
- Any axis with zero survivors noted in one line (the deliberate gap).

This ranked list doubles as the index the user references when choosing an idea in Phase 5. Terminal-only readers still get a usable view; depth is one open away.

### 4.3 Open It

- **HTML:** in an interactive session, best-effort open the file in the browser via the platform's open primitive (`open` on macOS, `xdg-open` on Linux, `start` on Windows); always print the absolute path so it can be reopened or shared. Skip auto-open in headless / pipeline runs (no interactive surface).
- **Markdown:** print the path. There is no browser-open step for Markdown; the Phase 5 menu offers only the next-step options below.

## Phase 5: Next Steps

Ask what to do next using the platform's blocking question tool: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex. Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. Free-text answers are accepted.

The deliverable already exists (Phase 4), so the menu is purely *what next* — there is no "save" step.

**Stem:** "Your ideation is saved to `<path>`. What next?"

Offer the applicable options with self-contained labels and the distinguishing word front-loaded so they stay distinct when truncated. Renumber the visible options contiguously after applying the format gate:

1. *(when `OUTPUT_FORMAT=html`)* **Open in browser** — open the saved HTML deliverable (re-open if it was already opened).
2. **Brainstorm one idea with `spec-brainstorm`** — commit a chosen idea to a requirements-only unified plan under `docs/plans/`; leaves spec-ideate. Asks which idea first.
3. **Discuss or refine the ideas first** — stay here to think across the set before committing: adjust or interrogate one idea, compare several, or combine/merge them. Asks what you want to work on.
4. **Done — keep the file and stop.**

**Adjacent nudge (prose, not a slot):** "Don't want it kept? Say 'discard' and the agent deletes the file." Handled via free text (see §5.5); it is create-only and never deletes a resumed or pre-existing doc.

If the user already named what they want to work on inline (e.g. "brainstorm the table tool", "tighten the highlighter idea", "merge the table and highlighter ideas"), skip the follow-up that asks what to work on for §5.2 / §5.3.

### 5.1 Open in Browser (html)

- **HTML — Open in browser.** (Re)open the saved file via the platform primitive where available; otherwise print the absolute path. Return to the Phase 5 menu. The HTML file is the canonical record.

### 5.2 Brainstorm One Idea

1. **Identify the idea** by number or name (skip if the user already named it). Match against the ranked list from Phase 4.2.
2. **Build a focused seed** from the idea's substance already in the orchestrator's context. Do **not** pass the whole file — wasteful and noisy (the other survivors, grounding, and rejection table are irrelevant to defining this one idea, and an HTML file carries CSS/SVG chrome). Do **not** pass only a file pointer — that forces `spec-brainstorm` to re-open and re-extract the idea the orchestrator already holds. The seed is feature-description-shaped:

   > `<title> — <description>. Basis: <basis/evidence>. Source snapshot: <commit/version/observed state, including dirty/unknown status>. Why it matters: <rationale>. Known tradeoffs: <downsides>. Evidence limitations: <stale/partial/unknown constraints>. Unverified assumptions: <assumptions or none>. Relevant rejected alternative: <one directly adjacent rejected alternative and why it lost>.`

   The basis/evidence directly feeds `spec-brainstorm`'s product-pressure-test, so it won't re-derive what we already know. Snapshot the load-bearing basis from the evidence already held by the orchestrator; if the worktree is dirty or the revision is unknown, say `dirty/unknown` rather than inventing a clean revision. When HEAD or a cited source changed after the idea was evaluated, mark that basis `stale` and keep it as a limitation — `spec-brainstorm` decides whether and how to re-ground it. Carry only one directly adjacent rejected alternative, chosen because it would change the selected idea's Product Contract; omit unrelated rejects and the complete rejection table. Preserve reasoned claims as unverified assumptions when no direct evidence supports them. If the user examined that exact tradeoff and selected the idea, append one transient settled-decision brief entry containing the decision, `user-directed` or `user-approved` class, rejected alternative, and one-line reason. Do not label an agent-ranked idea as settled. `spec-brainstorm` becomes the single durable owner by writing the accepted decision once in the Product Contract; the ideation artifact and handoff seed remain provenance inputs, not competing decision registries. Append a one-line provenance pointer: `(Seeded from spec-ideate: <path>, idea "<title>")` — it records origin and lets brainstorm pull adjacent detail if it wants, without being forced to read anything. Do not include implementation HOW or start any browser helper from the seed.
3. **Load the `spec-brainstorm` skill** with that seed. The saved file is already the record — no extra write step.

**Repo mode only:** do **not** skip brainstorming and go straight to `spec-plan` — `spec-plan` wants a brainstorm-grounded Product Contract. In elsewhere modes, ideation is a legitimate terminal state; brainstorming is optional deeper development of one idea, not a required next rung on an implementation ladder that does not exist in these modes.

### 5.3 Discuss or Refine the Ideas First

This stays in spec-ideate — no skill handoff. It is the "think across the set before committing" step, and it is a normal, expected outcome of ideation: seeing several strong candidates and wanting to deliberate is more common than instantly committing one. The orchestrator still holds the full grounding and generation context, so it can reason across every survivor — this is where that context pays off. The work here is either **single-idea** (sharpen or interrogate one) or **cross-idea** (compare, combine, or merge several); do not force the user to name a single idea before they can engage.

1. **Establish what the user wants to work on and how.** Infer from their phrasing when given; otherwise ask one open question ("What do you want to work on?") rather than assuming a single idea. The scope may be one idea, a subset, or the whole set.
2. **Route by intent:**
   - **Ask / compare** ("why High confidence?", "how does this compare to FigJam?", "which of these overlap?", "which two are closest?") — answer in conversation, grounded in the ideas' bases and the Phase 1 grounding. Spans one idea or many. **No file rewrite** unless the discussion yields a change the user wants captured.
   - **Adjust** ("smaller scope", "drop the paste-import part", "reframe around X") — revise that idea's framing, scope, or basis as discussed, then **rewrite the saved file** so the deliverable stays current.
   - **Deepen** ("expand the second-order effects") — extend an idea's analysis; capture into the file only if the user wants it kept.
   - **Combine / merge** ("merge the table and highlighter ideas", "fold 2 into 5") — synthesize the named ideas into one: write a unified title, description, and basis that draws from each source idea (carry the strongest basis forward; union their evidence). On a file rewrite, **replace the merged source entries with the single combined entry** — do not leave the originals alongside the merge — and renumber the ranked list. Re-evaluate the combined idea's axis and confidence rather than copying one source's. Note the merge in the rejection summary if a source idea effectively drops out.
3. **Rewrite only on change.** The file is rewritten only when idea content actually changes (adjust, deepen-and-keep, or merge) — Q&A and comparison alone do not churn it.
4. **Return to the Phase 5 menu.** Typically the user next brainstorms a sharpened or merged idea (§5.2), discusses more, opens it, or finishes.

### 5.4 Done

The file is already written, so there is no save step.

- **Inside a git repo:** offer to commit only the ideation doc (do not create a branch, do not push; if the user declines, leave it uncommitted).
- **Temp-area or non-repo file:** skip the commit offer.

Then narrate the path and end the session — do not return to the menu.

### 5.5 Discard (free text)

Only when the file was **created fresh this run**: delete it, confirm the deletion, and end. On a **resume** run (a pre-existing file was updated in place), do **not** delete — tell the user the existing doc at `<path>` remains and offer no destructive action. Discard is never a default; it fires only on an explicit request.

After durable outputs and any repo-backed checkpoint are confirmed, reap `<scratch-dir>` best-effort and record cleanup failure as a limitation. Its web research material and evidence dossiers are run-local only; no later invocation may depend on them, and outside a repo the complete deliverable must already have been returned inline or written to a user-selected durable destination.

## Quality Bar

Before finishing, check:

- the idea set is grounded in the stated context (codebase in repo mode; user-supplied context in elsewhere mode)
- **every surviving idea has an articulated basis** (`direct:`, `external:`, or `reasoned:`) that actually supports the claimed move — speculation dressed as ambition was rejected, with reasons
- load-bearing `direct:` bases were verified against the repo (or the supplied context) — by the generating agent's verification reads or the Phase 3 verifier — not taken on faith
- **every surviving idea passes the meeting-test** unless Phase 0.5 detected tactical focus signals that waived the floor
- **no surviving idea replaces the subject** rather than operating on it
- when Phase 1.5 produced an axis list, the survivor set spreads across axes rather than clustering on one — and any axis with zero survivors is noted as a deliberate gap in the rejection summary, not silently absent
- the candidate list was generated before filtering
- the original many-ideas -> critique -> survivors mechanism was preserved
- if sub-agents were used, they improved diversity without replacing the core workflow
- every rejected idea has a reason
- survivors are materially better than a naive "give me ideas" list
- the deliverable was written automatically in both modes (Phase 4) — to `docs/ideation/` when present, else the spec-first temp area, never the user's CWD
- the session showed a concise summary, not a reproduction of the full deliverable
- acting on an idea routes to `spec-brainstorm` (with a substance seed, not the whole file), not directly to implementation