brainstorming-design
Skill0 starsChanged 22 days agoMITView on GitHub
Use when the idea is still ROUGH and no design exists yet. Turns a vague feature request into an approved design through questions, before any implementation. If a plan or design already exists and needs stress-testing, use grilling instead.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- thomascasali/memotecatheir own version, first seen Nov 8, 2026
- thomascasali/claude-kb-workflowtheir own version, first seen Oct 13, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- thomascasali/claude-kb-workflow★ 4same name
- thomascasali/memoteca★ 4same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository25 other files it gives its agents.
- AGENTS.mdAGENTS.md
- branch-lifecycleSkill
- bug-feedback-loopSkill
- codebase-designSkill
- code-review-disciplineSkill
- domain-modelingSkill
- failure-classesSkill
- git-safetySkill
- grillingSkill
- handoffSkill
- ops-safetySkill
- prototypeSkill
- quality-floorSkill
- researchSkill
- subagent-driven-devSkill
- systematic-debuggingSkill
- terse-modeSkill
- test-driven-developmentSkill
- ui-designSkill
- using-skillsSkill
- verification-before-completionSkill
- vetting-third-partySkill
- writing-plansSkill
- writing-skillsSkill
- zoom-outSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 9
Do NOT write code, scaffold a project, or take any implementation action until you have told the user what you intend and they approved it.
- Distinctive: line 16
Before your first question, classify the request and announce the classification ("this looks bounded, so I'll present a short design here …
- Distinctive: line 30
Know what you know first: If everything that matters is already in the request ("make the icon cornflower blue"), it is a quick, clear …
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Brainstorming Ideas Into Designs
<HARD-GATE>
Do NOT write code, scaffold a project, or take any implementation action until you have told the user what you intend and they approved it. This applies to EVERY task on EVERY path below — **the ceremony scales with the task; the approval gate never does.**
</HARD-GATE>"Simple" projects are where unexamined assumptions cause the most wasted work. The design can be two sentences in chat — but you MUST present it and get approval. What scales with simplicity is the artifact, never the approval.
Three paths — classify first, say it out loud
Before your first question, classify the request and announce the classification ("this looks bounded, so I'll present a short design here rather than write a spec") so the user can override it.
| Path | What it is | Process |
| Spike | A feasibility question ("can we…", "is it possible…", "quick and dirty is fine") whose output is an answer, not code you keep. | Present the question + what you'll try in 2-3 sentences → get a nod → find out as cheaply as correctness allows → report a recommendation. Anything built stays labelled throwaway. No design doc, no spec. |
| Bounded | A well-scoped change to code that already exists in this repo — a new flag, a small endpoint, a one-file fix. Bounded means the flow you're changing is here to read; no existing flow → not bounded. | Ask the clarifying questions that matter → present a short design in chat (a few sentences to a few short paragraphs: approach, files touched, testing) → STOP and wait for an explicit yes → implement via the normal workflow (TDD applies). No spec file, no plan document. |
| Architectural | New projects, new subsystems, changes that restructure how components fit together or alter interfaces others depend on. | The full checklist below → written spec → writing-plans. |
When in doubt between two paths, take the heavier one. The ratchet is one-way: hidden complexity discovered mid-task upgrades the path — stop, say so, step up. Nothing downgrades mid-task.
Terminal states are path-bound. Architectural → writing-plans, never an implementation skill. Bounded → implementation directly, no plan document. Spike → a reported recommendation.
Shared understanding before the first design question
- Know what you know first. If everything that matters is already in the request ("make the icon cornflower blue"), it is a quick, clear task: do it and say what you did. If something non-trivial is missing, start the conversation.
- First message = two things, in order: (1) one line saying they can skip the questions and have you just start (if they do, state any significant how-it-gets-made choice — platform, language, medium — in one plain line and continue through the normal workflow; the gate below no longer applies); (2) ONE open question that gets them describing a real moment or concrete picture, not a menu.
- Discover intent first. Ask the purpose before proposing features or an approach. Each message ends with exactly one question (one sentence, no list of example answers). Open questions before options; offer a short menu only when they are stuck, and when they say "just guess" propose something concrete. Match their vocabulary, no process jargon.
- Find out who decides the how (medium, tools, language, existing assets): build on what the repo already uses; any choice you make goes in the design as YOUR call, never as something they agreed to.
- Play back in chunks. As soon as one part is clear enough, describe it back in ~200-300 words in your own words, mark guesses as guesses (only what they said goes in as theirs), end by asking what is wrong or missing, then return to questions about the next part. Playback and questions alternate.
- Offer recon (codebase, files, web) once there is grounding; say what you would look for; they decide. Think wide privately (several ideas, drop the weak ones) and show the comparison only when it helps them decide.
- A reply approves the stage actually presented, nothing beyond it. Approval of an idea or a feature scope does not approve artifacts that do not exist yet: conversational design approval only permits writing the spec; written-spec approval only permits invoking
writing-plans. Read-only exploration of the repo is allowed before approval; writing is not. - A "simple todo app" from scratch is a new project -> architectural, not two sentences in chat.
Red flags
| Thought | Reality |
| "Too simple to need a design" | Simple means a short design, not none. Two sentences, then approval. |
| "I'll call it bounded and skip the spec" | Reaching for a label to skip work IS the doubt — take the heavier path. |
| "It's bounded and obvious — I'll start while they read it" | The gate is the approval, not the design's length. Present, then stop until you hear yes. |
| "I understand this kind of app, so it's bounded" | Bounded measures the repo, not your familiarity. A new project has no existing flow — it's architectural. |
| "I'll fill in sensible defaults silently" | Say them out loud. A default they never heard is one they could not reject. |
| "The spike works, so I'll keep the code" | A spike's output is an answer. Keeping the code is a new request — classify it. |
| "It grew, but I'm almost done — no need to re-classify" | Hidden complexity upgrades the path mid-task. Stop and say so. |
| "They approved the spike, so the follow-up is approved too" | Each task gets its own classification and its own approval. |
Checklist — architectural path (create a todo per item)
- Explore project context — files, docs, recent commits. Follow existing patterns.
- Scope check — request spans multiple independent subsystems? Decompose into sub-projects first; each gets its own spec → plan → implementation cycle.
- Ask clarifying questions — ONE at a time. Multiple choice preferred. Focus: purpose, constraints, success criteria.
- Propose 2-3 approaches with trade-offs; lead with your recommendation and reasoning.
- Present the design in sections scaled to complexity; get approval after each section. Cover: architecture, components, data flow, error handling, testing.
- Write the design doc to
docs/specs/YYYY-MM-DD-<topic>-design.mdand commit. (User preference overrides location.) - Builder check — dispatch a fresh subagent as "a talented
<domain>builder who cannot talk to the author": read the spec, report ONLY the questions whose wrong guess would matter, ranked, each with why it changes the plan ("nothing important left" if none). Sort into: answered already (put it in the spec) / minor (settle it, mark as your call) / theirs (only the user can answer and it changes what gets built). Bring "theirs" in ONE message, update the spec, hand it over with the list of your calls. One round only. No subagent tool -> read it as that builder yourself. - User reviews the written spec — wait for approval before proceeding.
- Transition — invoke
writing-plans. That is the ONLY next skill.
Design Principles
- YAGNI ruthlessly — cut unnecessary features from every design.
- Design for isolation: each unit has one clear purpose, a well-defined interface, and can be understood and tested independently. Can someone use it without reading its internals? Can you change internals without breaking consumers? If not, boundaries need work.
- Existing code with problems that affect the work → include targeted improvements. Don't propose unrelated refactoring.
Distilled from obra/superpowers (MIT © Jesse Vincent / Prime Radiant), v7.0.0 @ bb92a77 (2026-10-12).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.