Brainstorming — from idea to agreed design
This skill decides what to build and how we will know it is built. It ends
with acceptance criteria a stranger could check, and with a written spec when
the work needs one. Execution order, slicing and delegation belong to
writing-plans.
Understand the requested outcome, inspect existing patterns, choose a complete
solution, and continue into implementation when that is what the user asked.
Authorization and stop conditions come from OPS §1, not the design phase.
Choose the necessary design depth
Investigation/spike: answer a feasibility question with a bounded probe.
Define what the probe measures, run it, report evidence and limitations.
Do not silently turn a requested investigation into a permanent feature.
Bounded change: trace the existing flow and affected callers, resolve
details from code, state the approach briefly, implement and verify.
Architectural change: map responsibilities, interfaces, state transitions,
compatibility and failure handling before code.
Multi-capability requirement: one request bundles several independently
testable capabilities (accounts, billing, notifications). Write a capability
map before a spec, because the map decides build order and what can be
delivered in parallel:
# Capability Map: [Initiative]
| Module id | Responsibility | Depends on |
|---|---|---|
| identity | Accounts, sessions, SSO | — |
| billing | Plans, invoices, payments | identity |
| notifications | Email and webhook fan-out | identity |
Build order: identity → billing, notifications. Each capability gets its own
acceptance criteria; all requested capabilities are delivered, not just the
first sub-project.
Complexity determines design depth, not permission. Reclassify when new facts
change the approach; no mandatory heavier-path tie-break or approval pause.
Plan/design-only requests stop at their requested deliverable.
Design workflow
Inspect context. Read the relevant implementation, configuration and
existing decisions. Reuse project conventions rather than adding a parallel
design. Do not ask the user for repository-provided information.
Define done. Establish the intended use from the request and available
context, then choose an observable check of that outcome. Preserve required
behavior, compatibility and scope; do not substitute a convenient metric
for the user's problem. Ask only if missing context changes the decision.
REQUEST: "Make the dashboard faster"
OBSERVED CONTEXT: Operators wait 8 seconds after changing the date range;
initial load is already fast.
OUTCOME: Operators can compare periods without waiting for stale totals.
CHECK: Measure date-change to correct, usable totals on representative data.
Choose the target from the workflow; retain correctness checks.
NOT SUFFICIENT: Improving LCP alone does not test this interaction.
A simpler implementation must still deliver all requested formats, paths,
error behavior and quality.
Resolve uncertainty. Decide ordinary details from evidence and explain
consequential defaults. When something about intent is genuinely missing,
ask one batch of related questions, most important first: one open,
description-first question ("walk me through the last time this hurt you?",
"what would make you wince if I got it wrong?"), then the concrete
specifics you need. Offer a short menu of options only when the user is
stuck or asks what you think. Ask only when an unavailable answer would
materially change the outcome or an action lacks authority, and keep
independent authorized work moving while you wait.
Compare real alternatives. Include alternatives only when they have
meaningful tradeoffs. Prefer the simplest complete approach; do not invent
options to fill a quota. Existing proven patterns may settle the decision.
Design the change. Cover components, data flow, errors, integration,
migration and verification at the depth needed. Separate units by reason
for change, keep concrete interfaces, avoid unrelated restructuring.
Consequential platform, language, library or medium choices rest on repo
defaults and existing patterns where they exist; when you choose one the
user has not stated, own it as your call in plain words, never record it
as something the user agreed to, and surface it early enough to correct
cheaply.
Check the design. Resolve contradictions, placeholders, missing required
paths and uncertain boundaries. Map acceptance to checks before coding.
For a complex design, also read it as a builder who cannot ask you anything
and collect only the points where a wrong guess would change what gets
built — skip wording nitpicks and anything the design explicitly leaves to
the builder. Use an available reviewer when independent perspective is
useful and host rules permit it; otherwise do the check yourself.
Answer the answerable from evidence and mark those calls as yours; add the
genuinely user-owned questions to the same batch as step 3. A bounded change
needs little or none of this.
Continue. Use writing-plans when the execution shape is non-obvious,
then implement and verify without asking the user to approve the same
authorized work again. The outcome and grant agreed in design carry into
execution: ordinary implementation decisions inside them are yours, and
the deliverable is produced rather than handed back as a plan.
When intent was unclear, briefly reflect what the thing is for and who it
serves before committing to a design. Separate the user's statements from
your assumptions. Accept corrections; do not defend an earlier reading.
The spec
Reuse an existing spec or the user's explicit acceptance criteria. Write only
the design that is missing, at the size the work needs — a bounded change
needs a paragraph in the task tracker, not a document.
State assumptions, then proceed. Surface the ones you are betting on and
which would be expensive to reverse:
ASSUMPTIONS:
1. Web app, not native mobile
2. Session cookies, not JWT
3. PostgreSQL already provisioned
Proceed on those unless one changes the outcome the user asked for or the
authority required for it — those two are worth a question; the rest are not
worth a pause. Record them where the work is tracked so a later reader can
reject them.
Spec template — keep the sections that decide something, drop the rest:
# Spec: [Project/Feature]
## Objective
What we're building, why, who uses it; user stories or acceptance criteria.
## Commands
Build, test, lint, dev — full commands as they actually run.
## Tech stack and structure
Framework, language, key dependencies with versions; directory layout with
one-line descriptions of the parts a newcomer must find.
## Code style
One representative snippet plus the conventions it shows.
## Testing strategy
Framework, test locations, level of tests, what gets covered.
## Boundaries
- Always: verify affected behavior, follow project conventions, validate
trust boundaries
- Ask first: missing authority for irreversible or outward actions, or
unavailable information that changes the outcome
- Never: expose secrets, mutate production data as a test, suppress a real
failure
## Success criteria
Specific, testable conditions — each mapped to a check.
## Open questions
Only what is genuinely the user's to decide, with your recommended default.
Update the spec when decisions or scope change, not to keep it in sync with
every line of code. Save it durably when requested or when an explicit project
workflow requires it; otherwise the task tracker or chat is enough.
Artifacts and review
Reuse the project's existing design-document location; if none exists and a
durable file is needed, use docs/design/YYYY-MM-DD-<topic>-design.md. A
design file need not contain the whole implementation; record enough for
another engineer to understand decisions, contracts and acceptance.
User review is a gate only when the user requested it or a real project
approval governs the action. Do not ask after every section, force spec-file
approval, or end with an execution-method menu when implementation is already
authorized. Commits follow OPS §1.
Failure patterns
- New subsystem treated as new authorization: design thoroughly, then execute.
- Missing info guessed despite incompatible outcomes: inspect, then ask.
- Local security fix stalled solely because it touches auth: fix with isolated
positive and negative checks; no production mutation implied.
- Scope or platform silently drifted: "build a CLI" became a web app, or a
report became a dashboard, without the user's word or a stated assumption
they could reject.
- An unstated consequential default (language, library, medium) recorded as
if the user had chosen it: a default they never heard is one they could
not reject; own it in plain words instead.
- CSV-only shipped when CSV and JSON were requested: incomplete, not minimal.
- Coding started before acceptance or any check existed.
- Requested features dropped as an "MVP", or unrequested ones added because
they seemed useful.
- A spec document demanded, a human signoff awaited, or another menu offered
for work already authorized.
- A procedural skill says stop: reconcile it with scope and authority; do not
leave reachable implementation undone or ignore an explicit user stop.
Developing the user's thinking
When the request is an unfinished idea ("I want X but not sure what", "help me
find directions"), do not demand a finished specification or choose their goal
for them. Start with the description-first question above. When they ask for
directions or need concrete examples to react to, offer two to four
meaningfully different interpretations with consequences; keep them as
proposals, not decisions already made for the user.
When the user states an unusual method with explicit constraints (hardware,
scale, policy), evaluate it against those constraints before recommending the
standard approach; if it satisfies them, work within it and name only the risks
the stated constraints do not cover.
The user's goal stays theirs: if they correct your interpretation of what they
want, adopt the correction and continue from it; do not re-propose the
rejected framing under a new name.
Check before you leave design
Source: obra/superpowers (MIT); spec-driven development absorbed from
obra/superpowers and coding-kit v5.1. Adapted for coding-kit.
1---2name: brainstorming3description: 'Use when deciding what to build: a new feature, component or subsystem, a vague or conflicted request, a requirement that spans several capabilities, or a product-level design choice with real tradeoffs. Produces intent, constraints, capability map, spec and observable acceptance. Not for service or module structure (architecture-simplicity), consequential tool selection (production-first-decisions), executing already-specified multi-slice work (writing-plans), or non-code judgment work (fable-method).'4license: MIT5metadata:6 source: https://skillmd.com/skills/oleg494/brainstorming7 version: "6.1.0"8---910# Brainstorming — from idea to agreed design1112This skill decides *what* to build and how we will know it is built. It ends13with acceptance criteria a stranger could check, and with a written spec when14the work needs one. Execution order, slicing and delegation belong to15`writing-plans`.1617Understand the requested outcome, inspect existing patterns, choose a complete18solution, and continue into implementation when that is what the user asked.19Authorization and stop conditions come from OPS §1, not the design phase.2021## Choose the necessary design depth2223- **Investigation/spike:** answer a feasibility question with a bounded probe.24 Define what the probe measures, run it, report evidence and limitations.25 Do not silently turn a requested investigation into a permanent feature.26- **Bounded change:** trace the existing flow and affected callers, resolve27 details from code, state the approach briefly, implement and verify.28- **Architectural change:** map responsibilities, interfaces, state transitions,29 compatibility and failure handling before code.30- **Multi-capability requirement:** one request bundles several independently31 testable capabilities (accounts, billing, notifications). Write a capability32 map before a spec, because the map decides build order and what can be33 delivered in parallel:3435 ```markdown36 # Capability Map: [Initiative]37 | Module id | Responsibility | Depends on |38 |---|---|---|39 | identity | Accounts, sessions, SSO | — |40 | billing | Plans, invoices, payments | identity |41 | notifications | Email and webhook fan-out | identity |42 ```4344 Build order: identity → billing, notifications. Each capability gets its own45 acceptance criteria; all requested capabilities are delivered, not just the46 first sub-project.4748Complexity determines design depth, not permission. Reclassify when new facts49change the approach; no mandatory heavier-path tie-break or approval pause.50Plan/design-only requests stop at their requested deliverable.5152## Design workflow53541. **Inspect context.** Read the relevant implementation, configuration and55 existing decisions. Reuse project conventions rather than adding a parallel56 design. Do not ask the user for repository-provided information.572. **Define done.** Establish the intended use from the request and available58 context, then choose an observable check of that outcome. Preserve required59 behavior, compatibility and scope; do not substitute a convenient metric60 for the user's problem. Ask only if missing context changes the decision.6162 ```63 REQUEST: "Make the dashboard faster"64 OBSERVED CONTEXT: Operators wait 8 seconds after changing the date range;65 initial load is already fast.66 OUTCOME: Operators can compare periods without waiting for stale totals.67 CHECK: Measure date-change to correct, usable totals on representative data.68 Choose the target from the workflow; retain correctness checks.69 NOT SUFFICIENT: Improving LCP alone does not test this interaction.70 ```7172 A simpler implementation must still deliver all requested formats, paths,73 error behavior and quality.743. **Resolve uncertainty.** Decide ordinary details from evidence and explain75 consequential defaults. When something about intent is genuinely missing,76 ask one batch of related questions, most important first: one open,77 description-first question ("walk me through the last time this hurt you?",78 "what would make you wince if I got it wrong?"), then the concrete79 specifics you need. Offer a short menu of options only when the user is80 stuck or asks what you think. Ask only when an unavailable answer would81 materially change the outcome or an action lacks authority, and keep82 independent authorized work moving while you wait.834. **Compare real alternatives.** Include alternatives only when they have84 meaningful tradeoffs. Prefer the simplest complete approach; do not invent85 options to fill a quota. Existing proven patterns may settle the decision.865. **Design the change.** Cover components, data flow, errors, integration,87 migration and verification at the depth needed. Separate units by reason88 for change, keep concrete interfaces, avoid unrelated restructuring.89 Consequential platform, language, library or medium choices rest on repo90 defaults and existing patterns where they exist; when you choose one the91 user has not stated, own it as your call in plain words, never record it92 as something the user agreed to, and surface it early enough to correct93 cheaply.946. **Check the design.** Resolve contradictions, placeholders, missing required95 paths and uncertain boundaries. Map acceptance to checks before coding.96 For a complex design, also read it as a builder who cannot ask you anything97 and collect only the points where a wrong guess would change what gets98 built — skip wording nitpicks and anything the design explicitly leaves to99 the builder. Use an available reviewer when independent perspective is100 useful and host rules permit it; otherwise do the check yourself.101 Answer the answerable from evidence and mark those calls as yours; add the102 genuinely user-owned questions to the same batch as step 3. A bounded change103 needs little or none of this.1047. **Continue.** Use `writing-plans` when the execution shape is non-obvious,105 then implement and verify without asking the user to approve the same106 authorized work again. The outcome and grant agreed in design carry into107 execution: ordinary implementation decisions inside them are yours, and108 the deliverable is produced rather than handed back as a plan.109110 When intent was unclear, briefly reflect what the thing is for and who it111 serves before committing to a design. Separate the user's statements from112 your assumptions. Accept corrections; do not defend an earlier reading.113114## The spec115116Reuse an existing spec or the user's explicit acceptance criteria. Write only117the design that is missing, at the size the work needs — a bounded change118needs a paragraph in the task tracker, not a document.119120**State assumptions, then proceed.** Surface the ones you are betting on and121which would be expensive to reverse:122123```124ASSUMPTIONS:1251. Web app, not native mobile1262. Session cookies, not JWT1273. PostgreSQL already provisioned128```129130Proceed on those unless one changes the outcome the user asked for or the131authority required for it — those two are worth a question; the rest are not132worth a pause. Record them where the work is tracked so a later reader can133reject them.134135**Spec template** — keep the sections that decide something, drop the rest:136137```markdown138# Spec: [Project/Feature]139140## Objective141What we're building, why, who uses it; user stories or acceptance criteria.142143## Commands144Build, test, lint, dev — full commands as they actually run.145146## Tech stack and structure147Framework, language, key dependencies with versions; directory layout with148one-line descriptions of the parts a newcomer must find.149150## Code style151One representative snippet plus the conventions it shows.152153## Testing strategy154Framework, test locations, level of tests, what gets covered.155156## Boundaries157- Always: verify affected behavior, follow project conventions, validate158 trust boundaries159- Ask first: missing authority for irreversible or outward actions, or160 unavailable information that changes the outcome161- Never: expose secrets, mutate production data as a test, suppress a real162 failure163164## Success criteria165Specific, testable conditions — each mapped to a check.166167## Open questions168Only what is genuinely the user's to decide, with your recommended default.169```170171Update the spec when decisions or scope change, not to keep it in sync with172every line of code. Save it durably when requested or when an explicit project173workflow requires it; otherwise the task tracker or chat is enough.174175## Artifacts and review176177Reuse the project's existing design-document location; if none exists and a178durable file is needed, use `docs/design/YYYY-MM-DD-<topic>-design.md`. A179design file need not contain the whole implementation; record enough for180another engineer to understand decisions, contracts and acceptance.181182User review is a gate only when the user requested it or a real project183approval governs the action. Do not ask after every section, force spec-file184approval, or end with an execution-method menu when implementation is already185authorized. Commits follow OPS §1.186187## Failure patterns188189- New subsystem treated as new authorization: design thoroughly, then execute.190- Missing info guessed despite incompatible outcomes: inspect, then ask.191- Local security fix stalled solely because it touches auth: fix with isolated192 positive and negative checks; no production mutation implied.193- Scope or platform silently drifted: "build a CLI" became a web app, or a194 report became a dashboard, without the user's word or a stated assumption195 they could reject.196- An unstated consequential default (language, library, medium) recorded as197 if the user had chosen it: a default they never heard is one they could198 not reject; own it in plain words instead.199- CSV-only shipped when CSV and JSON were requested: incomplete, not minimal.200- Coding started before acceptance or any check existed.201- Requested features dropped as an "MVP", or unrequested ones added because202 they seemed useful.203- A spec document demanded, a human signoff awaited, or another menu offered204 for work already authorized.205- A procedural skill says stop: reconcile it with scope and authority; do not206 leave reachable implementation undone or ignore an explicit user stop.207208## Developing the user's thinking209210When the request is an unfinished idea ("I want X but not sure what", "help me211find directions"), do not demand a finished specification or choose their goal212for them. Start with the description-first question above. When they ask for213directions or need concrete examples to react to, offer two to four214meaningfully different interpretations with consequences; keep them as215proposals, not decisions already made for the user.216217When the user states an unusual method with explicit constraints (hardware,218scale, policy), evaluate it against those constraints before recommending the219standard approach; if it satisfies them, work within it and name only the risks220the stated constraints do not cover.221222The user's goal stays theirs: if they correct your interpretation of what they223want, adopt the correction and continue from it; do not re-propose the224rejected framing under a new name.225226## Check before you leave design227228- [ ] Required behavior, constraints and important risks are explicit.229- [ ] Success criteria are observable and each is mapped to a check.230- [ ] Multi-capability work has a capability map with build order.231- [ ] Necessary user decisions are resolved; ordinary details follow repo232 conventions and are recorded as your calls.233- [ ] No open question is an approval request for already authorized work.234235---236237Source: obra/superpowers (MIT); spec-driven development absorbed from238obra/superpowers and coding-kit v5.1. Adapted for coding-kit.