ideate

Files (5)

• README.md
• SKILL.md
• examples.md · references/
• frameworks.md · references/
• refinement-criteria.md · references/

SKILL.md (first lines)

# Ideate

Turn raw ideas into sharp, SpecScore-compatible Idea artifacts through structured divergent and convergent thinking.

## Hard Gate

<HARD-GATE>
Do NOT invoke `specstudio:specify`, `specstudio:plan`, `specstudio:implement`, `writing-plans`, or any implementation skill until:
  1. An Idea artifact has been written to `spec/ideas/<slug>.md`.
  2. `specscore spec lint` passes.
  3. The user has explicitly approved the Recommended Direction.

Ideas that can't be lint-clean aren't ready to be specified.
</HARD-GATE>

## When to Use

- Raw, vague, or unvalidated concept.
- User unsure whether an idea is worth building.
- Multiple possible directions with no clear winner.
- **Promoting a captured seed** — the user wants to turn an existing sidekick seed (`spec/ideas/seeds/<slug>.md`) into a full Idea. See [Promoting a Sidekick Seed](#promoting-a-sidekick-seed) below.
- **Skip** when: the user already has an approved Idea or a clear, high-conviction feature to specify — go straight to `specstudio:specify`.

## Promoting a Sidekick Seed

Entry mode for turning an existing sidekick seed at `spec/ideas/seeds/<slug>.md` into a full Idea. Triggers: "promote seed `<slug>`", "pick up seed `<slug>`", "ideate from the `<slug>` seed". This path delegates the file transformation to the `specscore idea promote` CLI verb and then continues the normal authoring flow below — it does **not** hand-move the seed or hand-write the Idea.

1. **Resolve the seed** at `spec/ideas/seeds/<slug>.md`. If it doesn't exist, say so and stop (don't silently scaffold a fresh Idea).
2. **Consilium offer (unreviewed, manual pick).** A manually-picked seed is pulling from the queue out of band, so if the seed has **no `## Consilium Verdict` section**, OFFER to run the consilium first (`specstudio:consilium`) before promoting. Default to **yes** on an empty response (offer-and-default-to-yes). The offer is **suppressible**: when `specscore.yaml` has `promote.offer_consilium: false`, skip it and promote directly. The user MAY decline; on decline, promote without a verdict. Never hard-require a verdict, never block on decline.
3. **Delegate to the CLI.** Run `specscore idea promote <slug>` (add `--verdict=<pointer|full|drop>` only to override the project default; `--force` only to overwrite an existing Idea at that slug). The verb owns the `git mv`, the seed→Idea transform, same-repo back-link reconciliation, and the cross-repo archive — do NOT replicate any of that by hand. Branch on exit status per [`../shared/cli-detection.md`](../shared/cli-detection.md):
   - **exit `127`** — the verb isn't installed. Tell the user to update the `specscore` CLI (the `idea promote` verb ships in **v0.6.1+**). Do **not** fall back to hand-moving the seed — there is no fallback for promotion.
   - **any other non-zero** — surface the error verbatim and stop; do not hand-edit.
   - **success** — the verb prints the created Idea path (and the seed's fate: `moved` for same-repo, `archived` for cross-repo).
4. **Fill the skeleton.** The verb leaves a lint-clean Idea at `spec/ideas/<slug>.md` with the seed body folded into `## Context` and HTML-comment prompts for the rest. Fill the remaining sections (Recommended Direction, Alternatives Considered, MVP Scope, Not Doing, Key Assumptions, SpecScore Integration, Open Questions) via the normal **Phase 3** authoring, then continue the **Checklist from step 6 (Lint)** onward — self-review, publication checkpoint, user review gate, and `idea.drafted` / `idea.approved` events all apply unchanged. Promotion yields a `**Status:** Draft` Idea.

## Philosophy

See [philosophy.md](../shared/philosophy.md). Key tenets here: *simplicity is the ultimate sophistication*, *say no to 1,000 things*, *challenge every assumption*, *unsaved ideation is waste*, *prefer stable CLI contracts over ad-hoc file writes when both are possible*.

## Path Conventions

Artifacts land at `spec/ideas/<slug>.md`. See [path-conventions.md](../shared/path-conventions.md). Never use `docs/ideas/`.

If `spec/ideas/` does not exist when the skill is invoked, do not hand-bootstrap it. `specscore idea new <slug>` owns the artifact and ancestor-index creation path; tell the user that the CLI will bootstrap the ideas tree if needed.

## Checklist

Create a task for each and complete in order:

1. **Explore project context** — existing Features, architecture, related Ideas (`Glob`, `Grep`, `Read`).
2. **Scope decomposition check** — if the request describes multiple independent subsystems, stop and help the user split into multiple Ideas before proceeding.
3. **Phase 1 — Understand & Expand** (divergent).
4. **Phase 2 — Evaluate & Converge**.
5. **Phase 3 — Crystallize** as a SpecScore Idea artifact. Create the artifact with the `specscore idea new` CLI scaffold — the required creation path that also bootstraps missing ancestor indexes (see Phase 3 below).
6. **Lint** the artifact: `specscore spec lint`. On failure, run `specscore spec lint --fix` once, re-lint; surface remaining violations to the user.
7. **Publication checkpoint** — add every file the CLI created and every file you edited (`spec/ideas/<slug>.md`, plus CLI-reported ancestor indexes if any) to the checkpoint manifest and apply [publication-policy.md](../shared/publication-policy.md) for the lifecycle event being emitted.
8. **Inline self-review** — placeholders, contradictions, ambiguity, scope.
9. **User review** — present the lint-clean artifact, then resolve any open questions before requesting approval (see [User Review Gate](#user-review-gate)): when `## Open Questions` is non-empty, state the count, list them, and offer wizard / chat / skip via `AskUserQuestion`, folding answers back into the artifact. Then ask the user to review and approve the Recommended Direction. Recognize explicit approval phrases (`approve`, `approved`, `accept`, `accepted`, `lgtm`, plus their semantic equivalents in the user's language); treat vague positive signals as soft and ask one explicit confirmation question.
10. **Emit events** — `idea.drafted` on every successful lint pass while `**Status:** Draft`; `idea.approved` exactly once on approval; `idea.updated` on every successful lint pass while `**Status:** Approved`. Apply publication policy before emission so each event carries `publication_result`. Both `drafted` and `updated` payloads carry `changed_sections`, `previous_revision`, and a factual `change_summary` (≤2 sentences). See [events.md](../shared/events.md).
11. **Throughout** — watch for sidekick ideas per [sidekick-capture.md](../shared/sidekick-capture.md). When an out-of-scope improvement surfaces, invoke `specstudio:sidekick` with a one-liner, acknowledge in one line, and return to the current checklist step immediately. Do not derail to discuss the sideline idea.

## Phase 1 — Understand & Expand (Divergent)

**Goal:** Open the idea up before narrowing.

1. **Restate as a "How Might We…"** sentence. Forces clarity on what's actually being solved.
2. **Ask 3–5 sharpening questions** (batched — see [question-cadence.md](../shared/question-cadence.md)). Focus:
   - Who is this for, specifically?
   - What does success look like?
   - What are the real constraints (time, tech, resources)?
   - What's been tried before?
   - Why now?

   Use `AskUserQuestion`. Do NOT proceed until you know *who* and *success*.

3. **Generate 5–8 variations** using these lenses:
   - **Inversion** — what if we did the opposite?
   - **Constraint removal** — what if budget/time/tech weren't factors?
   - **Audience shift** — what if this were for a different user?
   - **Combination** — what if we merged this with an adjacent idea?
   - **Simplification** — what's the version that's 10x simpler?
   - **10x** — what would this look like at massive scale?
   - **Expert lens** — what would domain experts find obvious?

   Push beyond what the user asked for. See [frameworks.md](references/frameworks.md) for additional frameworks (SCAMPER, JTBD, First Principles, Pre-mortem, Analogous Inspiration). Pick the lens that fits — don't run every framework mechanically.

**If inside a codebase:** ground variations in what actually exists. Reference specific files and patterns.

## Phase 2 — Evaluate & Converge

After the user reacts to Phase 1, shift to convergent mode. Cadence becomes **single question at a time**.

1. **Cluster** ideas that resonated into 2–3 meaningfully different directions.
2. **Stress-test** each direction on three axes — see [refinement-criteria.md](references/refinement-criteria.md):
   - **User value** (painkiller vs. vitamin)
   - **Feasibility** (technical + resource + time-to-value)
   - **Differentiation** (new capability? 10x? new audience? new context? better UX?)
3. **Surface hidden assumptions** in three tiers:
   - **Must be true** (dealbreakers — validate before building)
   - **Should be true** (significant impact, but recoverable)
   - **Might be true** (secondary; don't validate yet)

**Be honest, not supportive.** If a direction is weak, say so with specificity and kindness.

## Phase 3 — Crystallize as a SpecScore Idea

**Creation is required-CLI.** `specscore idea new <slug>` is the ONLY way to create the artifact — it produces a lint-clean skeleton by construction and updates `spec/ideas/README.md` for you. There is no direct-write fallback: the CLI scaffold is the single source of truth for the Idea's structure. Subsequent edits must preserve that lint-clean state. This follows the Required-CLI Artifact Creation policy — see the Creation-class row in [`../shared/cli-detection.md`](../shared/cli-detection.md).

### Step 3.0 — Let the CLI bootstrap missing indexes

Before invoking the CLI, you MAY note whether `spec/ideas/` is absent so the user is not surprised by extra paths in the checkpoint manifest. Do not create directories or indexes yourself. `specscore idea new <slug>` materializes the required ancestor indexes (`spec/README.md`, `spec/ideas/README.md`) when absent, using the canonical templates owned by the SpecScore CLI. For the read-only contract, see [`https://specscore.md/idea-specification`](https://specscore.md/idea-specification) and the CLI's `idea new` documentation; never copy those templates into this skill.

### Step 3a — Detect the CLI (per the shared convention)

`ideate` is a **creation-class** skill: the CLI is required and there is no direct-write fallback. Do **not** run a standalone `command -v` probe. Invoke the scaffold call (Step 3b's `specscore idea new`) and branch on its exit status per the **Creation-class row** in [`../shared/cli-detection.md`](../shared/cli-detection.md) (which carries the per-outcome rationale): **`0`** → continue on the CLI path (Step 3b, step 2); **`127`** → install message (`/specscore:install`), then **install-then-retry**; **exit `8`** → **upgrade-then-retry**, naming the missing `idea new` subcommand; **any other non-zero** → surface verbatim, **never** a hand-written fallback.

### Step 3b (CLI path) — Scaffold, then fill

1. Invoke `specscore idea new <slug>` with every field you already have. Only these flags exist — do not invent others:

From specscore/specstudio-skills, MIT.

More from specscore/specstudio-skills