feat(ce-ideate): mode-aware v2 ideation (#588)
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Trevin Chow
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: ce:ideate
|
||||
description: "Generate and critically evaluate grounded improvement ideas for the current project. Use when asking what to improve, requesting idea generation, exploring surprising improvements, or wanting the AI to proactively suggest strong project directions before brainstorming one in depth. Triggers on phrases like 'what should I improve', 'give me ideas', 'ideate on this project', 'surprise me with improvements', 'what would you change', or any request for AI-generated project improvement suggestions rather than refining the user's own idea."
|
||||
description: "Generate and critically evaluate grounded ideas about a topic. Use when asking what to improve, requesting idea generation, exploring surprising directions, or wanting the AI to proactively suggest strong options before brainstorming one in depth. Triggers on phrases like 'what should I improve', 'give me ideas', 'ideate on X', 'surprise me', 'what would you change', or any request for AI-generated suggestions rather than refining the user's own idea."
|
||||
argument-hint: "[feature, focus area, or constraint]"
|
||||
---
|
||||
|
||||
@@ -65,13 +65,60 @@ If continuing:
|
||||
- preserve previous idea statuses
|
||||
- update the existing file instead of creating a duplicate
|
||||
|
||||
#### 0.2 Interpret Focus and Volume
|
||||
#### 0.2 Classify Subject Mode
|
||||
|
||||
Classify the **subject of ideation** (what the user wants ideas about), not the environment. A user inside any repo can ideate about something unrelated to that repo; a user in `/tmp` can ideate about code they hold in their head.
|
||||
|
||||
Make two sequential binary decisions, enumerating negative signals at each:
|
||||
|
||||
**Decision 1 — repo-grounded vs elsewhere.** Weigh prompt content first, topic-repo coherence second, and CWD repo presence as supporting evidence only.
|
||||
|
||||
- Positive signals for **repo-grounded**: prompt references repo files, code, architecture, modules, tests, or workflows; topic is clearly bounded by the current codebase.
|
||||
- Negative signals (push toward **elsewhere**): prompt names things absent from the repo (pricing, naming, narrative, business model, personal decisions, brand, content, market positioning); topic is creative, business, or personal with no code surface.
|
||||
|
||||
**Decision 2 (only fires if Decision 1 = elsewhere) — software vs non-software.** Classify by whether the *subject* of ideation is a software artifact or system, not by where the individual ideas will eventually land. If the topic concerns a product, app, SaaS, web/mobile UI, feature, page, or service, it is **elsewhere-software** — even when the ideas themselves are about copy, UX, CRO, pricing, onboarding, visual design, or positioning *for that software product*. **Elsewhere-non-software** is reserved for topics with no software surface at all: company or brand naming (independent of product), narrative and creative writing, personal decisions, non-digital business strategy, physical-product design.
|
||||
|
||||
Sample classifications:
|
||||
|
||||
- "Improve conversion on our sign-up page" → elsewhere-software (the subject is a page)
|
||||
- "Redesign the onboarding flow" → elsewhere-software (the subject is a flow)
|
||||
- "Pricing page A/B test ideas" → elsewhere-software (the subject is a page)
|
||||
- "Features to add to our note-taking app" → elsewhere-software
|
||||
- "Name my new coffee shop" → elsewhere-non-software (the subject is a brand)
|
||||
- "Plot ideas for a short story" → elsewhere-non-software (the subject is a narrative)
|
||||
- "Options for my next career move" → elsewhere-non-software (the subject is a personal decision)
|
||||
|
||||
State the inferred approach in one sentence at the top, using plain language the user will recognize. Never print the internal taxonomy label (`repo-grounded`, `elsewhere-software`, `elsewhere-non-software`) to the user — those names are for routing only. Adapt the template below to the actual topic; pick a domain word from the topic itself (e.g., "landing page", "onboarding flow", "naming", "career decision") instead of a mode label.
|
||||
|
||||
- **Repo-grounded:** "Treating this as a topic in this codebase — about X. Say 'actually this is outside the repo' to switch."
|
||||
- **Elsewhere-software:** "Treating this as a product/software topic outside this repo — about X. Say 'actually this is about this repo' or 'actually this has no software surface' to switch."
|
||||
- **Elsewhere-non-software:** "Treating this as a [naming | narrative | business | personal] topic — about X. Say 'actually this is about a software product' or 'actually this is about this repo' to switch."
|
||||
|
||||
The correction hints must also be plain language ("actually this is outside the repo", "actually this is about this repo"), not internal labels ("actually elsewhere-software").
|
||||
|
||||
**Active confirmation on ambiguity (V16).** When classifier confidence is low — single-keyword or short prompts mapping cleanly to either mode (`/ce:ideate ideas`, `/ce:ideate ideas for the docs`), conflicting CWD/prompt signals, or topic mentioning both repo-internal and external surfaces — ask one confirmation question via the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini) **before dispatching Phase 1 grounding**. For clear cases the one-sentence inferred-mode statement is sufficient; do not ask.
|
||||
|
||||
Sample wording (refine to fit the prompt at hand; follow the Interactive Question Tool Design rules in the plugin AGENTS.md — self-contained labels, max 4, third person, front-loaded distinguishing word, no leaked internal mode names):
|
||||
|
||||
- **Stem:** "What should the agent ideate about?"
|
||||
- **Options:**
|
||||
- "Code in this repository — features, refactors, architecture"
|
||||
- "A topic outside this repository — business, design, content, personal decisions"
|
||||
- "Cancel — let me rephrase the prompt"
|
||||
|
||||
If the user confirms or selects "elsewhere," still run Decision 2 to choose between elsewhere-software and elsewhere-non-software.
|
||||
|
||||
**Routing rule.** When Decision 2 = non-software, still run Phase 1 Elsewhere-mode grounding (user-context synthesis + web-research by default; skip phrases honored). Learnings-researcher is skipped by default in this mode — the CWD's `docs/solutions/` rarely transfers to naming, narrative, personal, or non-digital business topics; see Phase 1 for the full rationale. Then load `references/universal-ideation.md` and follow it in place of Phase 2's software frame dispatch and the Phase 6 menu narrative. This load is non-optional — the file contains the domain-agnostic generation frames, critique rubric, and wrap-up menu that replace Phase 2 and the post-ideation menu for this mode, and none of those details live in this main body. Improvising from memory produces the wrong facilitation for non-software topics. Do not run the repo-specific codebase scan at any point. The §6.5 Proof Failure Ladder in `references/post-ideation-workflow.md` still applies — load and follow it whenever a Proof save (the elsewhere-mode default for Save and end) fails, so the local-save fallback path stays reachable in non-software elsewhere runs.
|
||||
|
||||
If any prompt-broadening or intake step (0.4 below) materially changes the topic, re-evaluate the mode statement before dispatching Phase 1 — classify on the scope to be acted on, not the scope at first read.
|
||||
|
||||
#### 0.3 Interpret Focus and Volume
|
||||
|
||||
Infer three things from the argument:
|
||||
|
||||
- **Focus context** - concept, path, constraint, or open-ended
|
||||
- **Volume override** - any hint that changes candidate or survivor counts
|
||||
- **Issue-tracker intent** - whether the user wants issue/bug data as an input source
|
||||
- **Issue-tracker intent** - whether the user wants issue/bug data as an input source. **Repo-mode only** — do not trigger in elsewhere mode.
|
||||
|
||||
Issue-tracker intent triggers when the argument's primary intent is about analyzing issue patterns: `bugs`, `github issues`, `open issues`, `issue patterns`, `what users are reporting`, `bug reports`, `issue themes`.
|
||||
|
||||
@@ -80,7 +127,7 @@ Do NOT trigger on arguments that merely mention bugs as a focus: `bug in auth`,
|
||||
When combined (e.g., `top 3 bugs in authentication`): detect issue-tracker intent first, volume override second, remainder is the focus hint. The focus narrows which issues matter; the volume override controls survivor count.
|
||||
|
||||
Default volume:
|
||||
- each ideation sub-agent generates about 8-10 ideas (yielding ~30 raw ideas across agents, ~20-25 after dedupe)
|
||||
- each ideation sub-agent generates about 6-8 ideas (yielding ~36-48 raw ideas across 6 frames in the default path, or ~24-32 across 4 frames in issue-tracker mode; roughly 25-30 survivors after dedupe in the 6-frame path and fewer in the 4-frame path)
|
||||
- keep the top 5-7 survivors
|
||||
|
||||
Honor clear overrides such as:
|
||||
@@ -91,11 +138,46 @@ Honor clear overrides such as:
|
||||
|
||||
Use reasonable interpretation rather than formal parsing.
|
||||
|
||||
### Phase 1: Codebase Scan
|
||||
#### 0.4 Light Context Intake (Elsewhere Mode, Software Topics Only)
|
||||
|
||||
Before generating ideas, gather codebase context.
|
||||
Skip this step in repo mode (Phase 1 grounding agents do the work) and in non-software elsewhere mode (the universal facilitation reference governs intake).
|
||||
|
||||
Run agents in parallel in the **foreground** (do not use background dispatch — the results are needed before proceeding):
|
||||
Apply the **discrimination test** before asking anything: would swapping one piece of the user's stated context for a contrasting alternative materially change which ideas survive? If yes, the context is load-bearing — proceed without asking. If no, ask 1-3 narrowly chosen questions, building on what the user already provided rather than starting from a template. Default to free-form questions; use single-select only when the answer space is small and discrete (e.g., genre, tone). After each answer, re-apply the test before asking another. Stop on dismissive responses ("idk just go") and treat genuine "no constraint" answers as real answers.
|
||||
|
||||
When the user provides rich context up front (a paste, a brief, an existing draft), confirm understanding in one line and skip intake entirely.
|
||||
|
||||
#### 0.5 Cost Transparency Notice
|
||||
|
||||
Before dispatching Phase 1, surface the agent count for the inferred mode in one short line so multi-agent cost is not invisible. Compute the count from the actual dispatch decision: 1 grounding-context agent (codebase scan in repo mode; user-context synthesis in elsewhere) + 1 learnings (skip in elsewhere-non-software) + 1 web researcher + 6 ideation = baseline 9 in repo mode and elsewhere-software, 8 in elsewhere-non-software. When issue-tracker intent triggers (repo mode only): add 1 for the issue-intelligence agent and drop ideation from 6 to 4, for a net -1 (baseline 8). Add 1 if the user opted into Slack research. Subtract 1 if the user issued a web-research skip phrase or V15 reuse will fire.
|
||||
|
||||
Examples (defaults, no skips, no opt-ins):
|
||||
|
||||
- **Repo mode:** "Will dispatch ~9 agents: codebase scan + learnings + web research + 6 ideation sub-agents. Skip phrases: 'no external research', 'no slack'."
|
||||
- **Repo mode, issue-tracker intent:** "Will dispatch ~8 agents: codebase scan + learnings + web research + issue intelligence + 4 ideation sub-agents. Skip phrases: 'no external research', 'no slack'." Reflects the successful-theme path; if issue intelligence returns insufficient signal (see Phase 1), ideation falls back to 6 sub-agents and the total becomes ~9.
|
||||
- **Elsewhere-software:** "Will dispatch ~9 agents: context synthesis + learnings + web research + 6 ideation sub-agents. Skip phrases: 'no external research'."
|
||||
- **Elsewhere-non-software:** "Will dispatch ~8 agents: context synthesis + web research + 6 ideation sub-agents. Skip phrases: 'no external research'."
|
||||
|
||||
The line is informational; users do not need to acknowledge it.
|
||||
|
||||
### Phase 1: Mode-Aware Grounding
|
||||
|
||||
Before generating ideas, gather grounding. The dispatch set depends on the mode chosen in Phase 0.2. Web research runs in all modes (skip phrases honored). Learnings runs in repo mode and elsewhere-software, and is **skipped by default in elsewhere-non-software** — the CWD repo's `docs/solutions/` almost always contains engineering patterns that do not transfer to naming, narrative, personal, or non-digital business topics.
|
||||
|
||||
Generate a `<run-id>` once at the start of Phase 1 (8 hex chars). Reuse it for the V15 cache file (this phase) and the V17 checkpoints (Phases 2 and 4) so they share one per-run scratch directory.
|
||||
|
||||
**Pre-resolve the scratch directory path.** Scratch lives in OS temp (not `.context/`), per the cross-invocation-reusable rule in the repo Scratch Space convention — the ideation topic is rarely tied to the CWD repo (especially in elsewhere mode), so keeping scratch out of any repo tree is the right default. Run one bash command to create the directory and capture its **absolute path** for all downstream use. Do not pass `${TMPDIR:-/tmp}` as a literal string to non-shell tools (Write, Read, Glob); those tools do not perform shell expansion.
|
||||
|
||||
```bash
|
||||
SCRATCH_DIR="${TMPDIR:-/tmp}/compound-engineering/ce-ideate/<run-id>"
|
||||
mkdir -p "$SCRATCH_DIR"
|
||||
echo "$SCRATCH_DIR"
|
||||
```
|
||||
|
||||
Use the echoed absolute path (e.g., `/var/folders/.../T/compound-engineering/ce-ideate/a3f7c2e1` on macOS, `/tmp/compound-engineering/ce-ideate/a3f7c2e1` on Linux) as `<scratch-dir>` for every subsequent checkpoint write and cache read in this run. The run directory is not deleted on Phase 6 completion — the V15 cache is session-scoped and reused across run-ids, and the checkpoints follow the cross-invocation-reusable convention of leaving session-scoped artifacts for later invocations to find.
|
||||
|
||||
Run grounding agents in parallel in the **foreground** (do not background — results are needed before Phase 2):
|
||||
|
||||
**Repo mode dispatch:**
|
||||
|
||||
1. **Quick context scan** — dispatch a general-purpose sub-agent using the platform's cheapest capable model (e.g., `model: "haiku"` in Claude Code) with this prompt:
|
||||
|
||||
@@ -111,46 +193,76 @@ Run agents in parallel in the **foreground** (do not use background dispatch —
|
||||
|
||||
2. **Learnings search** — dispatch `compound-engineering:research:learnings-researcher` with a brief summary of the ideation focus.
|
||||
|
||||
3. **Issue intelligence** (conditional) — if issue-tracker intent was detected in Phase 0.2, dispatch `compound-engineering:research:issue-intelligence-analyst` with the focus hint. If a focus hint is present, pass it so the agent can weight its clustering toward that area. Run this in parallel with agents 1 and 2.
|
||||
3. **Web research** (always-on; see "Web research" subsection below for skip-phrase and V15 cache handling).
|
||||
|
||||
If the agent returns an error (gh not installed, no remote, auth failure), log a warning to the user ("Issue analysis unavailable: {reason}. Proceeding with standard ideation.") and continue with the existing two-agent grounding.
|
||||
4. **Issue intelligence** (conditional) — if issue-tracker intent was detected in Phase 0.3, dispatch `compound-engineering:research:issue-intelligence-analyst` with the focus hint. Run in parallel with the other agents.
|
||||
|
||||
If the agent returns an error (gh not installed, no remote, auth failure), log a warning to the user ("Issue analysis unavailable: {reason}. Proceeding with standard ideation.") and continue with the remaining grounding.
|
||||
|
||||
If the agent reports fewer than 5 total issues, note "Insufficient issue signal for theme analysis" and proceed with default ideation frames in Phase 2.
|
||||
|
||||
Consolidate all results into a short grounding summary. When issue intelligence is present, keep it as a distinct section so ideation sub-agents can distinguish between code-observed and user-reported signals:
|
||||
**Elsewhere mode dispatch (skip the codebase scan; user-supplied context is the primary grounding):**
|
||||
|
||||
- **Codebase context** — project shape, notable patterns, obvious pain points, likely leverage points
|
||||
- **Past learnings** — relevant institutional knowledge from docs/solutions/
|
||||
- **Issue intelligence** (when present) — theme summaries from the issue intelligence agent, preserving theme titles, descriptions, issue counts, and trend directions
|
||||
1. **User-context synthesis** — dispatch a general-purpose sub-agent (cheapest capable model) to read the user-supplied context from Phase 0.4 intake plus any rich-prompt material, and return a structured grounding summary that mirrors the codebase-context shape (project shape → topic shape; notable patterns → stated constraints; pain points → user-named pain points; leverage points → opportunity hooks the context implies). This keeps Phase 2 sub-agents agnostic to grounding source.
|
||||
|
||||
**Slack context** (opt-in) — never auto-dispatch. Route by condition:
|
||||
2. **Learnings search** *(elsewhere-software only; skipped by default in elsewhere-non-software)* — dispatch `compound-engineering:research:learnings-researcher` with the topic summary in case relevant institutional knowledge exists (skill-design patterns, prior solutions in similar shape). Skip for elsewhere-non-software: the CWD's `docs/solutions/` is unlikely to be topically relevant for non-digital topics, and running it risks polluting generation with unrelated engineering patterns.
|
||||
|
||||
- **Tools available + user asked**: Dispatch `compound-engineering:research:slack-researcher` with the focus hint in parallel with other Phase 1 agents. Include findings in the grounding summary.
|
||||
- **Tools available + user didn't ask**: Note in output: "Slack tools detected. Ask me to search Slack for organizational context at any point, or include it in your next prompt."
|
||||
- **No tools + user asked**: Note in output: "Slack context was requested but no Slack tools are available. Install and authenticate the Slack plugin to enable organizational context search."
|
||||
3. **Web research** — same as repo mode (see subsection below).
|
||||
|
||||
Do **not** do external research in v1.
|
||||
Issue intelligence does not apply in elsewhere mode. Slack research is opt-in for both modes (see "Slack context" below).
|
||||
|
||||
#### Web Research (V5, V15)
|
||||
|
||||
Always-on for both modes. Skip when the user said "no external research", "skip web research", or equivalent in their prompt or earlier answers; in that case, omit `compound-engineering:research:web-researcher` from dispatch and note the skip in the consolidated grounding summary.
|
||||
|
||||
Reuse prior web research within a session via a sidecar cache — see `references/web-research-cache.md` for the cache file shape, reuse check, append behavior, and platform-degradation rules. Read it the first time `compound-engineering:research:web-researcher` would be dispatched in this run (and on every subsequent dispatch where the cache might apply).
|
||||
|
||||
When dispatching `compound-engineering:research:web-researcher`, pass: the focus hint, a brief planning context summary (one or two sentences), and the mode. Do not pass codebase content — the agent operates externally.
|
||||
|
||||
#### Consolidated Grounding Summary
|
||||
|
||||
Consolidate all dispatched results into a short grounding summary using these sections (omit any section that produced nothing):
|
||||
|
||||
- **Codebase context** *(repo mode)* OR **Topic context** *(elsewhere mode)* — project/topic shape, notable patterns or stated constraints, pain points, leverage points
|
||||
- **Past learnings** — relevant institutional knowledge from `docs/solutions/`
|
||||
- **Issue intelligence** *(when present, repo mode only)* — theme summaries with titles, descriptions, issue counts, and trend directions
|
||||
- **External context** *(when web research ran)* — prior art, adjacent solutions, market signals, cross-domain analogies. Note "(reused from earlier dispatch)" when V15 reuse fired
|
||||
- **Slack context** *(when present)* — organizational context
|
||||
|
||||
**Failure handling.** Grounding agent failures follow "warn and proceed" — never block on grounding failure. If `compound-engineering:research:web-researcher` fails (network, tool unavailable), log a warning ("External research unavailable: {reason}. Proceeding with internal grounding only.") and continue. If elsewhere-mode intake produced no usable context, note in the grounding summary that context is thin so Phase 2 sub-agents can compensate with broader generation.
|
||||
|
||||
**Slack context** (opt-in, both modes) — never auto-dispatch. When the user asks for Slack context and Slack tools are available (look for any `slack-researcher` agent or `slack` MCP tools in the current environment), dispatch `compound-engineering:research:slack-researcher` with the focus hint in parallel with other Phase 1 agents. When tools are present but the user did not ask, mention availability in the grounding summary so they can opt in. When the user asked but no Slack tools are reachable, surface the install hint instead.
|
||||
|
||||
### Phase 2: Divergent Ideation
|
||||
|
||||
Generate the full candidate list before critiquing any idea.
|
||||
|
||||
Dispatch 3-4 parallel ideation sub-agents on the inherited model (do not tier down -- creative ideation needs the orchestrator's reasoning level). Omit the `mode` parameter so the user's configured permission settings apply. Each targets ~8-10 ideas (yielding ~30 raw ideas, ~20-25 after dedupe). Adjust per-agent targets when volume overrides apply (e.g., "100 ideas" raises it, "top 3" may lower the survivor count instead).
|
||||
Dispatch parallel ideation sub-agents on the inherited model (do not tier down -- creative ideation needs the orchestrator's reasoning level). Omit the `mode` parameter so the user's configured permission settings apply. Dispatch count is mode-conditional: **4 sub-agents only when issue-tracker intent was detected in Phase 0.3 AND the issue intelligence agent returned usable themes** (see override below — cluster-derived frames capped at 4); **6 sub-agents otherwise**, including the insufficient-issue-signal fallback from Phase 1 where intent triggered but themes were not returned. Each targets ~6-8 ideas (yielding ~36-48 raw ideas across 6 frames or ~24-32 across 4 frames, roughly 25-30 survivors after dedupe in the 6-frame path and fewer in the 4-frame path). Adjust per-agent targets when volume overrides apply (e.g., "100 ideas" raises it, "top 3" may lower the survivor count instead).
|
||||
|
||||
Give each sub-agent: the grounding summary, the focus hint, the per-agent volume target, and an instruction to generate raw candidates only (not critique). Each agent's first few ideas tend to be obvious -- push past them. Ground every idea in the Phase 1 scan.
|
||||
Give each sub-agent: the grounding summary, the focus hint, the per-agent volume target, and an instruction to generate raw candidates only (not critique). Each agent's first few ideas tend to be obvious -- push past them. Ground every idea in the Phase 1 grounding summary.
|
||||
|
||||
Assign each sub-agent a different ideation frame as a **starting bias, not a constraint**. Prompt each to begin from its assigned perspective but follow any promising thread -- cross-cutting ideas that span multiple frames are valuable.
|
||||
|
||||
**Frame selection:**
|
||||
- **When issue-tracker intent is active and themes were returned:** Each high/medium-confidence theme becomes a frame. Pad with default frames if fewer than 3 cluster-derived frames. Cap at 4 total.
|
||||
- **Default frames (no issue-tracker intent):** (1) user/operator pain and friction, (2) inversion, removal, or automation of a painful step, (3) assumption-breaking or reframing, (4) leverage and compounding effects.
|
||||
**Frame selection (mode-symmetric — same six frames in repo and elsewhere modes):**
|
||||
|
||||
1. **Pain and friction** — user, operator, or topic-level pain points; what is consistently slow, broken, or annoying.
|
||||
2. **Inversion, removal, or automation** — invert a painful step, remove it entirely, or automate it away.
|
||||
3. **Assumption-breaking and reframing** — what is being treated as fixed that is actually a choice; reframe one level up or sideways.
|
||||
4. **Leverage and compounding** — choices that, once made, make many future moves cheaper or stronger; second-order effects.
|
||||
5. **Cross-domain analogy** — generate ideas by asking how completely different fields solve a structurally analogous problem. The grounding domain is the user's topic; the analogy domain is anywhere else (other industries, biology, games, infrastructure, history). Push past the obvious analogy to non-obvious ones.
|
||||
6. **Constraint-flipping** — invert the obvious constraint to its opposite or extreme. What if the budget were 10x or 0? What if the team were 100 people or 1? What if there were no users, or 1M? Use the resulting design as a candidate even if the constraint flip itself is not realistic.
|
||||
|
||||
**Issue-tracker mode override (repo mode only).** When issue-tracker intent is active and themes were returned by the issue intelligence agent: each high/medium-confidence theme becomes a frame. Pad with frames from the 6-frame default pool (in the order listed above) if fewer than 3 cluster-derived frames. Cap at 4 total — issue-tracker mode keeps its tighter dispatch by design.
|
||||
|
||||
Ask each sub-agent to return a compact structure per idea: title, summary, why_it_matters, evidence/grounding hooks, optional boldness or focus_fit signal.
|
||||
|
||||
After all sub-agents return:
|
||||
|
||||
1. Merge and dedupe into one master candidate list.
|
||||
2. Synthesize cross-cutting combinations -- scan for ideas from different frames that combine into something stronger (expect 3-5 additions at most).
|
||||
3. If a focus was provided, weight the merged list toward it without excluding stronger adjacent ideas.
|
||||
4. Spread ideas across multiple dimensions when justified: workflow/DX, reliability, extensibility, missing capabilities, docs/knowledge compounding, quality/maintenance, leverage on future work.
|
||||
|
||||
After merging and synthesis, read `references/post-ideation-workflow.md` for the adversarial filtering rubric, presentation format, artifact template, handoff options, and quality bar. Do not load this file before Phase 2 agent dispatch completes.
|
||||
**Checkpoint A (V17).** Immediately after the cross-cutting synthesis step completes and the raw candidate list is consolidated, write `<scratch-dir>/raw-candidates.md` (using the absolute path captured in Phase 1) containing the full candidate list with sub-agent attribution. This protects the most expensive output (6 parallel sub-agent dispatches + dedupe) before Phase 3 critique potentially compacts context. Best-effort: if the write fails (disk full, permissions), log a warning and proceed; the checkpoint is not load-bearing. Not cleaned up at the end of the run (the run directory is preserved so the V15 cache remains reusable across run-ids in the same session — see Phase 6).
|
||||
|
||||
After merging and synthesis — and before presenting survivors — load `references/post-ideation-workflow.md`. This load is non-optional. The file contains the adversarial filtering rubric, artifact template, quality bar, and the canonical Phase 6 handoff menu (Refine, Open and iterate in Proof, Brainstorm, Save and end) — these options do not appear anywhere in this main body. Skipping the load silently degrades every subsequent step; the agent improvises the menu from memory instead of presenting the documented options. "Quickly" means fewer Phase 2 sub-agents, not skipping references. Do not load this file before Phase 2 agent dispatch completes.
|
||||
|
||||
@@ -14,12 +14,12 @@ Rejection criteria:
|
||||
- too vague
|
||||
- not actionable
|
||||
- duplicates a stronger idea
|
||||
- not grounded in the current codebase
|
||||
- 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
|
||||
|
||||
Score survivors using a consistent rubric weighing: groundedness in the current repo, expected value, novelty, pragmatism, leverage on future work, implementation burden, and overlap with stronger ideas.
|
||||
Score survivors using a consistent rubric weighing: groundedness in stated context, expected value, novelty, pragmatism, leverage on future work, implementation burden, and overlap with stronger ideas.
|
||||
|
||||
Target output:
|
||||
- keep 5-7 survivors by default
|
||||
@@ -28,7 +28,9 @@ Target output:
|
||||
|
||||
## Phase 4: Present the Survivors
|
||||
|
||||
Present the surviving ideas to the user before writing the durable artifact. This is a review checkpoint, not the final archived result.
|
||||
**Checkpoint B (V17).** Before presenting, write `<scratch-dir>/survivors.md` (using the absolute path captured in Phase 1) containing the survivor list plus key context (focus hint, grounding summary, rejection summary). This protects the post-critique state before the user reaches the persistence menu. Best-effort: if the write fails (disk full, permissions), log a warning and proceed; the checkpoint is not load-bearing. Reuses the same `<run-id>` and `<scratch-dir>` generated in Phase 1; not cleaned up at the end of the run (the run directory is preserved so the V15 cache remains reusable across run-ids in the same session — see Phase 6).
|
||||
|
||||
Present the surviving ideas to the user. The terminal review loop is a complete ideation cycle in itself — persistence is opt-in (Phase 5), and refinement happens in conversation with no file or network cost (Phase 6).
|
||||
|
||||
Present only the surviving ideas in structured form:
|
||||
|
||||
@@ -41,25 +43,26 @@ Present only the surviving ideas in structured form:
|
||||
|
||||
Then include a brief rejection summary so the user can see what was considered and cut.
|
||||
|
||||
Keep the presentation concise. The durable artifact holds the full record.
|
||||
Keep the presentation concise. Allow brief follow-up questions and lightweight clarification.
|
||||
|
||||
Allow brief follow-up questions and lightweight clarification before writing the artifact.
|
||||
## Phase 5: Persistence (Opt-In, Mode-Aware)
|
||||
|
||||
Do not write the ideation doc yet unless:
|
||||
- the user indicates the candidate set is good enough to preserve
|
||||
- the user asks to refine and continue in a way that should be recorded
|
||||
- the workflow is about to hand off to `ce:brainstorm`, Proof sharing, or session end
|
||||
Persistence is opt-in. The terminal review loop is a complete ideation cycle. Refinement loops happen in conversation with no file or network cost. Persistence triggers only when the user explicitly chooses to save, share, or hand off (selected in Phase 6).
|
||||
|
||||
## Phase 5: Write the Ideation Artifact
|
||||
When the user picks an option in Phase 6 that requires a durable record (Open and iterate in Proof, Brainstorm, Save and end), ensure a record exists first. When the user chooses to keep refining, no record is needed unless the user asks.
|
||||
|
||||
Write the ideation artifact after the candidate set has been reviewed enough to preserve.
|
||||
**Mode-determined defaults:**
|
||||
|
||||
Always write or update the artifact before:
|
||||
- handing off to `ce:brainstorm`
|
||||
- sharing to Proof
|
||||
- ending the session
|
||||
| Action | Repo mode default | Elsewhere mode default |
|
||||
|---|---|---|
|
||||
| Save | `docs/ideation/YYYY-MM-DD-<topic>-ideation.md` | Proof |
|
||||
| Share | Proof (additional) | Proof (primary) |
|
||||
| Brainstorm handoff | `ce:brainstorm` | `ce:brainstorm` (universal-brainstorming) |
|
||||
| End | Conversation only is fine | Conversation only is fine |
|
||||
|
||||
To write the artifact:
|
||||
Either mode can also use the other destination on explicit request ("save to Proof even though this is repo mode", "save to a local file even though this is elsewhere"). Honor such overrides directly.
|
||||
|
||||
### 5.1 File Save (default for repo mode; on request for elsewhere mode)
|
||||
|
||||
1. Ensure `docs/ideation/` exists
|
||||
2. Choose the file path:
|
||||
@@ -74,18 +77,19 @@ Use this structure and omit clearly irrelevant fields only when necessary:
|
||||
date: YYYY-MM-DD
|
||||
topic: <kebab-case-topic>
|
||||
focus: <optional focus hint>
|
||||
mode: <repo-grounded | elsewhere-software | elsewhere-non-software>
|
||||
---
|
||||
|
||||
# Ideation: <Title>
|
||||
|
||||
## Codebase Context
|
||||
[Grounding summary from Phase 1]
|
||||
## Grounding Context
|
||||
[Grounding summary from Phase 1 — labeled "Codebase Context" in repo mode, "Topic Context" in elsewhere mode]
|
||||
|
||||
## Ranked Ideas
|
||||
|
||||
### 1. <Idea Title>
|
||||
**Description:** [Concrete explanation]
|
||||
**Rationale:** [Why this improves the project]
|
||||
**Rationale:** [Why this idea is strong in the stated context]
|
||||
**Downsides:** [Tradeoffs or costs]
|
||||
**Confidence:** [0-100%]
|
||||
**Complexity:** [Low / Medium / High]
|
||||
@@ -102,28 +106,52 @@ If resuming:
|
||||
- update the existing file in place
|
||||
- preserve explored markers
|
||||
|
||||
### 5.2 Proof Save (default for elsewhere mode; on request for repo mode)
|
||||
|
||||
Hand off the ideation content to the `proof` skill in HITL review mode. This uploads the doc, runs an iterative review loop (user annotates in Proof, agent ingests feedback and applies tracked edits), and (in repo mode) syncs the reviewed markdown back to `docs/ideation/`.
|
||||
|
||||
Load the `proof` skill in HITL-review mode with:
|
||||
|
||||
- **source content:** the survivors and rejection summary from Phase 4 (in repo mode, this is the file written in 5.1; in elsewhere mode, render to a temp file as the source for upload)
|
||||
- **doc title:** `Ideation: <topic>` or the H1 of the ideation doc
|
||||
- **identity:** `ai:compound-engineering` / `Compound Engineering`
|
||||
- **recommended next step:** `/ce:brainstorm` (shown in the proof skill's final terminal output)
|
||||
|
||||
The Proof failure ladder in Phase 6.5 governs what happens when this hand-off fails.
|
||||
|
||||
**Caller-aware return.** The return-rule bullets below describe the default control flow, but the next step depends on which Phase 6 option invoked the Proof save. Apply the right branch for the caller:
|
||||
|
||||
- **§6.2 Open and iterate in Proof.** Behavior is mode-aware:
|
||||
- *Repo mode:* return to the Phase 6 menu on every status. The Proof-reviewed content is now synced locally, and the user typically has a follow-up action in the repo (brainstorm toward a plan, save and end, or keep refining).
|
||||
- *Elsewhere mode:* on a successful Proof return (`proceeded` or `done_for_now`), exit cleanly — narrate that the artifact lives at `docUrl` (including any stale-local note if applicable) and stop. Proof iteration is often the terminal act in elsewhere mode; forcing another menu choice after the user already got what they came for produces decision fatigue. Only the `aborted` branch returns to the Phase 6 menu so the user can retry or pick another path.
|
||||
- **§6.3 Brainstorm a selected idea.** On a successful Proof return (`proceeded` or `done_for_now`), do **not** stop at the Phase 6 menu — after applying the per-status handling below (including any stale-local pull offer), continue into §6.3's remaining bullets (mark the chosen idea as `Explored`, then load `ce:brainstorm`). Only the `aborted` branch returns to the Phase 6 menu, since no durable record was written.
|
||||
- **§6.4 Save and end.** On a successful Proof return (`proceeded` or `done_for_now`), exit cleanly: narrate that the ideation was saved, surface the `docUrl` (and the local-path note if applicable), and stop. Do **not** re-ask the Phase 6 question — the user already chose to end. Only the `aborted` branch returns to the Phase 6 menu so the user can retry or pick a different path.
|
||||
|
||||
When the proof skill returns control:
|
||||
|
||||
- `status: proceeded` with `localSynced: true` → the ideation doc on disk now reflects the review. Apply the caller-aware return rule above for the invoking branch.
|
||||
- `status: proceeded` with `localSynced: false` → the reviewed version lives in Proof at `docUrl` but the local copy is stale. Offer to pull the Proof doc to `localPath` using the proof skill's Pull workflow. Apply the caller-aware return rule above; if the pull was declined, include a one-line note that `<localPath>` is stale vs. Proof so the next handoff (or final exit narration) doesn't read the old content silently. Placement: above the Phase 6 menu when the caller-aware rule returns to it, in the handoff preamble to `ce:brainstorm` for §6.3, or alongside the final save/exit narration for §6.2 elsewhere / §6.4.
|
||||
- `status: done_for_now` → the doc on disk may be stale if the user edited in Proof before leaving. Offer to pull the Proof doc to `localPath` so the local ideation artifact stays in sync, then apply the caller-aware return rule above. `done_for_now` means the user stopped the HITL loop — it does not mean they ended the whole ideation session unless the caller-aware rule exits (§6.2 elsewhere mode or §6.4). If the pull was declined, include the stale-local note at the placement described in the previous bullet.
|
||||
- `status: aborted` → fall back to the Phase 6 menu without changes, regardless of caller. No durable record was written, so §6.3 must not proceed with the brainstorm handoff and §6.4 must not end — the menu lets the user retry or pick another path.
|
||||
|
||||
## Phase 6: Refine or Hand Off
|
||||
|
||||
After presenting the results, ask what should happen next using the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the numbered options in chat and wait for the user's reply before proceeding.
|
||||
Ask what should happen next using the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present numbered options in chat and wait for the user's reply.
|
||||
|
||||
**Question:** "Ideation saved. What's next?"
|
||||
**Question:** "What should the agent do next?"
|
||||
|
||||
Offer these options:
|
||||
1. **Brainstorm a selected idea** — hand off to `ce:brainstorm` with the selected idea as the seed
|
||||
2. **Refine the ideation** — add, re-evaluate, or deepen ideas before handing off
|
||||
3. **Open in Proof (web app) — review and comment to iterate with the agent** — open the doc in Every's Proof editor, iterate via comments, or copy a link to share with others
|
||||
4. **End the session** — no further action; the ideation doc is saved
|
||||
Offer these four options (each label is self-contained per the Interactive Question Tool Design rules in the plugin AGENTS.md — the distinguishing word is front-loaded so options stay distinct when truncated):
|
||||
|
||||
### 6.1 Brainstorm a Selected Idea
|
||||
1. **Refine the ideation in conversation (or stop here — no save)** — add ideas, re-evaluate, or deepen analysis. No file or network side effects; ending the conversation at any point after this pick is a valid no-save exit.
|
||||
2. **Open and iterate in Proof** — save the ideation to Proof and enter the proof skill's HITL review loop: iterate via comments in the Proof editor; reviewed edits sync back to `docs/ideation/` in repo mode.
|
||||
3. **Brainstorm a selected idea** — load `ce:brainstorm` with the chosen idea as the seed. The orchestrator first writes a durable record using the mode default in Phase 5.
|
||||
4. **Save and end** — persist the ideation using the mode default (file in repo mode, Proof in elsewhere mode), then end.
|
||||
|
||||
If the user selects an idea:
|
||||
- write or update the ideation doc first
|
||||
- mark that idea as `Explored`
|
||||
- invoke `ce:brainstorm` with the selected idea as the seed
|
||||
No-save exit is supported without a dedicated menu option. Pick option 1 and stop the conversation, or use the question tool's free-text escape to say so directly — persistence is opt-in and the terminal review loop is already a complete ideation cycle.
|
||||
|
||||
Do **not** skip brainstorming and go straight to planning from ideation output.
|
||||
Do not delete the run's scratch directory (`<scratch-dir>` resolved in Phase 1) on completion. The V15 web-research cache is session-scoped and reused across run-ids by later ideation invocations in the same session (see `references/web-research-cache.md`); per-run cleanup would defeat that reuse. Checkpoint A (`raw-candidates.md`) and Checkpoint B (`survivors.md`) are cheap to leave behind and follow the repo's Scratch Space cross-invocation-reusable convention — OS handles eventual cleanup.
|
||||
|
||||
### 6.2 Refine the Ideation
|
||||
### 6.1 Refine the Ideation in Conversation
|
||||
|
||||
Route refinement by intent:
|
||||
|
||||
@@ -131,46 +159,74 @@ Route refinement by intent:
|
||||
- `re-evaluate` or `raise the bar` -> return to Phase 3
|
||||
- `dig deeper on idea #N` -> expand only that idea's analysis
|
||||
|
||||
After each refinement:
|
||||
- update the ideation document before any handoff, sharing, or session end
|
||||
No persistence triggers during refinement. The user can choose Save and end (or Brainstorm, or Open and iterate in Proof) when they are ready to persist.
|
||||
|
||||
### 6.3 Open in Proof (web app)
|
||||
Ending after refinement — or without any refinement at all — is a valid no-save exit. There is no required next step; stopping the conversation here leaves no durable artifact, which matches the opt-in persistence contract.
|
||||
|
||||
If requested, hand off the ideation document to the proof skill in HITL review mode. This uploads the doc, runs an iterative review loop (user annotates in Proof, agent ingests feedback and applies tracked edits), and syncs the reviewed markdown back to `docs/ideation/`.
|
||||
### 6.2 Open and Iterate in Proof
|
||||
|
||||
Load the `proof` skill in HITL-review mode with:
|
||||
Invoke the Proof HITL review path via §5.2 with §6.2 as the caller. In repo mode, ensure the local file exists first (run §5.1) so the HITL sync-back has a target; in elsewhere mode, §5.2 renders to a temp file as usual. Honor Phase 5's "ensure a record exists first" contract either way.
|
||||
|
||||
- **source file:** the ideation document path written in Phase 5 (e.g., `docs/ideation/YYYY-MM-DD-<topic>-ideation.md`)
|
||||
- **doc title:** `Ideation: <topic>` or the H1 of the ideation doc
|
||||
- **identity:** `ai:compound-engineering` / `Compound Engineering`
|
||||
- **recommended next step:** `/ce:brainstorm` (shown in the proof skill's final terminal output)
|
||||
Apply §5.2's caller-aware return rule for the §6.2 branch — behavior is mode-aware. In repo mode, return to the Phase 6 menu on every status so the user can pick a follow-up (brainstorm toward a plan, save-and-end, or keep refining) now that the Proof review is reflected in the local file. In elsewhere mode, exit cleanly on a successful Proof return since Proof iteration is often the terminal act — the artifact lives at `docUrl` and is the canonical record; only the `aborted` status returns to the menu.
|
||||
|
||||
If the initial upload fails (network error, Proof API down), retry once after a short wait. If it still fails, tell the user the upload didn't succeed and briefly explain why, then return to the next-step options — don't leave them wondering why the option did nothing.
|
||||
If the Proof handoff fails, the §6.5 Proof Failure Ladder governs recovery.
|
||||
|
||||
When the proof skill returns control:
|
||||
### 6.3 Brainstorm a Selected Idea
|
||||
|
||||
- `status: proceeded` with `localSynced: true` → the ideation doc on disk now reflects the review. Return to the next-step options.
|
||||
- `status: proceeded` with `localSynced: false` → the reviewed version lives in Proof at `docUrl` but the local copy is stale. Offer to pull the Proof doc to `localPath` using the proof skill's Pull workflow. Return to the next-step options; if the pull was declined, include a one-line note above the menu that `<localPath>` is stale vs. Proof so the next handoff doesn't read the old content silently.
|
||||
- `status: done_for_now` → the doc on disk may be stale if the user edited in Proof before leaving. Offer to pull the Proof doc to `localPath` so the local ideation artifact stays in sync, then return to the next-step options. `done_for_now` means the user stopped the HITL loop — it does not mean they ended the whole ideation session; they may still want to brainstorm or refine. If the pull was declined, include the stale-local note above the menu.
|
||||
- `status: aborted` → fall back to the next-step options without changes.
|
||||
- Write or update the durable record per the mode default in Phase 5 (file in repo mode, Proof in elsewhere mode). When this routes through §5.2 Proof Save, apply §5.2's caller-aware return rule: continue into the next bullet on a successful Proof return instead of bouncing back to the Phase 6 menu. If Proof returned `aborted` (no durable record written), go back to the Phase 6 menu and do **not** proceed with the brainstorm handoff.
|
||||
- Mark the chosen idea as `Explored` in the saved record
|
||||
- Load the `ce:brainstorm` skill with the chosen idea as the seed
|
||||
|
||||
### 6.4 End the Session
|
||||
**Repo mode only:** do **not** skip brainstorming and go straight to `ce:plan` from ideation output — `ce:plan` wants brainstorm-grounded requirements. In elsewhere modes, ideation (or ideation + Proof iteration) 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.
|
||||
|
||||
### 6.4 Save and End
|
||||
|
||||
Persist via the mode default (5.1 in repo mode, 5.2 in elsewhere mode), then end. If the user instead asked to use the non-default destination, honor that explicit request.
|
||||
|
||||
When the path lands in a Proof save (5.2), apply §5.2's caller-aware return rule for the §6.4 branch: on a successful Proof return, exit cleanly — narrate the save, surface the `docUrl` (and any stale-local note if the pull was declined), and stop. Do **not** loop back to the Phase 6 menu; the user already chose to end. Only a `status: aborted` from Proof returns to the menu so the user can retry or pick another path (file save, custom path, or keep refining). The §6.5 Proof Failure Ladder still governs persistent Proof failures and ends at the Phase 6 menu — that failure-recovery path is distinct from the successful-save exit described here.
|
||||
|
||||
When the path lands in a file save (5.1):
|
||||
|
||||
When ending:
|
||||
- offer to commit only the ideation doc
|
||||
- do not create a branch
|
||||
- do not push
|
||||
- if the user declines, leave the file uncommitted
|
||||
|
||||
After the file save (and optional commit), end the session — do not return to the Phase 6 menu.
|
||||
|
||||
### 6.5 Proof Failure Ladder
|
||||
|
||||
The `proof` skill performs single-retry-once internally on transient failures (`STALE_BASE`, `BASE_TOKEN_REQUIRED`) before surfacing failure. The proof skill's return contract does not expose typed error classes to callers — the orchestrator cannot distinguish retryable vs terminal failures from outside.
|
||||
|
||||
**Orchestrator-side retry harness (intentionally minimal):** wrap the proof skill invocation in **one** additional best-effort retry with a short pause (~2 seconds). The proof skill already retried internally, so this catches transient races at the orchestrator boundary without compounding latency. Do not classify error types from outside the skill — no detection mechanism exists.
|
||||
|
||||
Distinguish create-failure from ops-failure by inspecting whether the proof skill returned a `docUrl` before failing:
|
||||
|
||||
- **Create-failure** (no `docUrl` returned): retry the create.
|
||||
- **Ops-failure** (a `docUrl` was returned, but a later operation failed): retry only the failing operation. **Do not recreate** the document.
|
||||
|
||||
**Failure narration.** Narrate the single retry to the terminal so the pause does not look like a hang ("Retrying Proof... attempt 2/2"). On persistent failure, narrate that retry exhausted before showing the fallback menu.
|
||||
|
||||
**Fallback menu after persistent failure.** Use the platform's blocking question tool. Present these options (omit option (a) if no repo exists at CWD):
|
||||
|
||||
- "Save to `docs/ideation/` instead" (repo-mode default destination, available when CWD is inside a git repo)
|
||||
- "Save to a custom path the user provides" (validate writable; create parent dirs)
|
||||
- "Skip save and keep the ideation in conversation" (no persistence)
|
||||
|
||||
If proof returned a partial `docUrl` before failing, surface that URL alongside the fallback options so the user can recover or share the partial record.
|
||||
|
||||
After the fallback completes (any path), continue back to the Phase 6 menu so the user can still refine, iterate in Proof, brainstorm, or save and end.
|
||||
|
||||
## Quality Bar
|
||||
|
||||
Before finishing, check:
|
||||
|
||||
- the idea set is grounded in the actual repo
|
||||
- the idea set is grounded in the stated context (codebase in repo mode; user-supplied topic in elsewhere mode)
|
||||
- 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 artifact was written before any handoff, sharing, or session end
|
||||
- persistence followed user choice — terminal-only sessions did not write a file or call Proof
|
||||
- when persistence did trigger, the mode default was respected unless the user explicitly overrode it
|
||||
- acting on an idea routes to `ce:brainstorm`, not directly to implementation
|
||||
|
||||
@@ -0,0 +1,63 @@
|
||||
# Universal Ideation Facilitator
|
||||
|
||||
This file is loaded when ce:ideate detects an elsewhere-mode topic with no software surface at all — naming (independent of product), narrative writing, personal decisions, non-digital business strategy, physical-product design. Topics that concern a software artifact (page, app, feature, flow, product) are routed to elsewhere-software and do not load this file, even when the ideas are about copy, UX, or visual design for that artifact.
|
||||
|
||||
Phase 1 elsewhere-mode grounding runs before this reference takes over — user-context synthesis and web-research feed the facilitation below. Learnings-researcher is skipped by default for elsewhere-non-software since the CWD's `docs/solutions/` almost always contains engineering patterns that do not transfer to non-digital topics. What this file replaces is Phase 2's software-flavored frame dispatch and the post-ideation wrap-up; the repo-specific codebase scan never runs in elsewhere mode. Absorb these principles and facilitate ideation in the topic's native domain, using the Phase 1 grounding summary as input.
|
||||
|
||||
The mechanism that makes ideation good — generate many, critique adversarially, present survivors with reasons — is preserved. Only the framing of the work changes.
|
||||
|
||||
---
|
||||
|
||||
## Your role
|
||||
|
||||
Be a divergent thinking partner, not a delivery service. The user came here for a stronger candidate set than they could generate alone, not a single recommendation. Resist the urge to converge early. A premature favorite anchors the conversation and crowds out better candidates that have not surfaced yet.
|
||||
|
||||
Match the tone to the stakes. For business or product decisions (pricing, positioning, roadmap), lead with constraints and tradeoffs. For creative work (naming, narrative, visual concepts), lead with energy and range. For personal decisions, lead with values before mechanics.
|
||||
|
||||
## How to start
|
||||
|
||||
Match depth to scope:
|
||||
|
||||
- **Quick** — the user wants a starter set right now. Generate one round, critique briefly, present 3-5 survivors, done.
|
||||
- **Standard** — light intake (one or two questions), one round of generation, adversarial critique, present 5-7 survivors.
|
||||
- **Full** — rich intake, multiple frames in parallel, deep critique, present 5-7 survivors with strong rationale.
|
||||
|
||||
Apply the discrimination test before asking anything. Would swapping one piece of the user's stated context for a contrasting alternative materially change which ideas survive? If yes, the context is load-bearing — proceed. If no, ask 1-3 narrowly chosen questions, building on what the user already provided rather than starting from a template. After each answer, re-apply the test before asking another. Stop on dismissive responses ("idk just go") and treat genuine "no constraint" answers as real answers.
|
||||
|
||||
**Grounding freshness.** Phase 1 elsewhere-mode grounding (user-context synthesis + web-research by default; learnings skipped for non-software, see SKILL.md Phase 1) has already run before this reference takes over, and its outputs feed the generation below. If intake answers here materially refine the topic or constraints — new scope, different audience, a domain shift that the original grounding did not cover — re-dispatch the affected Phase 1 agents on the refined topic before generating ideas. The guardrail mirrors SKILL.md Phase 0.4's rule that mode and grounding re-evaluate when intake changes the scope to be acted on; ranking against stale grounding risks surfacing ideas fit to the wrong topic.
|
||||
|
||||
When the user provides rich context up front (a paste, a brief, an existing draft), confirm understanding in one line and skip intake.
|
||||
|
||||
## How to generate
|
||||
|
||||
Generate the full candidate list before critiquing any idea. Use the same six frames as software ideation, described in domain-agnostic language. Each frame is a **starting bias, not a constraint** — follow promising threads across frames.
|
||||
|
||||
- **Pain and friction** — what is consistently annoying, slow, or broken in the current state of the topic? Generate ideas that remove or reduce that friction.
|
||||
- **Inversion, removal, automation** — what would happen if a step were inverted, removed entirely, or automated away? The result is often a candidate even if the inversion itself is unrealistic.
|
||||
- **Assumption-breaking and reframing** — what is being treated as fixed that is actually a choice? Reframe the problem one level up or sideways.
|
||||
- **Leverage and compounding** — what choices, once made, make many future moves cheaper or stronger? Look for second-order effects.
|
||||
- **Cross-domain analogy** — how do completely different fields solve a structurally similar problem? The grounding domain is the user's topic; the analogy domain is anywhere else (other industries, biology, games, infrastructure, history). Push past the obvious analogy to non-obvious ones.
|
||||
- **Constraint-flipping** — invert the obvious constraint to its opposite or extreme. What if the budget were 10x or 0? What if there were one constraint instead of ten, or ten instead of one? Use the resulting design as a candidate even if the flip itself is not realistic.
|
||||
|
||||
Aim for 5-8 ideas per frame. After generating, merge and dedupe; scan for cross-cutting combinations (3-5 additions at most).
|
||||
|
||||
## How to converge
|
||||
|
||||
Apply adversarial critique. For each candidate, write a one-line reason if rejected. Score survivors using a consistent rubric weighing: groundedness in stated context, expected value, novelty, pragmatism, leverage, implementation burden, and overlap with stronger candidates.
|
||||
|
||||
Target 5-7 survivors by default. If too many survive, run a second stricter pass. If fewer than five survive, report that honestly rather than lowering the bar.
|
||||
|
||||
## When to wrap up
|
||||
|
||||
Present survivors before any persistence. For each: title, description, rationale, downsides, confidence, complexity. Then a brief rejection summary so the user can see what was considered and cut.
|
||||
|
||||
Persistence is opt-in. The terminal review loop is a complete ideation cycle. Refinement happens in conversation with no file or network cost. Persistence triggers only when the user explicitly chooses to save, share, or hand off.
|
||||
|
||||
Use the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini) — or numbered options in chat as a fallback — and offer four choices:
|
||||
|
||||
- **Refine the ideation in conversation (or stop here — no save)** — add ideas, re-evaluate, or deepen analysis without writing anything. Ending the conversation at any point after this pick is a valid no-save exit.
|
||||
- **Open and iterate in Proof** — invoke the Proof HITL review path per the §6.2 contract in `references/post-ideation-workflow.md`: upload the survivors to Proof (rendered to a temp file since no local file is written in non-software elsewhere mode), iterate via comments, and exit cleanly with the Proof URL as the canonical record on successful return. Proof iteration is typically the terminal act in this mode, so the flow does not force another menu choice afterward. Only an `aborted` status returns to this menu. On persistent Proof failure, apply the §6.5 Proof Failure Ladder from `references/post-ideation-workflow.md` so the iteration attempt is not stranded without recovery.
|
||||
- **Brainstorm a selected idea** — go deeper on one idea through dialogue. Unlike repo mode, this is not the first step of an implementation chain — there is no `ce:plan` → `ce:work` after; `ce:brainstorm` in universal mode develops the idea further (e.g., expands a name into a brand brief, a plot into an outline, a decision into a weighed framework) and ends there. Persist first per the §6.3 contract in `references/post-ideation-workflow.md`: save the survivors to Proof (the elsewhere-mode default) or to `docs/ideation/` when the user explicitly asked for a local file, mark the chosen idea as `Explored`, then load `ce:brainstorm` with that idea as the seed. On a successful Proof return (`proceeded` or `done_for_now`), continue into the brainstorm handoff per §5.2's caller-aware return rule; on `aborted`, return to this menu without handing off. On persistent Proof failure, apply the §6.5 Proof Failure Ladder before ending so the brainstorm seed is preserved through a local-save fallback.
|
||||
- **Save and end** — share the survivors to Proof (the elsewhere-mode default) and end. Use `docs/ideation/` instead only when the user explicitly asks for a local file. On Proof failure (including after the single orchestrator-side retry), apply the §6.5 Proof Failure Ladder from `references/post-ideation-workflow.md` — surface the local-save fallback menu (custom path or skip) before ending so the user is not stranded without a recovery path.
|
||||
|
||||
No-save exit is supported without a dedicated menu option. Pick Refine and stop the conversation, or use the question tool's free-text escape to say so directly — persistence is opt-in and the terminal review loop is already a complete ideation cycle.
|
||||
@@ -0,0 +1,55 @@
|
||||
# Web Research Cache (V15)
|
||||
|
||||
Read this when checking the V15 cache before dispatching `web-researcher`, or when appending fresh research to the cache after dispatch. The behavior here is conditional — most invocations either hit the cache or write to it once and move on.
|
||||
|
||||
## Cache file shape
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"key": {
|
||||
"mode": "repo|elsewhere-software|elsewhere-non-software",
|
||||
"focus_hint_normalized": "<lowercase, whitespace-collapsed focus hint or empty string>",
|
||||
"topic_surface_hash": "<short hash of the user-supplied topic surface>"
|
||||
},
|
||||
"result": "<web-researcher output as plain text>",
|
||||
"ts": "<iso8601>"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Files live under `<scratch-dir>/web-research-cache.json`, where `<scratch-dir>` is the absolute OS-temp path resolved once in SKILL.md Phase 1 (`"${TMPDIR:-/tmp}/compound-engineering/ce-ideate/<run-id>"`). Do not pass the unresolved `${TMPDIR:-/tmp}` string to non-shell tools; always use the absolute path captured in Phase 1.
|
||||
|
||||
## Reuse check
|
||||
|
||||
Before dispatching `web-researcher`, resolve the scratch root (the parent of `<scratch-dir>`) in bash and list sibling run-id directories — refinement loops within a session may legitimately reuse another run's cache by topic, not run-id:
|
||||
|
||||
```bash
|
||||
SCRATCH_ROOT="${TMPDIR:-/tmp}/compound-engineering/ce-ideate"
|
||||
find "$SCRATCH_ROOT" -maxdepth 2 -name 'web-research-cache.json' -type f 2>/dev/null
|
||||
```
|
||||
|
||||
`find` exits 0 with empty output when no cache files exist, so the first-run case does not abort the reuse-check step.
|
||||
|
||||
Read each matching file. If any entry's `key` matches the current dispatch (same full mode variant — `repo`, `elsewhere-software`, or `elsewhere-non-software` — plus same case-insensitive normalized focus hint plus same topic surface hash), skip the dispatch and pass the cached `result` to the consolidated grounding summary. Mode variants must match exactly: `elsewhere-software` and `elsewhere-non-software` are distinct domains and must not cross-reuse. Note in the summary: "Reusing prior web research from this session — say 're-research' to refresh."
|
||||
|
||||
On `re-research` override, delete the matching entry and dispatch fresh.
|
||||
|
||||
## Append after fresh dispatch
|
||||
|
||||
After a fresh dispatch, append the new result to the current run's cache file at `<scratch-dir>/web-research-cache.json` using the absolute path from Phase 1 (create directory and file if needed). The next invocation in the session can reuse it via the `find` listing above.
|
||||
|
||||
## Topic surface hash
|
||||
|
||||
The topic surface is the user-supplied content the web research is grounded on:
|
||||
- **Elsewhere modes (`elsewhere-software`, `elsewhere-non-software`):** the user's topic prompt plus any Phase 0.4 intake answers (the actual subject the agent is researching). The two sub-modes are keyed separately — a reclassification between software and non-software for the same topic hash must force a fresh dispatch, since the research domain differs.
|
||||
- **Repo mode:** the focus hint plus a stable repo discriminator. This keeps the cache key meaningful when focus is empty — two bare-prompt invocations in the same repo legitimately share research, but the key still differentiates repos. Since cache files from every repo's runs now live under the shared OS-temp root, a bare basename like `app` or `frontend` would collide across unrelated repos. Resolve the discriminator with this fallback chain and hash the result (first 8 hex chars of sha256 is sufficient):
|
||||
1. `git remote get-url origin` — stable across machines, correct for collaborators on the same remote.
|
||||
2. `git rev-parse --show-toplevel` — absolute repo path; machine-local but always available in a git checkout.
|
||||
3. The current working directory's absolute path — last resort when not in a git repo.
|
||||
|
||||
Normalize before hashing: lowercase, collapse whitespace. (The repo discriminator hash is computed from the raw command output; only the focus hint and topic text are normalized.)
|
||||
|
||||
## Degradation
|
||||
|
||||
If the cache file is unreachable across invocations on the current platform (filesystem isolation, sandboxing, ephemeral working directory), degrade to "no reuse, dispatch every time." Surface the limitation in the consolidated grounding summary and proceed without reuse rather than inventing a capability the platform may not have.
|
||||
Reference in New Issue
Block a user