Visual brainstorming

Visual Brainstorming Companion

A browser-based tool for showing mockups, diagrams, and visual options during brainstorming. This is a tool — not a mode. Invoking this skill means the browser is available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.

Offering the Companion

When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer the companion once for user consent:

"Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be token-intensive. Want to try it? (Requires opening a local URL)"

This offer MUST be its own message. Do not combine it with clarifying questions, context summaries, or any other content. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.

When to Use the Browser vs Terminal

Decide per-question, not per-session. The test: would the user understand this better by seeing it than reading it?

Use the browser when the content itself is visual:

• UI mockups — wireframes, layouts, navigation structures, component designs
• Architecture diagrams — system components, data flow, relationship maps
• Side-by-side visual comparisons — two layouts, two color schemes, two design directions
• Design polish — questions about look and feel, spacing, visual hierarchy
• Spatial relationships — state machines, flowcharts, entity relationships rendered as diagrams

Use the terminal when the content is text or tabular:

• Requirements and scope questions — "what does X mean?", "which features are in scope?"
• Conceptual A/B/C choices — picking between approaches described in words
• Tradeoff lists — pros/cons, comparison tables
• Technical decisions — API design, data modeling, architectural approach selection
• Clarifying questions — anything where the answer is words, not a visual preference

A question about a UI topic is not automatically a visual question. "What kind of wizard do you want?" is conceptual — use the terminal. "Which of these wizard layouts feels right?" is visual — use the browser.

Starting a Session

After the user consents to the visual companion, ask one question before starting the server:

"Do you want to save the wireframes from this session? If yes, where should I save them? (Otherwise they'll be cleaned up automatically when we're done.)"

If they want to save: pass --project-dir <path> to start-server.sh. If not: start without --project-dir and the session cleans up on stop.

Detailed Guide

Once the user consents, read the detailed guide before proceeding: skills/visual-brainstorming/visual-companion.md