Grilling Ideas

Grill Idea

User Input

$ARGUMENTS

Treat $ARGUMENTS as the seed idea. If empty, ask the user for it once before starting the interview.

What this does

Interview the user relentlessly about every aspect of a feature idea until it is sharp enough to hand off to whatever comes next (a PRD, a spec, a speckit run, or a ticket). Walk down each branch of the idea tree, resolving dependencies between decisions one-by-one. For each question, propose your recommended answer first, then wait for feedback before asking the next one. If a question can be answered by reading the codebase or the project's own documentation, do that instead of asking.

The output is a structured idea brief that lives in the conversation by default — no files are written. If the user asks for a written artefact, write it to a temporary path under the system temp directory (e.g. $(mktemp -t idea-brief.XXXXXX.md)) and report the path. Do not write to .specify/idea-brief.md — that location is reserved for a speckit-specific workflow and is out of scope for this skill.

When to use

• The user has an idea expressed in one or two paragraphs and wants a sharper version.
• The idea is fuzzy on scope, users, success, or how it fits the existing system.
• The user explicitly says they want to grill / stress-test / pressure-test an idea before formalising it.

Do not use this skill for:

• A bug fix or refactor with no user-visible behaviour change — go straight to a regular PR or the project's bug pipeline.
• An idea the user has already turned into a spec or PRD — the grilling moment has passed; refine the existing artefact instead.

Discover available context (read what exists, skip what doesn't)

Before the first question, probe the repository for project-level context files. Read whichever are present. None of them are required — the skill must work in a repo that has none of them.

Probe with a quick ls/test -f pass rather than reading the whole tree. Read in full only the files that genuinely matter for this idea.

If none of these exist, you fall back to plain interviewing — the lenses below still apply; you just don't have a project-specific frame to test against.

How to interview

• One question at a time. Do not batch. Wait for an answer before the next question.
• Lead with your recommendation. Format each turn as: short context → question → your recommended answer with reasoning → invite confirmation or redirection.
• Explore before asking. If anything in the repo (the context files above, the codebase, ADRs, existing specs/issues) can answer the question, read and report rather than asking.
• Cross-reference with code. When the user asserts how something works today, verify against the relevant files. Surface contradictions immediately.
• Sharpen fuzzy terms. If CONTEXT.md exists, pin every domain term the user uses to a canonical entry. If it does not, still push back on synonyms drifting mid-conversation — pick one term and stick to it.
• Use concrete scenarios. When relationships are vague, invent a specific example ("imagine a user upgrades v1.2 → v1.3 mid-operation — what should happen?") and force a precise answer.
• Capture clarifications inline in the conversation. Update the in-session brief as decisions land. Don't batch at the end.

Glossary drift (only when CONTEXT.md is present)

If CONTEXT.md exists, treat it as the project's living glossary and watch for drift during the interview. Surface — and offer to fix — any of:

1. A new domain concept the idea introduces that isn't in CONTEXT.md yet.
2. An existing concept used in the codebase but missing from the glossary.
3. A CONTEXT.md entry that is wrong, stale, or ambiguous given what the conversation reveals.
4. A new ambiguity between two terms.

For each, ask the user once whether to add/update the entry. Do not silently edit CONTEXT.md — propose the diff, get a yes, then apply it surgically (**Term**: definition. _Avoid_: synonyms.). If CONTEXT.md does not exist in the repo, skip this section entirely.

Grilling lenses

Every idea should be exercised through these lenses, in this order. Skip a lens only if you can justify why it does not apply.

1. Users and value

• Who is the primary user? (a developer, an operator, an end-user of a deployed system, an internal stakeholder?)
• What can they not do today, or what is painful?
• What is the smallest observable change that would make them say "this is better"?

2. User journeys (P1/P2/P3)

Pin down at least one P1 journey before considering the idea grilled. Each journey must be a slice that could ship on its own and still deliver value.

• What is the P1 journey end-to-end? (single sentence)
• Is there a P2 / P3? If yes, can each be developed, tested, deployed, demoed independently?
• For each: write a Given / When / Then acceptance scenario before moving on.

3. Functional requirements

• What MUST the system do that it does not do today? Express as testable System MUST … statements.
• What MUST users be able to do? (Users MUST be able to …)
• For every "MUST", ask: how would you verify this in a test? If you cannot describe a test, the requirement is not yet testable — sharpen it.

4. Key entities and domain fit

• Which existing entities or concepts are touched? If CONTEXT.md exists, use the canonical names from it. Otherwise infer the vocabulary from the codebase or surrounding docs and stick to one name per concept.
• Are new entities required, or can the idea be expressed in terms of existing ones? Strongly prefer the latter.
• If a new entity is needed: what is its lifecycle, who owns it, what is its relationship to existing entities?

5. Edge cases

• Boundary conditions (empty, max, concurrent, partial).
• Failure modes (network, validation, permission, drift between desired and actual state).
• "What happens when … ?" — invent at least three scenarios and force an answer for each.

6. Success criteria

Push the user past vibes. Each criterion must be measurable and technology-agnostic:

• Replace "faster" with "in under N seconds".
• Replace "more reliable" with "P99 success rate ≥ X%".
• Replace "easier" with a task-completion metric or a reduction in support load.
• Reject criteria that name a framework, library, database, or response-time-in-ms (those are implementation, not user value).

7. Governance gates and project rules

The idea must respect whatever the project has already written down. Two sources to check:

• Governance gates — many AGENTS.md files list "ask first" areas (database / schema migrations, API or GraphQL changes, new external dependencies, CI/CD changes, auth changes). Read AGENTS.md if it exists and use whatever list it names. For each gate the idea crosses, name it in the brief under Governance Gates Crossed so it cannot be missed later.
• Constitution principles (only if dev/constitution.md is present) — walk its principles and flag any the idea pushes back on. A pushback may need to become an Assumption, a Governance Gate decision, or a reason to reshape the idea. Skip entirely if no constitution document exists.