- Update session-start hook to clarify that using-superpowers content is provided directly
- Add explicit guidance to use Skill tool only for other skills
- Prevents confusing loop where agents execute using-superpowers manually
- Reduces overhead and improves user experience
Fixes redundant skill execution in bootstrap workflow.
Update .claude-plugin/plugin.json version from 3.2.3 to 3.4.0 to match
the version already set in marketplace.json. This ensures consistency
across all plugin manifest files.
Remove heavyweight 6-phase process with formal checklists and return to
conversational approach:
- Natural dialogue instead of structured phases
- One question at a time without rigid progression
- 200-300 word design sections with validation
- Keep documentation and implementation handoff
- Remove AskUserQuestion tool requirements and complex flowcharts
This aligns with the original spec: help turn ideas into designs through
collaborative questioning, then present design in small sections.
2025-10-30 20:21:28 -07:00
5 changed files with 49 additions and 158 deletions
- Optimized superpowers bootstrap to eliminate redundant skill execution. The `using-superpowers` skill content is now provided directly in session context, with clear guidance to use the Skill tool only for other skills. This reduces overhead and prevents the confusing loop where agents would execute `using-superpowers` manually despite already having the content from session start.
## v3.4.0 (2025-10-30)
### Improvements
- Simplified `brainstorming` skill to return to original conversational vision. Removed heavyweight 6-phase process with formal checklists in favor of natural dialogue: ask questions one at a time, then present design in 200-300 word sections with validation. Keeps documentation and implementation handoff features.
"additionalContext": "<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**The content below is from skills/using-superpowers/SKILL.md - your introduction to using skills:**\n\n${using_superpowers_escaped}\n\n${warning_escaped}\n</EXTREMELY_IMPORTANT>"
"additionalContext": "<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${using_superpowers_escaped}\n\n${warning_escaped}\n</EXTREMELY_IMPORTANT>"
description: Use when creating or developing anything, before writing code or implementation plans - refines rough ideas into fully-formed designs through structured Socratic questioning, alternative exploration, and incremental validation
description: Use when creating or developing, before writing code or implementation plans - refines rough ideas into fully-formed designs through collaborative questioning, alternative exploration, and incremental validation. Don't use during clear 'mechanical' processes
---
---
# Brainstorming Ideas Into Designs
# Brainstorming Ideas Into Designs
## Overview
## Overview
Transform rough ideas into fully-formed designs through structured questioning and alternative exploration.
Help turn ideas into fullyformed designs and specs through natural collaborative dialogue.
**Core principle:** Research first, ask targeted questions to fill gaps, explore alternatives, present design incrementally for validation.
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 your idea into a design."
## Quick Reference
| Phase | Key Activities | Tool Usage | Output |
|-------|---------------|------------|--------|
| **Prep: Autonomous Recon** | Inspect repo/docs/commits, form initial model | Native tools (ls, cat, git log, etc.) | Draft understanding to confirm |
| **1. Understanding** | Share findings, ask only for missing context | AskUserQuestion for real decisions | Purpose, constraints, criteria (confirmed) |
| **2. Exploration** | Propose 2-3 approaches | AskUserQuestion for approach selection | Architecture options with trade-offs |
| **3. Design Presentation** | Present in 200-300 word sections | Open-ended questions | Complete design with validation |
- [ ] Phase 4: Design Documentation (design written to docs/plans/)
- [ ] Phase 5: Worktree Setup (if implementing)
- [ ] Phase 6: Planning Handoff (if implementing)
```
### Prep: Autonomous Recon
**Presenting the design:**
-Use existing tools (file browsing, docs, git history, tests) to understand current project state before asking anything.
-Once you believe you understand what you're building, present the design
-Form your draft model: what problem you're solving, what artifacts exist, and what questions remain.
-Break it into sections of 200-300 words
-Start the conversation by sharing that model: "Based on exploring the project state, docs, working copy, and recent commits, here's how I think this should work…"
-Ask after each section whether it looks right so far
-Ask follow-up questions only for information you cannot infer from available materials.
-Cover: architecture, components, data flow, error handling, testing
- Be ready to go back and clarify if something doesn't make sense
### Phase 1: Understanding
## After the Design
- Share your synthesized understanding first, then invite corrections or additions.
- Ask one focused question at a time, only for gaps you cannot close yourself.
- **Use AskUserQuestion tool** only when you need the human to make a decision among real alternatives.
- Gather: Purpose, constraints, success criteria (confirmed or amended by your partner)
**Example summary + targeted question:**
**Documentation:**
```
- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
Based on the README and yesterday's commit, we're expanding localization to dashboard and billing emails; admin console is still untouched. Only gap I see is whether support responses need localization in this iteration. Did I miss anything important?
- Use elements-of-style:writing-clearly-and-concisely skill if available
```
- Commit the design document to git
### Phase 2: Exploration
**Implementation (if continuing):**
-Propose 2-3 different approaches
-Ask: "Ready to set up for implementation?"
-For each: Core architecture, trade-offs, complexity assessment, and your recommendation
-Use superpowers:using-git-worktrees to create isolated workspace
-**Use AskUserQuestion tool** to present approaches when you truly need a judgement call
- Use superpowers:writing-plans to create detailed implementation plan
- Lead with the option you prefer and explain why; invite disagreement if your partner sees it differently
- Own prioritization: if the repo makes priorities clear, state them and proceed rather than asking
**Example using AskUserQuestion:**
```
Question: "Which architectural approach should we use?"
Options:
- "Direct API calls with retry logic" (simple, synchronous, easier to debug) ← recommended for current scope
- "Event-driven with message queue" (scalable, complex setup, eventual consistency)
- "Hybrid with background jobs" (balanced, moderate complexity, best of both)
I recommend the direct API approach because it matches existing patterns and minimizes new infrastructure. Let me know if you see a blocker that pushes us toward the other options.
```
### Phase 3: Design Presentation
- Present in coherent sections; use ~200-300 words when introducing new material, shorter summaries once alignment is obvious
- Cover: Architecture, components, data flow, error handling, testing
- Check in at natural breakpoints rather than after every paragraph: "Stop me if this diverges from what you expect."
- Use open-ended questions to allow freeform feedback
- Assume ownership and proceed unless your partner redirects you
### Phase 4: Design Documentation
After validating the design, write it to a permanent document:
- **File location:** `docs/plans/YYYY-MM-DD-<topic>-design.md` (use actual date and descriptive topic)
- **RECOMMENDED SUB-SKILL:** Use elements-of-style:writing-clearly-and-concisely (if available) for documentation quality
- **Content:** Capture the design as discussed and validated in Phase 3, organized into sections that emerged from the conversation
- Commit the design document to git before proceeding
### Phase 5: Worktree Setup (for implementation)
When design is approved and implementation will follow:
- Announce: "I'm using the using-git-worktrees skill to set up an isolated workspace."
- **REQUIRED SUB-SKILL:** Use superpowers:using-git-worktrees
- Follow that skill's process for directory selection, safety verification, and setup
- Return here when worktree ready
### Phase 6: Planning Handoff
Ask: "Ready to create the implementation plan?"
When your human partner confirms (any affirmative response):
- Announce: "I'm using the writing-plans skill to create the implementation plan."
- **REQUIRED SUB-SKILL:** Use superpowers:writing-plans
- Create detailed plan in the worktree
## Question Patterns
### When to Use AskUserQuestion Tool
**Use AskUserQuestion when:**
- You need your partner to make a judgement call among real alternatives
- You have a recommendation and can explain why it’s your preference
- Prioritization is ambiguous and cannot be inferred from existing materials
**Best practices:**
- State your preferred option and rationale inside the question so your partner can agree or redirect
- If you know the answer from repo/docs, state it as fact and proceed—no question needed
- When priorities are spelled out, acknowledge them and proceed rather than delegating the choice back to your partner
### When to Use Open-Ended Questions
**Use open-ended questions for:**
- Phase 3: Design validation ("Does this look right so far?")
- When you need detailed feedback or explanation
- When partner should describe their own requirements
- When structured options would limit creative input
Frame them to confirm or expand your current understanding rather than reopening settled topics.
**Example decision flow:**
- "What authentication method?" → Use AskUserQuestion (2-4 options)
- "Does this design handle your use case?" → Open-ended (validation)
## When to Revisit Earlier Phases
```dot
digraph revisit_phases {
rankdir=LR;
"New constraint revealed?" [shape=diamond];
"Partner questions approach?" [shape=diamond];
"Requirements unclear?" [shape=diamond];
"Return to Phase 1" [shape=box, style=filled, fillcolor="#ffcccc"];
"Return to Phase 2" [shape=box, style=filled, fillcolor="#ffffcc"];
- **Be flexible** - Go back and clarify when something doesn't make sense
| **Incremental validation** | Present design in sections, validate each |
| **Flexible progression** | Go backward when needed - flexibility > rigidity |
| **Own the initiative** | Recommend priorities and next steps; ask if you should proceed only when requirements conflict |
| **Announce usage** | State skill usage at start of session |
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
