Ce Ideate

Generate Improvement Ideas

Note: The current year is 2026. Use this when dating ideation documents and checking recent ideation artifacts.

ce-ideate precedes ce-brainstorm.

• ce-ideate answers: "What are the strongest ideas worth exploring?"
• ce-brainstorm answers: "What exactly should one chosen idea mean?" and writes a requirements-only unified plan under docs/plans/.
• ce-plan answers: "How should it be built?"

This workflow produces a ranked ideation artifact — written to docs/ideation/ when present, else a CE temp path (see Phase 4). It does not produce requirements, plans, or code.

Interaction Method

Use 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, ask_question in Antigravity CLI (agy), ask_user in Pi (requires the pi-ask-user extension). 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.

Ask one question at a time. Prefer concise single-select choices when natural options exist.

Focus Hint

The focus hint is any optional context this skill was invoked with — present in the current prompt or conversation, whether the user gave it directly or a calling skill passed it. The rest of this skill refers to it as {focus_hint} (empty if none was given).

Interpret any provided argument as optional context. It may be:

• a concept such as DX improvements
• a path such as skills/
• a research artifact to draw on — a file of gathered evidence (social-research report, survey export, analytics dump) at any path, inside or outside the repo (handled in Phase 1's user-supplied research subsection)
• a constraint such as low-complexity quick wins
• a volume hint such as top 3, 100 ideas, or raise the bar

If no argument is provided, proceed with open-ended ideation.

Core Principles

1. Ground before ideating - Scan the actual codebase first. Do not generate abstract product advice detached from the repository.
2. Generate many -> critique all -> explain survivors only - The quality mechanism is explicit rejection with reasons, not optimistic ranking. Do not let extra process obscure this pattern.
3. Route action into brainstorming - Ideation identifies promising directions; ce-brainstorm defines the selected one precisely enough for planning. Do not skip to planning from ideation output.

Model Tiers

Sub-agent dispatch is tiered by task shape, never hardcoded to a model name:

• Extraction tier — evidence scouts and other retrieval/quoting work. Use the platform's cheapest capable model when the current harness exposes a known override. "Capable" is part of the spec — escalate to the generation tier when the repo is large or the stack obscure.
• Generation tier — evidence-driven ideation frames and basis verification. Use the platform's mid-tier model when the current harness exposes a known override. If model names are unknown, omit the override and inherit rather than guessing.
• Ceiling tier — ceiling ideation frames, cross-cutting synthesis, and final arbitration. Inherit the orchestrator's model by omitting the model parameter.

Degradation rule. When the platform's subagent primitive does not support per-agent model selection, dispatch everything on the inherited model and keep the read budgets and dossier caps — cost control then comes from structure, not tiering.

Two overrides raise the whole ideation fleet to the ceiling tier: surprise-me mode (subject discovery is judgment-heavy and is the mode's whole value) and the go deep depth override (Phase 0.5).

Execution Flow

Phase 0: Resume and Scope

When the subject, mode, and format are already clear from the prompt, resolve this phase in one pass and move on — the gates below exist for ambiguity, not ceremony.

0.0 Resolve Output Mode

Determine OUTPUT_FORMAT for the ideation artifact this run might persist. Output mode is exclusive — the ideation doc is written as either HTML (.html) OR markdown (.md), never both. Precedence: in-prompt request > user-stated preference > config > default (html), with a hard pipeline-mode override.

Unlike ce-plan and ce-brainstorm (which default to md), ce-ideate defaults to html — ideation artifacts are read mainly by humans weighing candidate directions, and a rich self-contained HTML file (with illustrative diagrams for the top candidates) makes the ideas easier to approach.

Read config. Resolve <repo-root> at runtime by running git rev-parse --show-toplevel with the shell tool. Then read <repo-root>/.compound-engineering/config.local.yaml with the native file-read tool. If the root cannot be resolved (not a git repo) or the file does not exist, fall through to the defaults below.

Resolution steps:

1. In-prompt request. Reason over the user's prompt for this run for a request about this document's output format, expressed either as the output: shorthand or in plain language ("give me this as markdown", "I want a webpage"). On an explicit format, match it case-insensitively to md/html, and ignore the output: shorthand token when reading the rest of the prompt as the focus hint. Distinguish a request about the document's format from a format named as subject matter: "ideate on an HTML export feature" is the work, not a doc-format request — do not switch on it.
   • output: alone (no value) → no-op, fall through to step 2.
   • output:<unknown> (e.g., output:pdf) → drop the token, fall through to step 2, and remember to emit a one-line note above the post-ideation menu after final resolution: Ignored unknown output: value '<value>' — using <resolved_format> instead. where <resolved_format> is the value OUTPUT_FORMAT actually resolved to after the remaining precedence steps. Do not hardcode a format in the note — that misleads users when config or the default differs from what you assume.
2. User-stated preference. If this prompt holds no format request, honor an output-format preference (markdown vs HTML) the user established earlier — earlier in this session, in your memory, or written into their active instructions — that is already in your context (match md/html case-insensitively). A remembered preference is more current than the rarely-edited config, so it overrides the config in step 3. Do not open or search instruction files to find it — act only on a preference already present in your context; if none is, fall through to the config.
3. Config. If steps 1-2 did not resolve and the config file read above has an active (non-commented) ideate_output: key whose value matches md or html (case-insensitive), use it. Missing, invalid, or commented values fall through silently. Critical: lines starting with # are YAML comments and must be ignored — the shipped config template includes a commented example like # ideate_output: md to document the option, and matching that as an active setting would silently override the default on every run without the user having opted in.
4. Default. Otherwise OUTPUT_FORMAT=html.
5. Pipeline override. When invoked from any pipeline or disable-model-invocation context, force OUTPUT_FORMAT=md regardless of steps 1-4 — automated downstream consumers parse markdown reliably and HTML in pipeline runs is unnecessary friction.

Token-parsing convention: only literal-prefix flag tokens (output:, mode: where applicable) are consumed and stripped. Other <word>:<word> tokens — including conventional commit prefixes like feat:, fix:, chore: that may appear inside a focus hint — pass through verbatim.

Defer loading the format-rendering reference. The deliverable is written at Phase 4 (after generation), so references/ideation-sections.md and the format-rendering references (markdown-rendering.md / html-rendering.md) are only needed then — loading them at Phase 0.0 would carry them through the entire grounding and ideation dispatch for no benefit. Resolve OUTPUT_FORMAT now, but load the section contract and the matching rendering reference at write time (see references/post-ideation-workflow.md §4.1).

The output: preference does NOT auto-propagate to ce-brainstorm on handoff (Phase 5) — ce-brainstorm re-resolves its own brainstorm_output config independently. Asymmetric output (ideation.html + unified-plan markdown) is acceptable; users who want HTML for both set both keys in .compound-engineering/config.local.yaml.

0.1 Check for Recent Ideation Work

Look in docs/ideation/ for ideation documents (*.md or *.html) created within the last 30 days.

Treat a prior ideation doc as relevant when:

• the topic matches the requested focus
• the path or subsystem overlaps the requested focus
• the request is open-ended and there is an obvious recent open ideation doc
• the issue-grounded status matches: do not offer to resume a non-issue ideation when the current argument indicates issue-tracker intent, or vice versa — treat these as distinct topics

If a relevant doc exists, ask whether to:

1. continue from it
2. start fresh

If continuing:

• read the document
• summarize what has already been explored
• preserve the previous ideas and rejection summary
• update the existing file instead of creating a duplicate
• write the update back in the existing file's format, overriding the Phase 0.0 baseline: resuming a .html doc rewrites HTML, a .md doc rewrites markdown. Format precedence on resume is: explicit output: arg this run > resumed file's extension > config > default (html); a pipeline/disable-model-invocation run still forces md per Phase 0.0. An explicit output: arg that differs from the existing file switches the artifact's format (write the new-format file; leave the original in place).

0.2 Subject-Identification Gate

Before classifying mode or dispatching any grounding, check whether the subject of ideation is identifiable. Every downstream agent — grounding and ideation — needs to know what it's working on. If the subject is ambiguous enough that reasonable sub-agents would diverge on what the topic even is (bare words like improvements, ideas, birthday cakes, vacation destinations), the output will be scattered.

Questioning principles (apply in this phase and in 0.4):

• Questions exist only to supply what sub-agents need to operate: an identifiable subject (this phase) and enough context for the agent to say something specific about it (0.4, elsewhere modes only). Nothing else.
• Never ask about solution direction, constraints, audience, tone, success criteria, or anything that characterizes the subject — those belong to ce-brainstorm.
• Always keep "Surprise me" (letting the agent decide the focus) as a real option, not a fallback for when the user can't name a subject. Ideation is allowed to be greenfield by design.
• Stop as soon as the subject is identifiable or the user has delegated to "Surprise me." More than 3 total questions across 0.2 and 0.4 is a smell that ideation is not the right workflow — consider suggesting ce-brainstorm.

Detection — issue-tracker intent (repo mode only; subject-identifying).

Issue-tracker intent requires an explicit reference to the tracker or to reports filed in it. Trigger only when the prompt uses phrases like github issues, open issues, issue patterns, issue themes, what users are reporting, or bug reports — the subject is "issues in the tracker." Proceed to 0.3 with issue-tracker intent flagged.

Do NOT trigger on arguments that merely mention bugs as a focus: bug in auth, fix the login issue, the signup bug, top 3 bugs in authentication — these are focus hints on regular ideation, not requests to analyze the issue tracker. A bare bugs with no tracker phrasing is handled by the vagueness check below, not here.

When combined (e.g., top 3 issue themes in authentication, biggest bug reports about checkout): detect issue-tracker intent first, volume override in 0.5, remainder is the focus hint. The focus narrows which issues matter; the volume override controls survivor count.

Detection — subject identifiability.

The test: would a reader, seeing only this prompt, know what subject the agent should ideate on? Vagueness is about what the words refer to, not phrase length: browser sniff is two words but plausibly names a feature (identifiable — proceed to 0.3); quick wins is two words but names only a quality (vague — ask the scope question). A prompt that refers to a catch-all quality, category, or placeholder (improvements, bugs alone, an empty prompt) is vague; one that names or plausibly names a specific feature, concept, document, flow, or topic is identifiable, in any domain.

Being inside a repo does not settle vagueness. improvements in any repo is still scattered across DX, reliability, features, docs, tests, architecture. The repo provides material for grounding after a subject is settled, not the subject itself. Do not silently interpret a vague prompt as "about this repo" and proceed.

Genuine ambiguity (repo mode). When real doubt remains on a short phrase, one cheap check settles it: Glob for the phrase in filenames, or Grep for it in README/docs. Any repo footprint → identifiable; none and still vague → ask. When in doubt otherwise, err toward asking — one question is trivial compared to dispatching a dozen agents on a scattered interpretation.

The scope question.

Ask via the platform's blocking question tool per Interaction Method above — never silently skip.

• Stem: "What should the agent ideate about?"
• Options:
  • "Specify a subject the agent should ideate on"
  • "Surprise me — let the agent decide what to focus on"
  • "Cancel — let me rephrase"

Routing:

• Specify → accept the user's follow-up as the subject. Re-apply the identifiability check once. If still ambiguous, ask once more with "Surprise me" still on the menu. Do not cascade toward specificity about how to solve — only about what the subject is.
• Surprise me → mark the run as surprise-me mode. The agent will discover subjects from Phase 1 material rather than carry a user-specified subject. This is a first-class mode — it changes how Phase 1 scans and how Phase 2 sub-agents operate (see those phases). Dispatch routing for surprise-me is deterministic: if CWD is inside a git repo, route to repo-grounded (the codebase supplies substance); otherwise route to elsewhere-software and require Phase 0.4 to collect at least one piece of substance (URL, description, draft, or paste) before dispatching — "surprise me" outside a repo is only viable once the user has supplied something to surprise them about. Skip Decision 1/2 in Phase 0.3: with no user subject there is no prompt content to weigh, and surprise-me never routes to elsewhere-non-software (no way to infer naming/narrative/personal intent without a subject). The user can correct by interrupting and re-invoking with a named subject.
• Cancel → exit cleanly. Narrate that the user can rephrase and re-invoke.

0.3 Mode Classification

Classify the subject of ideation (settled in 0.2) into one of three modes for dispatch routing. 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.

Surprise-me short-circuit. When Phase 0.2 routed to surprise-me mode, skip the two-decision classification below and use the deterministic rule stated in 0.2: repo-grounded when CWD is inside a git repo, elsewhere-software otherwise. The ambiguity-confirmation step at the end of this section also does not fire for surprise-me — there is no user subject to be ambiguous about. State the chosen mode in one sentence and proceed to 0.4.

For specified subjects, 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. Issue-tracker intent from 0.2 is always repo-grounded.
• 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.

Contrast pair: "Improve conversion on our sign-up page" → elsewhere-software (the subject is a page, even though the ideas may be copy or CRO); "Name my new coffee shop" → elsewhere-non-software (the subject is a brand with no software surface).

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."
• Elsewhere-software: "Treating this as a product/software topic outside this repo — about X."
• Elsewhere-non-software: "Treating this as a [naming | narrative | business | personal] topic — about X."

Do not prescribe correction phrases ("say X to switch"). State the inferred mode plainly and proceed. If the user disagrees, they will correct in their own words or interrupt to re-invoke — reclassify and re-run any affected routing when that happens.

Active confirmation on mode ambiguity. Only fire when mode classification is genuinely ambiguous after 0.2 settled the subject — e.g., "our docs" could mean repo docs (repo-grounded) or public marketing docs (elsewhere-software). Most subjects settled in 0.2 classify cleanly here. When ambiguous, ask one confirmation question via the blocking tool with two self-contained labels naming the two candidate interpretations in plain language (e.g., "Treat as repo docs in this codebase" vs "Treat as public marketing docs") — never leak internal mode names. Otherwise the one-sentence inferred-mode statement is sufficient; do not ask.

Routing rule (non-software mode). 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 5 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 deliverable is auto-written here too (per references/post-ideation-workflow.md Phase 4); if the user publishes a markdown deliverable to Proof and it fails, the §5.1 Proof handling applies and the auto-written local file remains the intact record.

0.4 Context-Substance Gate (Elsewhere Modes Only)

Skip in repo mode — the repo provides the substance Phase 1 agents work from. In elsewhere modes (both software and non-software), Phase 1 agents depend on user-supplied context for substance. A bare prompt with no description, URL, or artifact leaves the user-context-synthesis agent with nothing to synthesize and weakens web research's relevance.

Apply the discrimination test: would swapping one piece of the user's stated context for a contrasting alternative materially change which ideas survive? If yes, context is load-bearing — proceed. If no, ask 1-3 narrowly chosen questions focused on supplying substance, not characterizing the subject:

• A URL or file to read
• A brief description of the current state
• A paste of an existing draft or brief

Build 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. After each answer, re-apply the test before asking another. Stop on dismissive responses ("idk just go") — treat genuine "no context" answers as real answers and note context is thin in the summary so Phase 2 can compensate with broader generation.

Surprise-me exception. When the run is in surprise-me mode and routed to elsewhere-software (per 0.2's deterministic routing for no-repo CWDs), at least one piece of substance is required — there is no subject AND no repo, so Phase 1 and 2 agents would have nothing to discover subjects from. Dismissive responses are not acceptable here; if the user still has no context after one ask, tell them the run needs a URL, description, or paste to proceed and end cleanly so they can re-invoke with material.

When the user provides rich context up front (a paste, a brief, an existing draft, a URL), confirm understanding in one line and skip this step entirely.

If this step materially changes the topic (not just adds context but shifts the subject), re-run 0.2 and 0.3 against the refined scope before dispatching Phase 1 — classify on what's actually being ideated on, not the scope at first read.

0.5 Interpret Focus and Volume

Infer two things from the argument and any intake so far:

• Focus context — concept, path, constraint, or open-ended
• Volume override — any hint that changes candidate or survivor counts

Default volume:

• each ideation frame yields about 6-8 ideas (~36-48 raw across the six frames in the default path, or ~24-32 across 4 frames in issue-tracker mode; roughly 25-30 survivors after dedupe in the default path and fewer in the 4-frame path)
• keep the top 5-7 survivors

Honor clear overrides such as:

• top 3
• 100 ideas
• raise the bar

Depth override. go deep (or equivalent) opts into maximum depth deliberately: every ideation agent moves to the ceiling tier, the Phase 2 verification read budget doubles, and Phase 3 adds a second critic. The default is the mixed-tier fleet — users opt into top-tier cost explicitly rather than inheriting it from whichever model the conversation happens to run on.

Tactical scope detection. Parse the focus hint (and any intake answers from 0.2 specify path) for tactical signals: polish, typo, typos, quick wins, small improvements, cleanup, small fixes. When present, lower the Phase 2 ambition floor — the user has explicitly opted into tactical scope. Default otherwise is step-function (see Phase 2 meeting-test floor).

Use reasonable interpretation rather than formal parsing.

0.6 Cost Transparency Notice

Before dispatching Phase 1, surface the agent count and cost shape 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 + evidence scouts (repo mode only, one per Phase 1.5 axis, max 5, extraction tier) + user-research distillers (one per user-supplied research artifact needing distillation, extraction tier, all modes) + the ideation fleet (5 agents default: 3 generation-tier + 2 ceiling-tier; 6 all-ceiling in surprise-me or go deep; 4 in issue-tracker mode) + 1 basis verifier (generation tier). When issue-tracker intent triggers (repo mode only): add 1 for the issue-intelligence agent. 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. In surprise-me mode, note "(surprise-me mode: deeper exploration per agent)". Phase 2's axis-coverage check may dispatch up to 2 additional recovery sub-agents when generation leaves any topic axis empty (skipped in surprise-me mode); when not in surprise-me, append "(+up to 2 if axis-coverage requires recovery)" to the count line.

Examples (defaults, no skips, no opt-ins):

• Repo mode, specified subject: "Will dispatch ~13 agents, most on cheap tiers: codebase scan + learnings + web research + up to 5 evidence scouts (cheap) + 5 ideation (3 mid-tier, 2 top-tier) + 1 basis verifier (mid-tier). Skip phrases: 'no external research', 'no slack'."
• Repo mode, surprise-me: "Will dispatch ~10 agents (surprise-me mode: deeper exploration per agent): codebase scan + learnings + web research + 6 ideation (top-tier) + 1 basis verifier. Skip phrases: 'no external research', 'no slack'."
• Repo mode, issue-tracker intent: "Will dispatch ~13 agents: codebase scan + learnings + web research + issue intelligence + up to 5 evidence scouts + 4 ideation + 1 basis verifier. 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 the default 5-agent fleet.
• Elsewhere-software: "Will dispatch ~9 agents: context synthesis + learnings + web research + 5 ideation + 1 basis verifier. Skip phrases: 'no external research'."
• Elsewhere-non-software: "Will dispatch ~8 agents: context synthesis + web research + 5 ideation + 1 basis verifier. 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.3. Web research runs in all modes (skip phrases honored). When the user supplied a research artifact, the user-supplied research handling below also runs in all modes. 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.

Surprise-me grounding depth. When Phase 0.2 routed to surprise-me mode, Phase 1 must produce richer material than specified mode — Phase 2 sub-agents will discover their own subjects from what Phase 1 returns, so texture matters:

• Repo mode surprise-me: the codebase-scan sub-agent samples a few representative files per top-level area (not just reads the top-level layout + AGENTS.md), surfaces recent PR/commit activity as signal about what's actively being worked on, and — when issue intelligence runs — passes issue themes as first-class input rather than footnote. Keep the scan bounded: representative, not exhaustive.
• Elsewhere mode surprise-me: user-context synthesis extracts themes, recurring language, tensions, and omissions from whatever the user supplied, rather than just restating it. Web research broadens beyond narrow prior-art for a single subject toward the domain's landscape.
• Specified mode keeps the current shallower scan — the user's named subject anchors what's relevant, so broader exploration is unnecessary.

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 directly under /tmp (not under $TMPDIR and not under .context/). $TMPDIR on macOS resolves to an obscure per-user path like /var/folders/64/.../T/ that is hostile for users who want to inspect checkpoints, copy them elsewhere, or reference them later — /tmp is universally accessible on macOS, Linux, and WSL, and the per-user isolation $TMPDIR provides is not valuable for ephemeral ideation scratch. Run one bash command to create the directory and capture its absolute path for downstream use.

SCRATCH_DIR="/tmp/compound-engineering/ce-ideate/<run-id>"
mkdir -p "$SCRATCH_DIR"
echo "$SCRATCH_DIR"

Use the echoed absolute path (/tmp/compound-engineering/ce-ideate/<run-id>) as <scratch-dir> for every subsequent checkpoint write and cache read in this run. The run directory is not deleted on completion — the V15 cache is session-scoped and reused across run-ids, the checkpoints follow the cross-invocation-reusable convention, and in the no-repo case the deliverable itself is written here (see references/post-ideation-workflow.md Phase 4 and §5.5).

Run grounding agents in parallel in the foreground (do not background — results are needed before Phase 2):

Repo mode dispatch:

Resolve the project profile from the shared cache first. The question-agnostic profile (stack, top-level layout, conventions, root instruction files) is identical whenever committed profile inputs match, so reuse it instead of re-deriving it in the codebase scan. Set SKILL_DIR to this skill's directory and run the helper (full protocol in references/repo-profile-cache.md):

SKILL_DIR="<absolute path of the directory containing the SKILL.md you just read>";
python3 "$SKILL_DIR/scripts/repo-profile-cache.py" get

On HIT, load the profile JSON — that is your agnostic project shape (stack, top-level layout, conventions); do not re-derive it in the scan. On MISS, dispatch a generic subagent with references/agents/repo-profiler.md to derive the profile, write its JSON output to a file under <scratch-dir>, then persist with python3 "$SKILL_DIR/scripts/repo-profile-cache.py" put <file> (re-set SKILL_DIR in that call — shell vars don't persist between Bash invocations). On NO-CACHE, derive the agnostic shape inline (the codebase scan below covers it) and skip the put. The cache is an optimization, never a hard dependency — on any failure or unreadable output, degrade to the full scan. With the profile in hand, the codebase scan runs only the question-specific slice on top of it.

1. Quick context scan — dispatch a general-purpose subagent using the platform's cheapest capable model when the harness exposes a known override; otherwise inherit. Before dispatching, apply the routing test from "User-Supplied Research Artifacts" below to any root-level *.md file the focus hint names: research artifacts (evidence) take that subsection's distillation path, so list them on the prompt's research-artifacts line to keep the scan from duplicating them into User-named references. Dispatch with this prompt:

   Project profile handling (read first): if a project profile is supplied at the end of this prompt, its agnostic shape — stack/language/framework, top-level directory layout, conventions, and root instruction-file content — is already established; do not re-derive it. Skip reading the instruction files and globbing the layout for those facts, and run only the question-specific slice (notable patterns bearing on the focus, pain points, leverage points; in surprise-me mode also sample a few representative files per area and surface recent PR/commit activity). If no profile is supplied, derive the full shape as described below.

   Read the project's root agent-instruction file for this harness (e.g., AGENTS.md, CLAUDE.md, GEMINI.md, or .cursor/rules) and README.md when present, then discover the top-level directory layout using the native file-search/glob tool (e.g., Glob with pattern * or */* in Claude Code). Also read STRATEGY.md if it exists — it captures the product's target problem, approach, persona, metrics, and tracks.

   Two paths for other root-level *.md files, depending on whether the focus hint names them:

   • User-named references — if the focus hint names a specific root-level *.md file (e.g., focus is "ideate based on FEEDBACK.md", "use NOTES.md as input", "review the gaps in TODO.md"), fully read that file and include its content under a heading User-named references. Phase 2 treats these as constraint, so sub-agents need actual content, not a gist. Quote or summarize substantive sections; keep one-line gists for files that are mentioned but not the actual subject. Exception: skip this path for any file listed on the research-artifacts line below — a separate agent distills those; give each only a one-line gist under Additional context.
   • Additional context — for any other root-level *.md files (not named in the focus), read briefly and include a one-line gist under a heading Additional context. Phase 2 treats these as background, so a gist is sufficient.

   Return a concise summary (under 40 lines, longer if user-named references include substantive content) covering:

   • project shape (language, framework, top-level directory layout)
   • notable patterns or conventions
   • obvious pain points or gaps
   • likely leverage points for improvement
   • product strategy summary, if STRATEGY.md was present — include the approach and active tracks verbatim so ideation can weight toward strategy-aligned directions
   • User-named references section (when the focus hint named root-level *.md files)
   • Additional context section (when other root-level *.md files exist that the focus did not name)

   Keep the scan shallow otherwise — read only top-level documentation and directory structure. Do not analyze GitHub issues, templates, or contribution guidelines. Do not do deep code search.

   Focus hint: {focus_hint}

   Research artifacts (gist-only under Additional context — do not fully read; a separate agent distills these): {research_artifact_files, or "none"}

   Project profile (agnostic shape — treat as established, do not re-derive; when "none", derive the full shape): {project_profile, or "none — derive the full shape"}

2. Learnings search — read references/agents/learnings-researcher.md and dispatch a generic subagent seeded with that local prompt plus a brief summary of the ideation focus.

3. Web research (always-on; see "Web research" subsection below for skip-phrase and V15 cache handling).

4. Issue intelligence (conditional) — if issue-tracker intent was detected in Phase 0.3, read references/agents/issue-intelligence-analyst.md and dispatch a generic subagent seeded with that local prompt plus the focus hint. Run in parallel with the other subagents.

   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.

Elsewhere mode dispatch (skip the codebase scan; user-supplied context is the primary grounding):

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.

2. Learnings search (elsewhere-software only; skipped by default in elsewhere-non-software) — read references/agents/learnings-researcher.md and dispatch a generic subagent seeded with that local prompt plus 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.

3. Web research — same as repo mode (see subsection below).

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 the web-researcher local prompt 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 the web-researcher local prompt would be dispatched in this run (and on every subsequent dispatch where the cache might apply).

When dispatching web research, read references/agents/web-researcher.md and seed a generic subagent with that prompt. Pass the focus hint, a brief planning context summary (one or two sentences), and the mode. Do not pass codebase content — the prompt operates externally. Use the platform's mid-tier model when a known override exists; otherwise omit the override and inherit.

User-Supplied Research Artifacts

Applies in all modes whenever the prompt or intake names a file of gathered evidence — a social-listening or search-research report, survey export, analytics dump, interview notes — at any path, inside or outside the repo.

Routing test (directive vs evidence). A named file is directive when ideas that ignore or contradict it would be wrong (a spec, a TODO list, feedback the user wants addressed) — in repo mode that is the User-named references path, and it rides in <constraints> at dispatch. A file is evidence when it is signal about the world that ideas may draw on and cite. Research artifacts are evidence: they enter the evidence layer, never <constraints> — engagement-ranked chatter must inform ideas, not veto them.

Repo-mode coordination. Apply this routing test before dispatching the Phase 1 quick context scan: when a research artifact is a root-level *.md the focus hint names, list it on the scan prompt's research-artifacts line so the scan gists it under Additional context instead of fully reading it into User-named references. Each file takes exactly one path — distillation here, never both.

Enrichment, not substitution. A supplied research artifact does not replace the web-research local prompt dispatch — these artifacts typically cover source classes (social platforms, niche communities, prediction markets, short-video) that web research does not reach, and vice versa. Dispatch web research as normal.

Handling:

• Small artifacts that fold into the grounding summary

…(truncated)