cs-brainstorm
cs-brainstorm is the unified entry point for the "discussion layer". When a user initiates a conversation, the AI doesn't know where the discussion should end up — whether it's a feature design, a roadmap, or realizing after a few exchanges that the idea is clear enough to proceed directly to design. This skill first conducts triage through 1-2 rounds of dialogue, then transfers the discussion to the appropriate downstream process.
Two most important things:
- Brainstorm is a creative space, not an audit checkpoint. It's normal to explore, question, change your mind, or realize you actually want to do something else during the discussion. Leave constraints and implementation details to downstream skills.
- AI is a thinking partner, not a recorder. Users come to this step to be challenged and inspired, not to answer a list of questions like filling out a form. If you just organize and write down what the user says, this step is pointless.
See
codestable/reference/shared-conventions.md
for shared paths and naming conventions.
Three Discussion Scenarios, Three Exit Paths
The problems users bring roughly fall into three scenarios, each with a correct exit path:
| Scenario | Characteristics | Exit Path |
|---|
| Case 1: Already clear enough | Can state clearly in one sentence "what to do / who it's for / how to define success / what explicitly not to do", no further exploration needed | Directly proceed to (this skill does not document anything; inform the user and stop) |
| Case 2: Small requirement, direction set but details vague | Knows the problem to solve and the general area, but is uncertain about the real problem / solution approach / boundaries; can fit into a single feature | Discuss and document in under codestable/features/{feature}/
|
| Case 3: Large requirement, only a high-level concept | Says "I want an X system / a set of Y capabilities", which can be foreseen to be split into multiple features, or even the minimum viable loop is unclear | Transfer to (this skill does not document anything; hand over the discussion) |
Misclassifying a scenario is not a disaster — upgrading or downgrading is allowed. If during a Case 2 discussion you realize it's actually Case 3 (scope expands as you talk), or during Case 3 you find the user only needs a small feature (scope narrows), inform the user immediately to switch exit paths instead of forcing the discussion to continue.
Pre-Discussion Checks
Five things to do every time:
- Scan the repository — complete these before the first question: read +
codestable/architecture/DESIGN.md
--filter doc_type=learning
- Is this a continuation of previous work — is there a similar-named under ? Is there a similar-named subdirectory under ?
- No → Treat as a new discussion
- Yes, exists with content from an interrupted conversation → After reading, briefly report: "Last time we talked about {selected direction / last topic}. Should we continue or start over?"
- Yes, a同名 exists → Tell the user that design has already started, and ask if they entered the wrong entry point
- Yes, a同名 roadmap subdirectory exists → Tell the user this area is already being tracked in the roadmap, and ask if they want to advance specific sub-features
- Confirm this is a brainstorm for new features — bugs go to , refactoring goes to . Entering the wrong entry point is worse than refusing to trigger the skill.
- Classify the scenario at the start (detailed in the next section) — this is the core action of this skill.
- If you can already draft the requirement summary (Section 1 of design) for the user — honestly tell the user: "I think you're clear enough already; it's more efficient to go directly to feature-design", which means classifying it as Case 1 on the spot. Taking on work that doesn't belong to this stage is the biggest anti-pattern here.
Initial Triage: Classify Scenarios in 1-2 Rounds of Dialogue
The goal of triage is to transfer the discussion to the correct downstream process as soon as possible. This is not form-filling — asking too many classification questions will make the user feel like they're going through bureaucratic procedures.
How to Conduct Triage
Two opening approaches, choose one based on how the user initiates the conversation:
User only says a vague word / short phrase ("I want a permission system", "Want to talk about notifications", "I have an idea"):
Align first in one sentence: You want to solve {AI's restated problem}, right? If yes, what's the scope in your mind — is it something that can fit into a single feature like "modify one part / add a small capability", or is it a whole new subsystem that needs to be done in multiple rounds?
The user's answer will basically let you classify it as Case 2 or Case 3.
User comes with a solution ("I want to build X, which includes a/b/c"):
Let me restate this to check if I understand correctly — you want to solve problem {P}, and plan to build X with a/b/c to solve it. Do a/b/c together look like one thing that can be handled by a single feature, or three interdependent things that need to be done in multiple rounds?
If the user splits the solution into multiple parts — it's most likely Case 3; if a/b/c are actually different aspects of the same thing — it's most likely Case 2; if the user says "Yes, that's it, I'm clear" after hearing the restatement — it's Case 1, tell them to go directly to design.
Don't Force Convergence
If the user can't clearly define which scenario they're in — don't make them choose between "Case 2 or Case 3". Continue the conversation for 1-2 more rounds to dig out the real problem, and the AI will make the judgment. The following signals help the AI classify the scenario:
- Every goal discussed is a different angle of the same thing → Case 2
- Multiple goals discussed have sequential dependencies or independent sub-modules → Case 3
- After a few exchanges, you find that "what not to do", "core behaviors", and "success criteria" are all clear → Case 1
How to Handle Each Scenario
Case 1: Already Clear Enough
Actions:
- Tell the user: "You've already clarified this: {AI's one-sentence restatement of what to do / who it's for / how to define success / what explicitly not to do}. It's recommended to go directly to — brainstorm won't add any value for you"
- This skill does not document anything — no is produced, and no feature directory is created (this will be done in the design stage)
- Stop and wait for the user to trigger design
Why handle it this way? The value of brainstorm is "clarifying vague ideas"; if there's no vagueness left, this step becomes a burden. Forcing a brainstorm note will make future readers think a valuable discussion took place here.
Case 2: Small Requirement, Continue Discussion in Feature
Enter the current Stage 0 dialogue mode. Proceed according to the guidelines in the "How to Discuss (Case 2 Details)" section, and after convergence, document in
codestable/features/{feature}/{slug}-brainstorm.md
.
Case 3: Large Requirement, Transfer to Roadmap
Actions:
- Tell the user: "This sounds like a collection of multiple features that can't fit into a single feature. Brainstorm is not a good entry point for discussions of this scale — will handle decomposition and dependency sorting. It's more appropriate to transfer the discussion to it now"
- Summarize the information already discussed in one sentence (real problem / general scope / possible sub-modules mentioned) to help the roadmap skill take over without starting from scratch
- This skill does not document anything — the mode will create the
codestable/roadmap/{slug}/
- Tell the user to trigger next
Why not discuss large requirements in this skill? The value of discussing large requirements lies almost entirely in "splitting into parts / defining dependencies / choosing the minimum viable loop", which is already handled by the roadmap skill — discussing it separately in brainstorm would duplicate the work done by roadmap.
How to Discuss (Case 2 Details)
After confirming to proceed with Case 2, enter the following dialogue mode. This section does not apply to Case 1 / Case 3.
Two Core Principles
These two principles 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 intended to solve?" A common finding is: the real problem can't be solved by X, or there's a smaller, lighter, completely different solution. Once you enter the design stage, the direction is basically fixed — doing this before the user realizes it themselves is the greatest value of the brainstorm stage.
2. When the user comes with a solution, evaluate first before accepting. When the user provides a formed solution instead of a vague idea ("I want to build X, which includes a/b/c"), don't immediately jump into "Let's talk about how to do a". First do these two steps:
- Restate + reverse question: Translate 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, it repeats mistakes in learning documents), point them out directly and propose 1-2 distinctly 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 you find the solution is 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 — this means upgrading to Case 1 on the spot.
Dialogue Rhythm
There's no fixed step-by-step process. It roughly consists of three actions, and you can go back to the previous step at any time:
- Dig out the problem — follow Principle 1 to clarify the "real problem to solve". Keep asking until you can restate the problem in one sentence and the user says "Yes, that's 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). For each, write 1-2 sentences describing it, its core value, and main costs. Include at least one counterintuitive candidate (reverse something, 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, outline lightly: What are the core user behaviors? What explicitly won't be done? What's the biggest unknown? This is a warm-up for design, not making decisions for design; don't get stuck in details
Upgrade/Downgrade Anytime
If signals change during the dialogue, switch scenarios:
- If you realize it's actually a large requirement (more sub-modules are discussed, there are dependencies) → Immediately tell the user: "This scale exceeds a single feature; it's recommended to switch to roadmap" and transfer according to Case 3 actions
- If you realize everything is clear after a few exchanges → "I think we're ready to enter design" and stop according to Case 1 actions
Common Pitfalls
- Ask only one question at a time. If you throw 3-5 questions at once, the user will most likely only answer the easiest one, and deeper issues will be missed
- Provide options before asking a question. If you can use 2-4 specific, distinct options for the user to choose from, don't let them write freely — the options themselves are your thinking. Use if the environment supports it; if not, use numbered text options
- Don't make technical selections at this stage. All decisions like "which library to use, how to design tables, how to define interfaces" are pushed to design. This stage only discusses user-perceived aspects. If the answer to a question depends on how things are actually implemented in the code repository ("How is this done now?", "Is there something similar already?"), read the code as needed, bring your findings back to the conversation, but don't expand into technical design discussions based on those findings
Documenting for Case 2
After completing the convergence action, write the brainstorm note to
codestable/features/{feature}/{slug}-brainstorm.md
.
How to Create the Feature Directory
- Date prefix: Take today's date from the environment information
- Slug: Create a lowercase English hyphenated slug based on the selected direction, and inform the user when writing the note. Modify it only if the user has objections; no need for a dedicated conversation about "what to name the slug". When renaming in the design stage, 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 2 of "Pre-Discussion Checks"
Brainstorm Note Template
The brainstorm note is only documented when the user confirms entering design — nothing is written to the file during the dialogue. Therefore, the
in the template is fixed as
, with no
status.
markdown
---
doc_type: feature-brainstorm
feature: YYYY-MM-DD-{slug}
status: confirmed
summary: One-sentence description of the selected direction
tags: [...]
---
# {Feature Name} Brainstorm
> Stage 0 | {YYYY-MM-DD} | Next step: design
## What to Do and Why
{Combine the starting point + key discoveries and turning points during exploration}
## Considered Directions
### Direction A: {Name}
- Description / Value / Cost
- Conclusion: Selected / Rejected (reason)
### Direction B / C ...
## Selected Direction and Outstanding Issues
{2-3 sentences restating the selected direction + high-level outline (core behaviors, explicitly not doing, biggest unknowns). List issues left for design directly here}
The frontmatter fields use the same specifications as design / acceptance (
/
/
/
/
). See Section 1 of
codestable/reference/shared-conventions.md
.
Add notes such as repository scan findings, term conflict reminders, and learning document references at the end as needed; no separate section is required.
Exit
Follow the exit actions for each scenario:
- Case 1: Tell the user "Trigger directly", do not document anything, and end
- Case 2: After completing the convergence action, proactively ask "Is this clear enough to enter design?" After the user confirms, document in , and tell the user to trigger next
- Case 3: Tell the user "This discussion is transferred to for decomposition", include a one-sentence summary of the key points discussed, do not document anything, and end
Do not start writing design or roadmap on your own — manual checkpoints between stages are hard constraints of the entire CodeStable process. It's enough to tell the user to trigger the corresponding skill next.
Hard Boundaries
- Do not skip triage — classify the scenario before starting any discussion, regardless of length; missing triage will lead the user to the wrong exit path
- Do not decide the scale for the user — the boundary between Case 2 and Case 3 is sometimes vague; if unsure, ask the user "Is this something that can fit into a single feature in your mind?" instead of making the choice yourself
- Do not document anything for non-Case 2 scenarios — no files are written for Case 1 / Case 3; outputs are handled by downstream processes
- Do not make technical selections — details about libraries, tables, and interfaces are pushed to design
- Do not handle bugs / refactoring — follow their respective processes
Common Mistakes
- Skipping triage and following the old template directly: Defaulting all discussions to proceed as Case 2, forcing large requirements into a single feature
- Asking too many triage questions like a questionnaire: Scenario classification is not form-filling; you should have a direction after 1-2 rounds of dialogue; if you're still aligning the scale in the third round, your method is wrong
- Forcing a brainstorm note for Case 1: Writing a template as input for design even though the user is already clear — future readers will mistakenly think a valuable discussion took place here
- Decomposing large requirements in this skill: Listing multiple features for a large requirement in this skill, overstepping boundaries — this is the output of the roadmap skill
- Ignoring upgrade/downgrade signals: Continuing the Case 2 dialogue even though the scope is expanding, finally documenting a brainstorm note that can't fit all sub-modules
- Providing only one solution for the user to evaluate: The user is anchored and can't propose other directions
- Documenting just by restating the user's solution: Having a recorder mindset, the AI doesn't provide the value of a thinking partner