guild-brainstorm

name	guild-brainstorm
description	Socratic clustered-question flow that turns a vague user brief into an approved `.guild/spec/<slug>.md`. Captures the seven planning-contract fields — goal, audience, success criteria, non-goals, constraints, autonomy policy, and known risks/rollback — plus an eighth assumptions-vs-blocking-unknowns roll-up. TRIGGER on "let's plan X", "help me scope this feature", "what are we actually building", "start a new Guild task", "I have a vague idea for …", or any `/guild` invocation with a brief shorter than the planning-contract checklist. Supports a `--skip` escape hatch (for users who already have a clear spec); in that mode the skill validates the supplied spec and flags gaps instead of asking the full question set. DO NOT TRIGGER for implementation requests (hand off to `guild:execute-plan`), team composition (hand off to `guild:team-compose`), direct code or file edits, or micro-tasks like typo fixes and branch pushes.
when_to_use	First step of the `/guild` lifecycle. Fires when a user invokes `/guild` with a vague brief, or when a specialist downstream needs the user's intent clarified before `guild:team-compose` can run.
type	meta

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:

npx tsx ${GUILD_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$HOME/.local/share/guild/dist/claude-code}}/scripts/ideation-min-build-cli.ts --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.

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/learning-checkpoint/SKILL.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.