# Clarify > Resolve a feature idea into a brainstorm doc through a relentless one-question-at-a-time grilling loop. Eagerly loads vocab and ADR indexes; explores the codebase before asking questions whose answers are derivable from code. Fires at workflow start. - Skill: `jdforsythe/clarify` (Agent Skill) - Install (CLI): `npx skillmds@latest add jdforsythe/clarify` - Raw SKILL.md: https://api.skillmd.com/api/skills/jdforsythe/clarify/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: jdforsythe (https://skillmd.com/u/jdforsythe) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/jdforsythe/clarify --- ## Summary Triggered by any feature-workflow start ("I want to build X"). Eagerly loads the vocabulary and ADR indexes at session start — index layer only. Asks exactly one question per turn, chosen to resolve the most important open uncertainty. Before asking a question whose answer may be in the codebase, explores the code and either answers it or sharpens the follow-up. Continues until a brainstorm doc can be written. Produces `docs/brainstorms/.md` with valid workflow-doc frontmatter and a `## Summary` block of ≤5 lines. ## Procedure ### Step 1 — Load substrate indexes (eager, before first question) Before saying anything else, read: - `.substrate/vocabulary/INDEX.md` - `.substrate/adr/INDEX.md` Read the index layer only — do not open any entry body files. If an index description is ambiguous relative to the feature idea, open that entry's body (via `substrate-read`) to resolve the ambiguity. Record what the indexes reveal: known terms, accepted decisions, and any constraints directly relevant to the stated idea. ### Step 2 — Identify the most important open uncertainty Before composing a question, enumerate the categories of uncertainty that typically gate a brainstorm: 1. **Recipients / scope** — Who is affected? Which users, roles, or external parties? 2. **Trigger / cause** — What event or action initiates the feature? 3. **Delivery / mechanism** — How does the outcome reach the recipient? 4. **Persistence / state** — What state must survive the interaction? 5. **Constraints / integration** — What existing decisions constrain the design? Select the single uncertainty that, if left unresolved, would block all other reasoning. That is the topic of the next question. **Substrate check before selecting:** If the indexes already resolve one of these categories (e.g., an ADR commits to a delivery mechanism), mark that category as resolved and skip it. ### Step 3 — Explore the codebase before asking (when applicable) If the chosen uncertainty might be answered by existing code, explore the codebase first: - Look for relevant modules, models, and interfaces related to the topic. - Look for existing infrastructure (event buses, queues, delivery clients, auth middleware) that constrains the design. - Look for data models that reveal implicit scope (e.g., `user.model.ts` with `email` and `phone` fields implies delivery channel options already exist). If exploration resolves the uncertainty: do not ask the question. Instead, state what you found and select the next uncertainty. If exploration narrows the uncertainty: incorporate the finding into a more targeted question. Do not ask "should we use X or Y?" when the codebase already uses X. ### Step 4 — Ask exactly one question Compose a single question that resolves the chosen uncertainty. The question must be: - **One question only.** Do not bundle sub-questions. Do not offer a numbered list of questions. - **Targeted.** Reflect what you found in Steps 1–3. Do not ask about things already resolved by substrate or codebase. - **Open-ended enough** to reveal unexpected constraints the user holds. Avoid yes/no questions unless the topic genuinely reduces to a binary. Before the question, state briefly what you learned from the substrate indexes or codebase exploration that motivates asking this particular question. Keep this framing to 1–2 sentences. ### Step 5 — Process the answer and repeat After the user answers: 1. Mark the resolved uncertainty as settled. 2. Return to Step 2 to identify the next most important open uncertainty. 3. Repeat Steps 2–4 until the brainstorm is ready to write (see Step 6). Do not revisit a settled topic unless the user's later answer contradicts an earlier one. ### Step 6 — Decide when to stop grilling Stop when you can answer all of the following from resolved uncertainties: - Who is affected? - What triggers the feature? - What is the delivery or outcome mechanism? - What constraints or prior decisions govern the design? - What is explicitly out of scope for this workflow? Typically requires 4–6 questions. Do not stop early just because you could write a plausible document — stop only when the above questions are genuinely settled. Do not continue beyond 8 questions; if uncertainty remains after 8 turns, write the brainstorm with explicit "open question" callouts in the body. ### Step 7 — Write the brainstorm doc Create `docs/brainstorms/` if it does not exist. Choose a `workflow_id` for this brainstorm using the workflow-id convention: strip articles from the feature idea, take the first 4–6 content words in kebab-case (e.g. "add notification system workspace members" → `add-notification-system-workspace-members`). The `id` field uses the same value. Write `docs/brainstorms/.md` with this structure: ```markdown --- id: type: brainstorm description: created: workflow_id: --- ## Summary <≤5 lines synthesizing the resolved answers: who is affected, what triggers it, how it works, key constraints> ## Scope ## Trigger ## Mechanism ## Constraints ## Out of scope ## Open questions ``` After writing the file, confirm the path to the user and state that the brainstorm is ready for the `research` phase. ## Constraints - Never ask more than one question per turn. - Never ask about a topic already resolved by a substrate index entry or by codebase exploration. - Never write the brainstorm doc before all five categories in Step 6 are settled (or explicitly called out as open questions after 8 turns). - The `description` field in the brainstorm frontmatter must be ≤200 characters. - The `## Summary` block must be ≤5 non-blank lines. - The `workflow_id` and `id` fields must match and conform to the workflow-id convention (kebab-case, `[a-z0-9-]`, max 50 chars).