hermes-skills/software-development/brainstorming/SKILL.md

name, description

name	description
brainstorming	Formal design-brainstorming process. MUST use before any creative work, feature creation, or behavior change. Explores intent, requirements, and design through collaborative dialogue before a single line of implementation.

Brainstorming Ideas Into Designs

Turn vague ideas into fully formed designs and specs through structured collaborative dialogue.

Trigger

Use this skill whenever the user asks for:

• A new feature, component, or tool
• A modification to existing behavior
• Any creative or design work
• Anything that could be described as "build X" or "add Y"

Hard Gate

Do NOT invoke any implementation skill, write code, scaffold projects, or take implementation action until a design has been presented and the user has approved it. This applies regardless of perceived simplicity. Even a config change or single-function utility gets a design (it can be a few sentences).

Process

Follow this sequence strictly. One step at a time.

1. Explore Project Context

• Check existing files, docs, recent commits, and codebase structure
• Assess scope: if the request spans multiple independent subsystems (chat + billing + analytics), flag it immediately and decompose before refining details
• For greenfield projects, confirm it's truly greenfield

1.5 Grounding Scan (Compound Engineering)

• Before ideating, check docs/solutions/ for prior learnings relevant to this topic
• Check CONCEPTS.md for domain vocabulary that constrains the design space
• If prior learnings exist, factor them in: "Last time we solved X, we learned Y" — this is the compound advantage
• Use search_files to find relevant solutions: search_files("topic_keyword", path="docs/solutions/")
• Also query Hindsight for semantically related learnings: hindsight_recall("topic description") — catches solutions that keyword search misses (e.g. "Galera bootstrap failure" finds a doc titled "Sequential SST Recovery")
• Merge both sources: file hits give full detail, Hindsight hits give semantic matches + cross-project patterns

1.6 Scope Assessment

Classify the work before proceeding — match ceremony to size:

• Lightweight — small, well-bounded, low ambiguity → brief alignment, short doc
• Standard — normal feature or bounded refactor with some decisions → full process
• Deep — cross-cutting, strategic, or highly ambiguous → extended exploration, sub-agent grounding
• If scope is unclear, ask one targeted question to disambiguate, then proceed

For Deep scope, also classify: feature (existing product shape anchors decisions) vs product (brainstorm must establish product shape itself). Product-tier triggers additional questions about primary actors, core outcome, and positioning.

1.7 Blindspot Pass (when user signals unfamiliarity)

If the user signals they lack domain knowledge ("I know nothing about X", "never touched the auth modules"):

• Map the decision surface BEFORE asking questions — lay out the territory
• List the areas where decisions will need to be made
• For each area, note what's known vs unknown
• Then begin targeted questions from a position of mapped terrain, not blind exploration

1.8 Visual Probe Tripwire

If the feature is inherently visual or spatial (drawing/canvas tools, UI layout, interaction states, charts, diagrams, maps, timelines):

• Offer a visual companion immediately, not just-in-time
• Use browser_vision to show mockup comparisons or layout sketches
• Visual decisions should be shown, not described

2. Offer Visual Companion (Just-in-Time)

• Do NOT offer upfront
• Only offer when a question would genuinely be clearer shown than described (mockups, layout comparisons, architecture diagrams)
• Offer as a standalone message; wait for yes/no before proceeding
• If declined, continue text-only and don't offer again unless the user raises it

3. Ask Clarifying Questions — One at a Time

• Only one question per message
• Prefer multiple choice when possible
• Focus on: purpose, constraints, success criteria, audience
• Break complex topics into multiple sequential questions

4. Propose 2–3 Approaches

• Present options with trade-offs
• Lead with your recommendation and reasoning
• Keep options realistic; no strawmen

5. Present Design Sections — Incrementally

• Scale each section to its complexity (few sentences to ~200 words)
• Ask after each section: "Does this look right?"
• Cover: architecture, components, data flow, error handling, testing
• Design for isolation: each unit should have one clear purpose, well-defined interface, and be testable independently

Product Contract (for Standard/Deep scope)

For non-lightweight work, the design doc should include a Product Contract:

• Primary actors — who uses this and how
• Success criteria — measurable outcomes, not just "it works"
• Scope boundaries — explicit non-goals (what we're NOT building)
• Acceptance examples — concrete scenarios that define "done"
• Key flows — the user journeys this enables or changes
• Keep implementation details OUT of the Product Contract — libraries, schemas, endpoints belong in planning

6. Write Design Doc

• Save to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md (or user-preferred location)
• For Standard/Deep scope, use the Product Contract structure above
• Commit to git if in a repo

6.5 Verdict Routing (Compound Engineering)

During exploration, if the conversation converges on "should we adopt/switch to/revisit a specific technology X":

• This is a verdict question, not a brainstorming question
• Route to the tech-pov skill: it gives a decisive, project-grounded verdict
• Offer the handoff interactively: "This looks like a technology decision — want me to evaluate X against our project with a structured verdict?"
• On decline, continue the normal brainstorming workflow

7. Spec Self-Review

• Placeholder scan: Fix any TBD/TODO/incomplete sections
• Internal consistency: Ensure architecture matches feature descriptions
• Scope check: Confirm it's focused enough for one implementation plan
• Ambiguity check: Remove any requirement that could be interpreted two ways

8. User Review Gate

• Ask the user to review the written spec before proceeding
• Wait for approval; make changes and re-review if requested

9. Transition to Implementation

• Invoke the writing-plans skill to create the implementation plan
• Do NOT invoke frontend-design, mcp-builder, or any other implementation skill directly

Pitfalls

• Load the skill BEFORE generating brainstorming content. When a user says "brainstorming first", "let's brainstorm", or similar, load this skill IMMEDIATELY and follow its structured process (one question at a time, multiple choice, incremental validation). Do NOT dump a full ad-hoc analysis first and then load the skill afterward — the structured process IS the value, not the ideas themselves. The user asking for the skill after you've already brainstormed is a correction signal.

• One question at a time — don't overwhelm

• Multiple choice preferred — easier to answer than open-ended

• Incremental validation — present design, get approval before moving on

• Implicit Approvals: On Telegram/Slack, short confirmations like "Ja", "Passt", or "Go" are valid approvals. Do NOT demand formal section-by-section confirmation.

• Explore alternatives — always propose 2–3 approaches

• Follow existing patterns — in existing codebases, match current conventions

• Informal approvals in text-only channels — On Telegram, Slack, or similar, users may approve designs with short messages like "ja", "passt", "looks good", or "go ahead" rather than explicit section-by-section confirmation. Treat these as valid approvals and proceed. Do NOT demand formal "yes, section 3 is approved" wording.

• User provides credentials mid-process — If the user shares an API key or password during brainstorming, accept it immediately, apply it, and continue. Do NOT halt the flow to ask them to set it themselves; security handling (env vars, no hardcoding) happens in implementation.

After the Design

The terminal state of this skill is invoking writing-plans. Do NOT proceed to coding or any other implementation action without an approved plan.