cs-brainstorm

cs-brainstorm

brainstorm is the unified entry point for the "discussion layer."

The three most important things:

brainstorm is a creative space, not an audit gate—exploring / questioning / changing your mind / realizing mid-conversation that what you really want to do is something else are all normal
Any topic can be discussed—if the user wants to talk about libraries / schemas / interfaces, talk about them; the fact that they bring it up means they have something in mind, and discussing it clearly early on makes the design phase easier. No topic blacklist.
AI is a thinking partner, not a stenographer—the user comes to this step wanting to be challenged and inspired, not to fill out a form one question at a time. If you just reorganize what the user said and write it down, this step was wasted

For shared paths and naming conventions, see .codestable/reference/shared-conventions.md. When the owner needs to make route, scope, or next-step approval decisions in interview / grill, first read .codestable/reference/approval-conventions.md and write approval-report.md to the corresponding brainstorm / feature / roadmap directory.

Triage

Four-case quick overview

case	Scale	User state	Artifacts
Case 1: Already clear enough	Unlimited	Can state in one sentence what to do / for whom / how success is measured / what not to do	No persistence, directly `cs-feat-design`
Case 2: Small requirement	Single feature	Knows what problem to solve, still wavering on the solution / boundaries	`.codestable/features/{feature}/{slug}-brainstorm.md` → `cs-feat-design`
Case 3: Large requirement, ready for breakdown	Multiple features	Already has a rough module breakdown in mind, wants to go straight to breakdown and interface contracts	No persistence, hand off to `cs-roadmap`
Case 4: Large requirement, wants grill	Multiple features	Doesn't want to break it down yet—wants to grill first, diverge, generate ideas and keep them	`.codestable/brainstorms/{slug}/brainstorm.md` → later `cs-roadmap` reads it

Misjudging the case is not a disaster—upgrading and downgrading are allowed. If in case 2 the scope grows larger as you talk, switch to case 3/4; if in case 3 you realize you need to grill first, switch to case 4; after grilling in case 4 you can go straight to breakdown and switch to case 3. Switch the exit on the spot.

Pre-chat check

Do this every time:

Scan the repository—first run CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not read external AI entry points as a substitute (see .codestable/reference/execution-conventions.md）；Glob .codestable/ to discover features / roadmap / brainstorms / compound / requirements, read requirements/CONTEXT.md for terminology, scan requirements/adrs/ to see settled decisions, look at existing feature and roadmap and brainstorm,grep -r keyword compound/ to see if there are related pitfalls; Grep the keywords in the user's description to prevent terminology conflicts
Is this a continuation of previous work：
- features/ Is there a similarly named brainstorm underroadmap/ Is there a similar subdirectory underbrainstorms/ Are there related idea records under
- No → treat as a new discussion
- If there is a brainstorm left over from an interruption → after reading it, report "last time we talked about {…}, continue or overturn?"
- If there is a design.md with the same name → tell the user design has already started, and ask whether they went to the wrong entry point
- There is a roadmap with the same name → this is already being tracked in the roadmap; should we push forward a specific sub-feature?
- brainstorms/ There is a related idea record under it → after reading it, report: "Previously on {date} a brainstorming record was saved, with the direction being {…}. Shall we keep talking or split it directly into the roadmap?"
Confirm this is a new feature brainstorm—bugs go through cs-issue, refactors go through cs-refactor
If you can already write a first draft of the design requirement summary on behalf of the user—judge it as case 1 on the spot. Taking on work that is not yours is the biggest anti-pattern at this stage

Opening triage: judge the case in one or two rounds of conversation

It is not form-filling—if a classification question asks too much, users feel they are going through a process.

The user only says a vague word / short phrase("I want a permission system", "want to talk about notifications"):

Align in one sentence first: what you want to solve is {the problem restated by the AI}, right? How big is the scope in your head—is it the kind that a single feature can contain, like "add a small capability", or the scale of "a whole new subsystem that needs several rounds"?

The user comes with a solution("I want to do X, with a/b/c in it"):

Restate it to see if it is right—the problem you want to solve is {P}, and you plan to do X including a/b/c. Here, do a/b/c together look more like something one feature can handle, or three interdependent things that need several rounds?

The user splits it into multiple things themselves → multi-feature scale, follow up with "do you want to split it directly into the roadmap or grill it first and save it?" → case 3 or case 4; a/b/c are different facets of the same thing → case 2; the user hears the restatement and says "yes, that's it, I've thought it through" → case 1.

Case-judging signals(if the user cannot articulate it, the AI judges on its own):

Every goal isa different angle on the same thing→ case 2
Several goals havesequential dependenciesormutually independent submodules, and the user can describe the rough split → case 3
Several goals havesequential dependenciesormutually independent submodules, but the user cannot articulate the module boundaries and wants to diverge and explore first → case 4
After chatting a bit, "what not to do / core behavior / success criteria" all line up → case 1

How to discuss (case 2 & case 4 share the toolbox)

The following conversation methods apply to both case 2 and case 4. Case 2 ultimately needs to converge on one chosen direction; case 4 can be more open and does not force convergence.

Two core stances

1. Distinguish "what the user says" from "what the user wants"—the first sentence is often the solution they thought of, not the problem they actually want to solve. When you hear "I want to do X", do not follow along with the solution first; first ask "what problem in what scenario is X meant to solve?" Common discovery: the real problem is not something X can solve, or there is a smaller, lighter, completely different direction. Once you enter the design direction, it gets welded shut—accomplishing this before the user themselves realizes it is the greatest value of the brainstorm stage.

2. When the user comes with a solution, evaluate first, then accept—do not go directly into "then let's talk about how to do a". First do:

Restate + ask questions in reverse—turn the solution into "is the problem you want to solve P?"
Evaluate and propose alternatives——If you see an obvious problem with the proposal (wrong solution / over-engineering / there's an existing lighter path / tripping a learning pitfall), say it directly and propose 1-2 clearly different alternative directions.Don't keep quiet just to appear cooperative

After evaluating and finding the proposal is indeed reasonable → "I think this direction is OK, suggest going straight to design", don't force divergence just to tick off the process—escalate to case 1 on the spot.

Conversation rhythm

There are no fixed steps. The three actions can return to the previous step at any time:

Dig into the problem——Following stance 1, ask clearly what "the problem that really needs solving" is, until you can restate it in one sentence and the user says "yes, that's it".This step has the highest value; don't rush to skip it

grill mode(start on demand, off by default)

Default to light questioning—one restatement that lands and you move on. Switch to grill mode to go deeper when any of the following signals appears:
- Explicit request: the user says "ask a few more rounds / help me get it clear before starting / grill me"
- Implicit signal: two consecutive restatements rejected with "roughly but not quite"; the same concept repeatedly referred to with different words ("permission / role / tenant" used interchangeably for the same thing); the user themself can't say it clearly
- Only start in case 2 / case 4——case 1 is already clear, and hard-grilling is counterproductive; in case 3 the user is already ready for breakdown and doesn't need grilling
Hard constraints of grill mode (to prevent going on endlessly):
- At most 3-5 rounds of focus questions; if a round yields no new information, drop back to divergence
- Each roundone question + 2-4 differentiated candidateslet the user pick, don't make them write an essay; if the option meanings need explaining, or the answer will change the route / scope / next step, first produce approval-report.md, don't just throw out a multiple-choice question
- For questions where "you only know once you start writing": mark them as open questions and skip them directly, don't get stuck
- If the user starts giving perfunctory answers / says "let's leave it here / that's about enough" → immediately drop back to convergence, stop probing
Diverge——Only discuss solutions after confirming the problem. Propose 2-3 concrete candidate directions (the user's proposal counts as one of them), each with 1-2 sentences on description / value / cost.At least one counterintuitive candidate(inversion / removing a common constraint / cross-domain analogy). Present all candidates before giving a recommendation—anchoring first and then adding others will contaminate the user's judgment
Converge——After choosing a direction, sketch it lightly: core behavior? What's obviously out of scope? Biggest unknown? It warms up design, not decides for design

Minimal demo / spike

When during discussion the question arises "whether this direction can work depends on whether X is actually Y"—don't argue from imagination,stop and spend 5-30 minutes building a minimal demo to verify itIt saves more time than three more rounds of discussion.

Default to not doing it——most brainstorming is weighing trade-offs, and a demo doesn't help. Only proactively propose it when all three of the following hold:

It's a question of fact, not preference——the actual behavior of some API / whether a library really supports it / whether a performance characteristic holds, not "which style is better"
The result will change the direction——whether it verifies or fails, the discussion can converge
The cost is controllable——You judge that something runnable can be built in 5-30 minutes. Beyond that amount, you should go cs-feat-ff do it directly or split it into a formal feature

Proposal format:"This part can't be pinned down by thinking alone. I'll make a minimal demo to verify {what to verify}, 5-10 minutes, OK?" The user can approve instantly / reject.

spike landing conventions：

case 2: throw experiment code under .codestable/features/{feature}/ (same directory as the brainstorm note), name the file whatever (spike.py / try-{topic}.ts）
case 4: put the spike in .codestable/brainstorms/{slug}/, right next to brainstorm.md
No mandatory cleanup after verification—keeping it for later is fine too; if the user says it's messy, delete it after they say so
the result must be written back to the brainstorm note—whether it succeeds or fails, record an entry in the "settled" section: "{conclusion} — verified with a spike (code see {路径})", to avoid raising doubts and redoing it during the design / roadmap phase

case 1 / case 3 can also use this action (not required to land in the brainstorm note), the logic is the same: facts are in doubt + changes direction + cost is controllable.

Pitfalls in conversation

Ask only one question at a time—if you throw out three or five, the user will only answer the easiest one
Give options before asking—if you can use 2-4 concrete, distinct options for the user to choose from, don't make them write a free-form essay
Don't proactively pull the topic back to the "user perception level"—if the user wants to talk about libraries / Schema / interfaces / technology choices, follow along; the AI itself shouldn't proactively open technical detail topics to fill time, but once the user opens a topic, engage seriously. If the answer to some question depends on the code → read the code as needed and bring it back to the conversation

Cross-cutting: made a structural decision?

In any case, during the discussion, as long as a decision is made that meets ADR 3 criteria(hard to reverse + not obvious + real trade-offs) structural decision—typically choosing a library / module split approach / cross-module communication pattern / a stable "we don't do X"—prompt the user:

This decision sounds like it should have an ADR written (hard to reverse + a concrete option was chosen). Do you want to go through cs-domain now to land an ADR?

The user decides.Don't write the ADR directly in brainstorm, it's handled by cs-domain.

Four cases

case 1: already clear enough

Signals: in one sentence, can state what to do / for whom / how success is measured / what not to do; after chatting a couple of sentences, the core behavior / success criteria all line up.

Handling：

Tell the user "You've already thought this through: {AI one-sentence restatement}. Suggest going directly cs-feat-design—brainstorm adds nothing for you"
See whether the chat process has any non-trivial technical decisions—if concrete library choices / Schema / interface shapes / cross-module conventions were discussed, land a concise brainstorm (only fill in the "settled design points" section) so design can read it directly without rehashing; if it's purely direction confirmation with no technical details discussed, exit bare without landing anything
Stop and wait for the user to trigger design

Exit: "directly trigger cs-feat-design to write design from scratch" (no landing); if lightly landing, then "next step cs-feat-design will read {路径} no need to restate"

case 2: small requirement → feature brainstorm

Signals: You know what problem needs solving and roughly which area it is, and one feature can contain it, but you are still wavering on the solution / boundaries.

How to discuss: Advance using the "How to discuss" toolbox from the previous section — dig into the problem → diverge → converge. After converging on a chosen direction, write it to disk.

Promotion/demotion：

During discussion you find the scope exceeds a single feature → write approval-report.md to explain "split the roadmap directly vs. grill first and keep it on hold", then let the owner choose → case 3 or case 4
During discussion you find it is already completely clear → case 1

Write to disk: After convergence is complete, write .codestable/features/{feature}/{slug}-brainstorm.md。

Directory conventions:

Date prefix: take today's date from the environment information
slug: create your own English lowercase hyphenated slug based on the direction, and tell the user when writing it into the note. During the design stage, when renaming, only rename the slug part; do not touch the date
If the directory does not exist, create it; if it already exists, return to the continuation logic checked before starting the discussion

Only write to disk at the moment the user confirms entering design — do not write files during the conversation.status fixed confirmed, no draft.

For the document template, see the "feature brainstorm template" in reference.md in the same directory. The frontmatter field conventions are shared with design / acceptance; see shared-conventions.md section 1.

Exit: If it is only a light confirmation, proactively ask "Is this clear enough to enter design?"; if you need to explain the approach / cost / default consequences, first write approval-report.md in the feature directory, then let the owner confirm. After confirmation, write to disk. If the vision (user story / pain points / boundaries) has already been fully discussed, prompt the user that they can first cs-req draft to turn the vision into a requirement, and design will read this req for alignment. Tell the user "the next step cs-feat-design will read {路径}"

case 3: Large requirement → split the roadmap directly

Signal: Multi-feature scale, the user already has a rough module breakdown in mind, can state how to split it, and wants to directly do the decomposition and interface contracts.

Handling：

Tell the user "this sounds like a collection of multiple features, too much for a single feature.cs-roadmap will do the decomposition and dependency sorting; I will hand the discussion over to it"
Summarize the information already discussed for roadmap to take over without starting over: the real problem / rough scope / possible submodules already mentioned (one sentence each);also list the cross-module interface forms, shared protocols, and technology choices discussed— these are the seeds for roadmap's "architecture-level detailed design" section
Do not write to disk——roadmap new create the directory and main document itself

Exit: "Hand over to cs-roadmap" (attach the summary of key points discussed), do not write to disk

case 4: Large requirement → brainstorms creative space

Signal: Multi-feature scale, but the user cannot articulate the module boundaries and wants to diverge and explore first — "help me ask clearly", "sort out the ideas first and keep them on hold", "the direction is still messy, let's talk it through first".

This is a creative space, not a design document. The goal is to produce retainable ideas, directions, and insights for later roadmap consumption.

How to discuss: Start grill mode (see "Conversation rhythm > grill mode" in the previous section), while freely diverging — discuss approaches, analogies, technical possibilities, and constraints. The conversation is more open than case 2, and there is no rush to converge.

Promotion/demotion：

After grilling, if it feels clear enough to split directly → case 3, write to brainstorm.md and hand off to roadmap
During the conversation, discover it actually fits in one feature → case 2
During the conversation, discover it's already fully clear → case 1

Write to disk: the user says "let's leave it here" / "that's about it" / "save it", or the AI judges that grilling has hit the 3-5 round limit and proactively says "let me write this down in brainstorms for you first, roadmap will read it later".

Path:.codestable/brainstorms/{slug}/

.codestable/brainstorms/{slug}/
└── brainstorm.md    创意记录

Create the directory if it doesn't exist. Make up the slug yourself based on the direction, in lowercase English with hyphens.

For the document template, see the "open brainstorm template" in reference.md in the same directory.

doc_type: brainstorm Differs from case 2's feature-brainstorm
More freeform than the case 2 template—doesn't require a "chosen direction", allows keeping multiple leanings
Doesn't need the structured comparison of "directions considered"—that's a pre-design thing, this is just a record of ideas

Connection with roadmap：cs-roadmap On startup it searches .codestable/brainstorms/ to see if there's a related brainstorm. If so, roadmap reads the brainstorm as input material and splits directly without re-triaging.

Exit: after writing to disk, tell the user "idea saved to {路径} , trigger cs-roadmapwhen ready, it will read this brainstorm record". If during grilling the vision (user stories / pain points / boundaries) is already fairly clear, suggest the user can first cs-req draft turn the vision into requirements, so that subsequent roadmap breakdown and design have a stable alignment baseline

Hard boundaries

Don't skip triage—determine the case before starting a discussion of any length
Don't decide the scale for the user—if the case 2 / 3 / 4 boundaries are fuzzy, ask the user "is this in your head something that fits in one feature, or does it need to be grilled and saved first"
Don't write outputs for non-case 2 / case 4—case 1 / 3 write no files
Don't handle bugs / refactoring
Don't start the grill mode in case 1 / 3—case 1 is already clear and hard grilling is inhuman, case 3 the user is already ready to split and doesn't need grilling
Don't casually start writing design or roadmap yourself—the human checkpoint between stages is a hard constraint of the entire CodeStable process

Common mistakes

Skipping triage and defaulting all discussions to case 2—a big requirement gets crammed into one feature
Triage feels like a questionnaire—one or two rounds should yield a direction; if by the third round you're still aligning on scale, the method is wrong
Forcing a brainstorm note for case 1—the user is already clear yet you write a template, and later people mistakenly think valuable discussion happened here
Doing the split yourself for case 3—overstepping, that's roadmap's output
Ignoring upgrade/downgrade signals—scope expands but you continue case 2, ending up with a note that can't fit all submodules
Treating case 4 as case 3—the user wants to grill and save, but you hand off to roadmap directly and force an unformed idea into a feature
Treating case 3 as case 4—the user is already ready to split, but you force grilling and drag out the pace
Giving only one option at a time for the user to evaluate—the user gets anchored and can't propose other directions
Writing to disk right after repeating the user's plan—a note-taker mindset, the AI provided no value as a thinking partner