guild-brainstorm

guild:brainstorm

This is the first step of every /guild task — ambiguity is front-loaded here so downstream specialists work from a single, approved spec instead of re-asking the user across every handoff. The spec produced here is the planning contract all downstream skills consume.

What you do

Run a short Socratic conversation organized into clusters — not a flat questionnaire. Each cluster groups related §8.1 fields so the user answers one coherent set at a time (e.g. goal + audience + outcome together, constraints + autonomy + risks together). Reflect back each cluster in one sentence before moving on, so the user can correct drift early. When every §8.1 field has a confirmed answer (or an explicit assumption), write .guild/spec/<slug>.md and hand off to guild:team-compose.

Knowledge-binding — min-build resolver (run FIRST, deterministic)

Ideation's required upstream is an init wiki. Before the Socratic flow, run the deterministic resolver — never eyeball whether init ran:

node ${GUILD_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$HOME/.local/share/guild/dist/claude-code}}/runtime/scripts/ideation-min-build-cli.js --cwd "$(pwd)" [--description "<one-line brief>"]

• {"needsMinBuild": false} → an init wiki exists; proceed normally.
• {"needsMinBuild": true, "spec": …, "frontmatter": …} → no init wiki. Do not refuse and do not silently invent project knowledge. Instead, this is the build-minimal continuity case (lifecycle §"A min-build spec"): seed the spec from the resolver baseline (its goal/audience/constraints are clearly-marked placeholders to confirm with the user during the clusters), and stamp the spec frontmatter with the returned frontmatter block — grounded_in: init_minimal, resolver_built: true, the gap notice, and resolved_at. Surface the gap to the user verbatim ("this spec was resolver-built and lacks real project knowledge; run /guild:init to replace it"). The G-knowledge-binding step is non-blocking — it marks the missing-init risk, it does not stop ideation. A later /guild:init replaces the baseline; it is never a silent substitute for real project knowledge.

Required capture (per §8.1)

The spec is not approved until every item below is either answered or explicitly converted to an assumption:

1. Goal and user-visible outcome — what changes for the end user when this is done.
2. Target audience or operator — who experiences the outcome or runs the artifact.
3. Success criteria and acceptance tests — measurable conditions the task must meet. Vague vibes ("feels better") are rejected.
4. Non-goals — explicit list of things the task is not doing, to stop scope creep downstream.
5. Constraints — time, budget, stack, platform, legal/compliance, brand, security. Anything that bounds the solution space.
6. Autonomy policy — what Guild may do without asking, what requires confirmation, what is forbidden. This becomes the specialists' permission contract.
7. Known risks and rollback/release expectations — what could go wrong and how the user expects to back out if it does.
8. Assumptions vs. blocking unknowns — per §8.1, blocking unknowns must be answered or explicitly converted into assumptions recorded in .guild/runs/<run-id>/assumptions.md. Low-significance uncertainty also goes in that file for end-of-task review.

Output contract

Write .guild/spec/<slug>.md with YAML frontmatter + a markdown body. Minimal template:

---
type: spec
owner: orchestrator
confidence: medium
source_refs: []
created_at: 2026-04-24
updated_at: 2026-04-24
---

# <Task title>

## Goal & outcome
<one or two sentences>

## Audience / operator
<who>

## Success criteria
- <measurable criterion 1>
- <measurable criterion 2>

## Non-goals
- <explicit out-of-scope 1>

## Constraints
- time: <...>
- stack: <...>
- legal/brand/security: <...>

## Autonomy policy
- may act without asking: <...>
- requires confirmation: <...>
- forbidden: <...>

## Risks & rollback
- <risk> → <rollback plan>

## Assumptions (from brainstorm)
- <assumption, with "user explicitly agreed" or "inferred, low-significance">

Blocking unknowns: if the user explicitly chooses to convert a blocking unknown into an assumption rather than answer it, record it in both the spec's Assumptions section and .guild/runs/<run-id>/assumptions.md so it surfaces at guild:verify-done. Frontmatter confidence drops to low whenever ≥ 1 blocking unknown is assumed-through.

--skip escape hatch

If the user invokes /guild ... --skip and supplies a spec (pasted text or a path), do not run the Socratic flow. Instead:

1. Parse the supplied spec.
2. Check each of the 8 capture items above. Missing items are listed back to the user in a single consolidated question — not a new full question flow.
3. If the user confirms "proceed anyway" for any gap, record that gap as an assumption (see Output contract) and drop confidence to low.
4. Write .guild/spec/<slug>.md and hand off.

Red flag: do not auto-fill missing fields from training-data priors. A missing field is either answered by the user in the consolidated follow-up, or recorded as an explicit assumption — never silently synthesized.

Adversarial review — G-spec (broker, when policy fires)

G-spec is a skill-internal gate (docs/v2/adversarial-review.html §Gate ownership): it fires here inside guild:brainstorm at the spec→approval boundary, not from a command — which is why it doesn't appear in build's skill row. Wire the review broker at this boundary, not guild:codex-review directly: the broker is the host-agnostic front door, and guild:codex-review survives only as the internal Codex adapter the broker dispatches to (docs/v2/adversarial-review.html §The review broker).

After writing the spec and before asking the user for approval, invoke guild:review-broker:

Skill: guild-review-broker
args: gate=G-spec artifact_path=.guild/spec/<slug>.md run_id=<run-id> author_host=<run author host>

The broker is policy-gated (docs/v2/adversarial-review.html §The review broker): it fires only when risk ≥ high, review: cross / --review=cross is set, or project config requires it — otherwise it resolves status: "skipped" and the gate passes with no reviewer. Self-build runs treat cross-host review as always-on. author_host is the host that produced the spec (resolved from the run-start preflight snapshot; claude on a Claude-hosted run).

If the broker returns status: "rework", loop back to the spec revision flow with the findings as context. On "satisfied", "skipped", or "force_passed", proceed to the user-approval question normally.

The gate runs between spec write and user-approval. It does not replace user approval — both must complete before handoff to guild:team-compose.

The reviewer slot is a phase participant — sequence the gate BEFORE the broker. A cross-host G-spec reviewer is a dispatchable participant of the ideate phase (participation_kind: reviewer_cross_host), so its dispatch rides the phase's guild.team_proposal.v2 → guild.team_decision.v1 gate. Operational order inside this skill: (1) write the draft spec; (2) resolve the broker policy first, without dispatching — the fire/skip predicate (risk ≥ high / review: cross / --review=cross / config; self-build = always-on) is a deterministic read of run posture + config, so evaluate it before composing anything: if it resolves to no-fire, record status: "skipped", compose NO proposal, and go straight to spec user-approval (nothing dispatches); (3) if it fires, compose the minimal ideate-phase proposal (typically the single reviewer slot; spec_ref = the just-written draft spec bytes — an early-phase proposal per guild:team-compose §"Team decision gate"); (4) hold for the user's approve; (5) only then invoke the broker; (6) proceed to spec user-approval. The full spec-driven composition still happens later at guild:team-compose for the plan phase. An advisory/review label never bypasses the gate.

Learning checkpoint (step 7.5 — advisory, no new gate)

After the G-spec review and before handoff, fire the per-phase LearningCheckpoint with phase=ideation and .guild/spec/<slug>.md as evidence_ref. Invoke guild:learning-checkpoint to classify the already-written spec/assumptions into the 12-target verdict, then emit via the hook — the full call signature + GUILD_PHASE mapping are canonical in skills/meta/reflect/references/learning-checkpoint.md §"How a phase skill fires the checkpoint" (do not re-spell). It rides this existing boundary, defaults to all-none (a near-zero-token no-op), asks no new prompt, and adds no new gate; non-none verdicts route only to .guild/reflections/<run-id>.md.

Handoff

Once the spec is written and the user has explicitly approved it (not just "looks fine" — the word "approved" or an equivalent affirmative), invoke guild:team-compose with the spec path as its argument. Do not continue into team composition on your own; guild:team-compose is a separate skill with its own responsibilities.

Handoff receipt should list: spec_path, assumptions_count, blocking_unknowns_converted (boolean), and confidence from the spec frontmatter.

Chapters

Three-stage disclosure (KTD25): this file is the assembler. Each row below is an L3 chapter that stays on disk until a request matches it. Compose by pointer — read the one chapter you were routed to, and never inline a chapter here.

Chapter	Covers
references/io-contract.md	reference material for this assembler
references/loop-clarify.md	F-1 adversarial pre-spec clarification driver — wraps guild:brainstorm, runs an architect↔researcher loop where the architect proposes scope and the researcher fact-checks, surfaces gaps, and either signals satisfaction with the literal sentinel ## NO MORE QUESTIONS or returns more questions
references/loop-mechanics.md	reference material for this assembler
references/product-explore.md	Product-loop EXPLORE producer — turns a vague product idea into a typed, fail-closed guild.explore.v1 artifact before any engineering scoping

Chapter pointers (resolve before you dispatch)

These names appear in the body as if they were skills. They are NOT — the T03 fold (KTD25/KTD59) made each one an L3 chapter. Read guild:<name> below as "load this file and run it in place"; never try to dispatch it as a skill.

Named in this body	Lives under	Load
guild:codex-review	review	../review/references/codex-review.md
guild:learning-checkpoint	reflect	../reflect/references/learning-checkpoint.md
guild:review-broker	review	../review/references/review-broker.md
guild:verify-done	quality	../../quality/references/verify-done.md