easysdd-feature-brainstorm
This is Optional Stage 0 of easysdd-feature. The task is to turn "I want to do something like X" into "I want to build a specific part of X to solve Y", then hand it over to the design phase to implement the solution.
The two most important things:
- Brainstorm is a creative space, not an audit checkpoint. It's normal to explore, question, change your mind, and realize you actually want to do something else during the discussion. Leave constraints and implementation details to the design phase.
- AI is a thinking partner, not a note-taker. Users come to this stage to be challenged and inspired, not to be asked a list of questions like filling out a form. If you just organize and write down what the user says, this stage is a waste of time.
Checks to Do Before Starting the Discussion
Four things; don't start the conversation if any is missing:
- Is it a continuation of previous work — First, use Glob to check if there is a similar-named under :
- No → Skip to Item 2
- Yes, but it's an empty file or only has frontmatter → Treat it as a new creation, skip to Item 2
- Yes, with partial content (left from an interrupted conversation) → After reading it, briefly report "Last time we talked about {selected direction / the last topic}, do you want to continue from there or start over?" If the user chooses to continue, pick up from that point and don't re-ask already answered questions
- Yes, a complete version with → Don't overwrite it silently; ask the user if they want to modify this one or create a new slug
- Also use Glob to check for a same-named ; if it exists, it means the design phase has started — go back to the user and ask if they entered the wrong stage
- Confirm it's a brainstorm for a new feature — Bugs should go through issues, refactoring through independent plans, and clear requirements should go directly to design. Entering the wrong stage is worse than refusing to trigger this stage.
- Confirm there is real ambiguity — If you can already draft the requirement summary in Section 1 "Decisions and Constraints" of the design phase, honestly tell the user it's more efficient to skip brainstorm and go directly to design. The biggest anti-pattern in this stage is taking on work that doesn't belong to it.
- Scan the repository before speaking — Complete these tasks before asking the first question: Read + the project architecture entry; Glob existing feature directories; Grep keywords from the user's description (to prevent term conflicts); Search for relevant pitfall records (
--filter doc_type=learning --filter track=pitfall
How to Conduct the Discussion
Two Core Attitudes
These two are more important than any operational suggestions below.
1. Distinguish between "what the user says" and "what the user needs". The user's first sentence is often a solution they've already thought of, not the real problem they want to solve. When you hear "I want to build X", don't immediately discuss the details of X; first ask "What problem in what scenario is X meant to solve?" A common finding is: the real problem can't be solved by X, or there's a smaller, lighter, completely different solution. Doing this before the user realizes it themselves is the greatest value of the brainstorm stage — once you enter design, the direction is basically fixed.
2. When the user brings a solution, evaluate it first before accepting. If the user provides a formed solution instead of a vague idea ("I want to build X that includes a/b/c"), don't directly jump into "Let's talk about how to build a". Do these two steps first:
- Paraphrase + Reverse Questioning: Rewrite the solution into "Is the problem you want to solve P?" and let the user confirm or correct it.
- Evaluate and Propose Alternatives: If you see obvious problems with the solution (solves the wrong problem, over-engineering, there's a lighter existing path, falls into pitfalls in learning documents), point them out directly and propose 1-2 significantly different alternative directions for the user to compare. Don't stay silent just to be cooperative — this is why the user came to brainstorm.
If after evaluation the solution is indeed reasonable, clearly tell the user "I think this direction is OK, it's recommended to go directly to design" — don't force divergence just to follow the process.
Discussion Rhythm
There's no fixed step-by-step plan. It roughly consists of three actions, but you can go back to the previous step at any time — if you realize the direction is wrong or a new angle emerges during the discussion, follow it:
- Dig for the Problem — Follow Attitude 1 above to clarify the "real problem to solve". Keep asking until you can paraphrase the problem in one sentence and the user says "Yes, that's exactly it". This is the most valuable step in brainstorm — don't rush to skip it.
- Diverge — Discuss solutions only after confirming the problem. Propose 2-3 specific candidate directions (if the user brought a solution, theirs counts as one of them), with 1-2 sentences each describing the direction, core value, and main cost. Include at least one counterintuitive candidate (reverse it, remove a common constraint, make a cross-domain analogy). Give recommendations only after presenting all candidates — if you anchor one first and then add others, the user's judgment will be biased by your opening.
- Converge — After the user selects a direction, briefly outline: What is the core user behavior? What is clearly out of scope? What is the biggest unknown? This is a warm-up for design, not making decisions for design, so don't get stuck in details.
Common Pitfalls
- Ask only one question at a time. If you throw 3-5 questions at the user at once, they will most likely only answer the easiest one, and the deeper issues will be missed.
- Provide options before asking questions. If you can let the user choose from 2-4 specific, distinct options, don't let them write freely. The options themselves are your thinking — you've already explored the solution space for them, and they just need to make a choice. Use if the environment supports it; otherwise, use numbered text options.
- Don't make technical selections at this stage. Questions like "which library to use, how to design the table, how to define the interface" are all pushed to the design phase. This stage only focuses on user-perceived aspects — who is this for and what problem does it solve. However, if the answer to a question depends on how things are actually implemented in the code repository ("How is this part done now?", "Is there something similar already existing?"), read the code as needed, bring back your findings to the conversation — but don't start a technical design discussion based on these findings; that's for the design phase.
Document the Results After Discussion
After the discussion converges, write the brainstorm note to
easysdd/features/{feature}/{slug}-brainstorm.md
.
How to Create the Feature Directory
- Date Prefix: Get today's date from the environment information, don't guess from memory.
- Slug: Create a lowercase English hyphenated slug based on the selected direction, and inform the user when writing it into the note. Only change it if the user has objections; there's no need to start a separate discussion like "What do you think the slug should be?" — it's more convenient for the AI to make this small decision for the user. If renaming during the design phase, only rename the slug part, keep the date prefix unchanged, and rename the entire directory together.
- Create the directory if it doesn't exist; if it does exist, go back to Item 1 of "Checks to Do Before Starting the Discussion" above.
Brainstorm Note Template
The brainstorm note is only documented when the user confirms entering the design phase — nothing is written to the file during the discussion. Therefore, the
in the template is fixed as
, with no
status. If a partial draft file is found when restarting after an interruption (a rare case, such as an abnormal exit of the previous session), follow Item 1 of "Checks to Do Before Starting the Discussion" above.
markdown
---
doc_type: feature-brainstorm
feature: YYYY-MM-DD-{slug}
status: confirmed
summary: 一句话讲选定方向是什么
tags: [...]
---
# {功能名称} Brainstorm
> Stage 0 | {YYYY-MM-DD} | 下一步：design
## 想做什么、为什么
{出发点 + 探索中的关键发现和转折，合在一起讲。}
## 考虑过的方向
### 方向 A：{名}
- 描述 / 价值 / 代价
- 结论：选定 / 否决（原因）
### 方向 B / C ...
## 选定方向与遗留问题
{选定方向 2-3 句重述 + 粗粒度轮廓（核心行为、明显不做、最大未知）。
遗留给 design 的问题直接列在这里。}
The frontmatter fields share the same specifications as design/acceptance (
/
/
/
/
), see Section 1 of
easysdd/reference/shared-conventions.md
for details.
Notes such as repository scan findings, term conflict prompts, and learning document references can be added at the end as needed, no separate section required.
Exit
After completing the convergence action, proactively ask "I think this is clear enough, can we proceed to design?" — don't wait for the user to stop you. Write the file to document the results only after the user confirms, and inform the user to trigger
for the next step.
Don't start writing the design on your own — manual checkpoints between stages are a hard constraint of the entire easysdd workflow. As explained in the root skill: running through stages without pauses will leave the user with no time to review each step, and they'll only realize they've gone off track after implementation is complete. So it's enough to tell the user to trigger
for the next step.