From lets-engineer
Explore requirements and approaches through collaborative dialogue, then write a right-sized requirements document. Use when the user says "let's brainstorm", "what should we build", or "help me think through X", presents a vague or ambitious feature request, or seems unsure about scope or direction -- even without explicitly asking to brainstorm.
How this skill is triggered — by the user, by Claude, or both
Slash command
/lets-engineer:lets-brainstorm [feature idea or problem to explore][feature idea or problem to explore]The summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Note: The current year is 2026.** Use this when dating requirements documents.
Note: The current year is 2026. Use this when dating requirements documents.
Brainstorming helps answer WHAT to build through collaborative dialogue. It precedes /lets-plan, which answers HOW to build it.
The durable output of this workflow is a requirements document. In other workflows this might be called a lightweight PRD or feature brief. In lets-engineer, keep the workflow name brainstorm, but make the written artifact strong enough that planning does not need to invent product behavior, scope boundaries, or success criteria.
This skill does not implement code. It explores, clarifies, and documents decisions for later planning or execution.
IMPORTANT: All file references in generated documents must use repo-relative paths (e.g., src/models/user.rb), never absolute paths. Absolute paths break portability across machines, worktrees, and teammates.
These rules apply to every brainstorm, including the universal (non-software) flow routed to references/universal-brainstorming.md.
AskUserQuestion in Claude Code (call ToolSearch with select:AskUserQuestion first if its schema isn't loaded), request_user_input in Codex, ask_user in Gemini, ask_user in Pi (requires the pi-ask-user extension). These tools include a free-text fallback (e.g., "Other" in Claude Code), so options scaffold the answer without confining it — well-chosen options surface dimensions the user may not have separated, and pick-plus-optional-note is lower activation energy than composing prose from scratch. This default holds for opening and elicitation questions too, not only narrowing. Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question.src/models/user.rb), never absolute paths. Absolute paths make documents non-portable across machines and teammates.<feature_description> #$ARGUMENTS </feature_description>
If the feature description above is empty, ask the user: "What would you like to explore? Please describe the feature, problem, or improvement you're thinking about."
Do not proceed until you have a feature description from the user.
If the user doesn't have a concrete idea yet — they want to figure out what to work on or generate options, rather than refine a direction they already hold — suggest /lets-ideate first to generate and pressure-test candidate ideas, then return here to develop the chosen one. lets-brainstorm explores a specific idea in depth; lets-ideate produces the ideas worth exploring.
If the user references an existing brainstorm topic or document, or there is an obvious recent matching *-requirements.md file in docs/brainstorms/:
Before proceeding to Phase 0.2, classify whether this is a software task. The key question is: does the task involve building, modifying, or architecting software? -- not whether the task mentions software topics.
Software (continue to Phase 0.2) -- the task references code, repositories, APIs, databases, or asks to build/modify/debug/deploy software.
Non-software brainstorming (route to universal brainstorming) -- BOTH conditions must be true:
Neither (respond directly, skip all brainstorming phases) -- the input is a quick-help request, error message, factual question, or single-step task that doesn't need a brainstorm.
If non-software brainstorming is detected: Read references/universal-brainstorming.md and use those facilitation principles. Skip Phases 0.2–4 below — the Core Principles and Interaction Rules above still apply unchanged, including one-question-per-turn and the default to the platform's blocking question tool.
Clear requirements indicators:
If requirements are already clear: Keep the interaction brief. Confirm understanding and present concise next-step options rather than forcing a long brainstorm. Only write a short requirements document when a durable handoff to planning or later review would be valuable. Skip Phase 1.1 and 1.2 entirely — go straight to Phase 1.3 or Phase 2.5 in announce-mode (synthesis emitted for visibility, no blocking confirmation), then to Phase 3.
Use the feature description plus a light repo scan to classify the work:
If the scope is unclear, ask one targeted question to disambiguate and then proceed.
Deep sub-mode: feature vs product. For Deep scope, also classify whether the brainstorm must establish product shape or inherit it:
Product-tier triggers additional Phase 1.2 questions and additional sections in the requirements document. Feature-tier uses the current Deep behavior unchanged.
Scan the repo before substantive brainstorming. Match depth to scope:
Lightweight — Search for the topic, check if something similar already exists, and move on.
Standard and Deep — Two passes:
Constraint Check — Check project instruction files (AGENTS.md, and CLAUDE.md only if retained as compatibility context) for workflow, product, or scope constraints that affect the brainstorm. Also read STRATEGY.md if it exists — the product's target problem, approach, persona, and active tracks are direct input to what this brainstorm should deliver and should shape scope, success criteria, and which approaches are aligned vs out-of-scope. If these add nothing, move on.
Topic Scan — Search for relevant terms. Read the most relevant existing artifact if one exists (brainstorm, plan, spec, skill, feature doc). Skim adjacent examples covering similar behavior.
If nothing obvious appears after a short scan, say so and continue. Two rules govern technical depth during the scan:
Verify before claiming — When the brainstorm touches checkable infrastructure (database tables, routes, config files, dependencies, model definitions), read the relevant source files to confirm what actually exists. Any claim that something is absent — a missing table, an endpoint that doesn't exist, a dependency not in the Gemfile, a config option with no current support — must be verified against the codebase first; if not verified, label it as an unverified assumption. This applies to every brainstorm regardless of topic.
Defer design decisions to planning — Implementation details like schemas, migration strategies, endpoint structure, or deployment topology belong in planning, not here — unless the brainstorm is itself about a technical or architectural decision, in which case those details are the subject of the brainstorm and should be explored.
Before generating approaches, scan the user's opening for rigor gaps. Match depth to scope.
This is agent-internal analysis, not a user-facing checklist. Read the opening, note which gaps actually exist, and raise only those as questions during Phase 1.3 — folded into the normal flow of dialogue, not fired as a pre-flight gauntlet. A fuzzy opening may earn three or four probes; a concrete, well-framed one may earn zero because no scope-appropriate gaps were found.
Lightweight:
Standard — scan for these gaps:
Evidence gap. The opening asserts want or need, but doesn't point to anything the would-be user has already done — time spent, money paid, workarounds built — that would make the want observable. When present, ask for the most concrete thing someone has already done about this.
Specificity gap. The opening describes the beneficiary at a level of abstraction where the agent couldn't design without silently inventing who they are and what changes for them. When present, ask the user to name a specific person or narrow segment, and what changes for that person when this ships.
Counterfactual gap. The opening doesn't make visible what users do today when this problem arises, nor what changes if nothing ships. When present, ask what the current workaround is, even if it's messy — and what it costs them.
Attachment gap. The opening treats a particular solution shape as the thing being built, rather than the value that shape is supposed to deliver, and hasn't been examined against smaller forms that might deliver the same value. When present, ask what the smallest version that still delivers real value would look like.
Plus these synthesis questions — not gap lenses, product-judgment the agent weighs in its own reasoning:
Favor moves that compound value, reduce future carrying cost, or make the product meaningfully more useful or compelling. Use the result to sharpen the conversation, not to bulldoze the user's intent.
Deep — Standard lenses and synthesis questions plus:
Deep — product — Deep plus:
Durability gap. The opening's value proposition rests on a current state of the world that may shift in predictable ways within the horizon the user cares about. When present, ask how the idea fares under the most plausible near-term shifts — and push past rising-tide answers every competitor could make.
What adjacent product could we accidentally build instead, and why is that the wrong one?
What would have to be true in the world for this to fail?
These questions force an explicit product thesis and feed the Scope Boundaries subsections ("Deferred for later" and "Outside this product's identity") and Dependencies / Assumptions in the requirements document.
Follow the Interaction Rules above. Use the platform's blocking question tool when available.
Guidelines:
Before exiting Phase 1.3: integration check. Mentally combine what the user has said so far and surface any non-obvious consequences the dialogue hasn't probed. If user-stated X plus user-stated Y plus your-default-Z produces a downstream effect the user is unlikely to have tracked through one-question-at-a-time dialogue ("if mute lives on the rule AND we don't warn on delete, then rule-delete silently loses pause state"), probe it now while you're still in dialogue. One probe per genuine combination effect, asked open-ended, same discipline as rigor probes. Phase 2.5's call-outs are a safety net for residuals (silent agent inferences, pre-loaded contexts with no dialogue) — NOT a punt list for consequences you could have asked about now.
Exit condition: Continue until the idea is clear AND no integration-check questions are pending, OR the user explicitly wants to proceed.
If multiple plausible directions remain, propose 2-3 concrete approaches based on research and conversation. Otherwise state the recommended direction directly.
Use at least one non-obvious angle — inversion (what if we did the opposite?), constraint removal (what if X weren't a limitation?), or analogy from how another domain solves this. The first approaches that come to mind are usually variations on the same axis.
Present approaches first, then evaluate. Let the user see all options before hearing which one is recommended — leading with a recommendation before the user has seen alternatives anchors the conversation prematurely.
When useful, include one deliberately higher-upside alternative:
At product tier, alternatives should differ on what is built (product shape, actor set, positioning), not how it is built. Implementation-variant alternatives belong at feature tier.
For each approach, provide:
Approach granularity: mechanism / product shape, not architecture. Approach descriptions name mechanism-level distinctions ("pause as a rule property" vs "pause as an event filter" vs "pause as a separate entity") and product-relevant trade-offs (plan-tier coupling, complexity surface, migration difficulty). They do NOT name implementation specifics — column names, table names, file paths, service classes, JSON shapes, exact method names. Those are lets-plan's job. Bringing architecture forward at brainstorm time forces the user to make architectural decisions on lets-brainstorm's intentionally-shallow research, and the synthesis at Phase 2.5 then has to filter out the leak.
After presenting all approaches, state your recommendation and explain why. Prefer simpler solutions when added complexity creates real carrying cost, but do not reject low-cost, high-value polish just because it is not strictly necessary.
If one approach is clearly best and alternatives are not meaningful, skip the menu and state the recommendation directly.
If relevant, call out whether the choice is:
STOP. Before composing the synthesis, read references/synthesis-summary.md. The two-stage shape (internal three-bucket draft → chat-time scoping synthesis), the Path A / Path B gate, the four scoping synthesis sections with their keep tests, the tier-aware bullet budget with re-cut rule, anti-pattern guidance, soft-cut behavior, self-redirect support, and internal-draft routing into doc body sections all live there. Composing a synthesis without these rules loaded reliably produces malformed output — pasting the full internal three-bucket draft verbatim into chat, implementation-detail leakage into the scoping synthesis, the proposal-pitch anti-pattern. Each scoping synthesis bullet must pass the affirmability test (can the user evaluate this without reading code?) AND the detail test (1–2 lines max, conversational not documentary); over-share and over-detail are the failure modes to avoid. This is not optional supplementary reading; it is the source of truth for how the phase behaves.
Surface a scoping synthesis to the user before Phase 3 writes the requirements doc — the user's last opportunity to correct scope before the artifact lands. The scoping synthesis is shaped like what two product collaborators would confirm before writing a PRD, not like a comprehensive audit or a one-line preview.
Fires for all tiers including Lightweight. Skip Phase 2.5 entirely on the Phase 0.1b non-software (universal-brainstorming) route.
Path A vs Path B: the scoping synthesis shape depends on TWO signals — whether any blocking question fired AND what tier Phase 0.3 classified the scope as.
Why the tier guard on Path A: Phase 0.2's fast path serves two very different cases — a tight one-liner that needs no dialogue ("fix the typo on line 47") and a richly pre-loaded brainstorm context that ALSO needs no dialogue because the user pre-stated everything. Without the tier guard, both route to Path A and the pre-loaded case gets a 1-sentence checkpoint for what may be 20+ items worth of scope. Tier-classifying Phase 0.3 distinguishes the two — pre-loaded substance makes the tier Standard or Deep, which then routes to Path B.
Write or update a requirements document only when the conversation produced durable decisions worth preserving. Read references/requirements-capture.md for the document template, formatting rules, visual aid guidance, and completeness checks.
For Lightweight brainstorms, keep the document compact. Skip document creation when the user only needs brief alignment and no durable decisions need to be preserved.
Present next-step options and execute the user's selection. Read references/handoff.md for the option logic, dispatch instructions, and closing summary format.
npx claudepluginhub williamzelesny/lets-engineer --plugin lets-engineerGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.