Collaborative design refinement that transforms rough ideas into fully-formed specifications through Socratic questioning. Explores alternatives, validates incrementally, and presents designs in digestible chunks for feedback. Use before writing code or implementation plans when requirements are unclear or multiple approaches exist. Do NOT use when requirements are already well-defined, you're implementing a known pattern, or making small changes - proceed directly to implementation instead.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
name: brainstorming description: "Collaborative design refinement that transforms rough ideas into fully-formed specifications through Socratic questioning. Explores alternatives, validates incrementally, and presents designs in digestible chunks for feedback. Use before writing code or implementation plans when requirements are unclear or multiple approaches exist. Do NOT use when requirements are already well-defined, you're implementing a known pattern, or making small changes - proceed directly to implementation instead." inputs:
Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
Announce at start: "I'm using the brainstorming skill to refine this idea into a design."
BEFORE brainstorming, verify this work hasn't been done or planned:
# Search for existing/related issues
gh issue list --search "<topic keywords>" --state all --json number,title,state --limit 10
# Search for related skills
grep -r "<keywords>" packages/plugin/skills/ --include="SKILL.md" -l
# Search for related utilities
grep -r "<keywords>" packages/plugin/hooks/utils/ --include="*.py" -l
# Check if another skill passed context to us
from hooks.utils.skill_context import load_skill_context
ctx = load_skill_context()
if ctx and ctx.previous_output:
# Use existing context instead of re-asking
topic = ctx.previous_output.get("topic")
existing_decisions = ctx.shared_decisions
If related issues or code found:
Use AskUserQuestion tool with:
- question: "Found existing work related to '<topic>'. How should we proceed?"
- header: "Existing"
- options:
- label: "Use existing"
description: "Build on what's already there"
- label: "Enhance"
description: "Extend existing with new features"
- label: "Start fresh"
description: "Create new (explain why existing doesn't fit)"
- multiSelect: false
Only proceed to brainstorming after completing this check.
ALWAYS use AskUserQuestion for decisions and clarifications:
Use AskUserQuestion tool with:
- question: Clear, specific question ending with "?"
- header: Short label (max 12 chars): "Approach", "Auth", "Database"
- options: 2-4 choices with labels and descriptions
- multiSelect: false (unless multiple selections make sense)
NEVER present options as plain text like "1. Option A, 2. Option B - type 1 or 2".
Understanding the idea:
Exploring approaches:
Presenting the design:
Documentation:
docs/plans/YYYY-MM-DD-<topic>-design.mdContext Handoff (for downstream skills):
# Save context for pop-writing-plans or other downstream skills
from hooks.utils.skill_context import save_skill_context, SkillOutput, link_workflow_to_issue
# Save design output
save_skill_context(SkillOutput(
skill_name="pop-brainstorming",
status="completed",
output={
"topic": "<topic>",
"approach": "<chosen approach>",
"design_summary": "<brief summary>"
},
artifacts=["docs/plans/YYYY-MM-DD-<topic>-design.md"],
next_suggested="pop-writing-plans",
decisions_made=[<list of AskUserQuestion results>]
))
# If GitHub issue exists, link it
if issue_number:
link_workflow_to_issue(issue_number)
Create or Link GitHub Issue:
# If no issue exists, offer to create one
gh issue create --title "[Design] <topic>" --body "Design document: docs/plans/..."
Implementation (if continuing):
When provided with a PDF file path (design doc, spec, or requirements), read it first:
User: Here's the design doc: /path/to/design.pdf
Process PDF input:
When reading design PDFs:
This allows brainstorming to start from existing documentation rather than from scratch.