Start an interactive Q&A session with deep codebase analysis and dynamically generated questions.
Interactive Q&A that analyzes your codebase to gather complete requirements before implementation. Use when planning new features or refactoring to ensure nothing is missed.
/plugin marketplace add bandofai/puerto/plugin install essentials@puertoStart an interactive Q&A session with deep codebase analysis and dynamically generated questions.
⚠️ CRITICAL: THIS COMMAND ONLY GATHERS REQUIREMENTS - NEVER IMPLEMENTS CODE ⚠️
YOU MUST NEVER:
.requirements/ folder)YOU MAY ONLY:
.requirements/ folderGOAL: Gather complete, actionable requirements so implementation can happen later with /implement command.
When user runs /brainstorm <description>:
Parse the request
Create timestamped requirement folder
.requirements/YYYY-MM-DD-HHMM-[slug]/.requirements/2025-10-25-1430-user-logging/Initialize files
01-initial-request.md - Save user's original request verbatimmetadata.json - Initialize tracking structure.requirements/_current-requirement with folder nameInitialize metadata.json
{
"id": "user-logging",
"slug": "user-logging",
"started": "2025-10-25T14:30:00Z",
"lastUpdated": "2025-10-25T14:30:00Z",
"status": "active",
"phase": "discovery",
"originalRequest": "add user logging",
"progress": {
"discovery": { "generated": false, "answered": 0, "total": 0 },
"analysis": { "status": "pending" },
"expert": { "generated": false, "answered": 0, "total": 0 }
},
"contextFiles": [],
"relatedFeatures": [],
"toolsAvailable": ["serena", "context7", "WebSearch"],
"recommendedSkill": null,
"skillRationale": null
}
Announce: "Starting requirements gathering for: [description]"
IMPORTANT: Questions are NOT hardcoded - they are generated dynamically based on the user's request!
Use sequential thinking to generate contextual questions:
Task: Generate 5-7 discovery questions to gather requirements for: "[user's request]"
Guidelines:
- Analyze what's ambiguous or unclear in the request
- Focus on WHAT the user wants, not HOW to implement
- Questions should clarify scope, behavior, and expectations
- Each question needs 2-5 numbered options with smart defaults
- Mark one option as [default - brief reason why]
- Include "Other (please specify)" for flexibility
- Mix yes/no with multiple choice appropriately
Focus areas based on request context:
- Scope and boundaries of the feature
- User interactions and workflows
- Data/content being worked with
- Performance or scale expectations
- Security/privacy considerations
- Integration with existing systems
Output format for each question:
## Q[N]: [Question Title]
[Question text that makes sense for THIS request]
Available tools: serena (code analysis), context7 (library docs), WebSearch (best practices)
Save all generated questions to: 02-discovery-questions.md
Example output for "add user logging":
## Q1: What should be logged?
What information should the logging system capture?
## Q2: Where should logs be stored?
What's the preferred log storage solution?
Example output for "build user dashboard":
## Q1: What data should the dashboard display?
What key metrics or information will users see?
## Q2: Should the dashboard update in real-time?
How current should the dashboard data be?
UX Rules:
After all discovery questions answered:
03-discovery-answers.mdmetadata.json progressNO USER INTERACTION - Fully autonomous
⚠️ CRITICAL REMINDER: READ-ONLY ANALYSIS ONLY - DO NOT IMPLEMENT ANYTHING ⚠️
Use sequential thinking for intelligent analysis:
Task: Analyze codebase to support implementing: "[user's request]"
**CRITICAL CONSTRAINTS:**
- DO NOT write, edit, or modify any code files
- DO NOT create new source code files
- DO NOT use Edit, Write, or any code modification tools
- ONLY read, search, and analyze existing code
- ONLY create requirement documents in .requirements/ folder
- Your role is RESEARCH and SPECIFICATION, not implementation
Context from discovery phase:
[Include summary of all discovery answers]
Your objectives:
1. Understand current architecture and technology stack (READ-ONLY)
2. Find similar features or related implementations (READ-ONLY)
3. Identify specific files that will need modification (DOCUMENT, don't modify)
4. Research best practices for this type of feature (RESEARCH ONLY)
5. Determine integration points with existing code (ANALYZE, don't implement)
6. Generate implementation recommendations with rationale (RECOMMEND, don't execute)
Available tools (READ-ONLY usage):
- serena: For finding symbols, searching patterns, analyzing code structure
* Use find_symbol to locate classes/functions
* Use search_for_pattern for code patterns
* Use find_referencing_symbols for dependencies
* Use get_symbols_overview for file structure
* DO NOT use replace_symbol_body, insert_after_symbol, insert_before_symbol
- context7: For library/framework documentation
* Research best practices for libraries used in codebase
- WebSearch: For industry best practices
* Search for implementation patterns
* Find security considerations
* Discover performance optimization techniques
Output required in 04-context-findings.md:
# Codebase Analysis Findings
## Architecture Overview
[High-level structure - technology stack, patterns used]
## Similar Features Found
- `[file-path]` - [what it does, why similar]
- [Include code snippets showing patterns]
## Patterns to Follow
```[language]
// Example from [file-path]:[line-number]
[relevant code snippet]
[Explanation of pattern and why it's relevant]
[path] - [what changes needed][path] - [what to add][How this feature connects to existing code]
[External best practices found via context7/WebSearch]
[Specific implementation strategy with rationale]
[Limitations, dependencies, considerations]
**After Phase 3:**
- Save findings to `04-context-findings.md`
- Update `metadata.json` with `contextFiles` and `relatedFeatures`
- Announce: "✅ Read-only analysis complete. Found [N] related features and [N] files to modify (documentation only - no code was changed). Generating expert questions..."
---
### Phase 4: Generate & Ask Expert Questions
**Again, questions are dynamically generated based on findings!**
#### Step 4.1: Generate Expert Questions
Use **sequential thinking** to generate implementation questions:
Task: Generate 5-7 expert implementation questions
Input context:
Guidelines:
Question types to consider:
Output format for each question:
[Question text referencing actual findings]
1. [Option 1] [default - reason citing analysis]
2. [Option 2]
3. [Option 3]
**Why this matters:**
[Explanation based on Phase 3 findings - cite files, patterns discovered]
Save all generated questions to: 05-expert-questions.md
**Example output for "add user logging" after finding existing Logger:**
```markdown
## Q6: Should we extend the existing Logger?
Found Logger class at src/utils/logger.ts. How should we implement user logging?
Why this matters:
Analysis found that AuthService and PaymentService both use the
existing Logger at src/utils/logger.ts:15. The Logger already supports
Winston with rotating file transport. Extending it maintains architectural
consistency and reuses existing log rotation configuration.
## Q7: Which log format should we use?
The existing Logger uses JSON format. Should user logging follow this pattern?
Why this matters:
Found 47 log statements across the codebase all using JSON format via
logger.info({...}) pattern. The log aggregator at scripts/analyze-logs.ts
parses JSON format. Consistency enables easier log analysis.
Same UX rules as Phase 2:
After all expert questions answered:
06-expert-answers.mdmetadata.jsonFirst: Detect which skill should be used for implementation
Use this logic to recommend a skill:
Analyze:
- Original request keywords
- Files involved from Phase 3 analysis
- Discovery answers (what user wants)
- Expert decisions (implementation approach)
Skill Detection Rules:
1. **developer** skill if:
- Keywords: "add", "implement", "build", "create", "fix", "refactor", "update [code]"
- Files: .ts, .tsx, .js, .jsx, .py, .go, .rs (code files)
- Context: Code implementation, testing, debugging
2. **docs-master** skill if:
- Keywords: "document", "write docs", "update README", "create guide"
- Files: .md, CLAUDE.md, AGENTS.md, docs/ folder
- Context: Documentation, guides, specifications
3. **gpt5-mini-prompting** skill if:
- Keywords: "tune", "optimize extraction", "confidence", "entity type", "prompt", "cost"
- Files: prompts-stage1.ts, prompts-stage2.ts, extractor.ts, identifier-config.ts
- Context: Prompt engineering, entity extraction
4. **skill-creator** skill if:
- Keywords: "create skill", "extract pattern", "new skill"
- Files: .claude/skills/
- Context: Meta-level skill creation
Default: `developer` if ambiguous
If multiple skills apply, recommend primary skill + note secondary tasks.
Then: Create 07-requirements-spec.md synthesizing all information:
# [Feature Name from Request]
**Created:** [ISO-8601 timestamp]
**Status:** draft
**Last Updated:** [ISO-8601 timestamp]
---
## Overview
[2-3 paragraph summary combining:
- Original request
- Discovery answers (what user wants)
- Analysis findings (current state)
- Implementation approach (expert decisions)]
---
## Implementation Strategy
### Recommended Skill
**Skill:** `[skill-name]`
**Rationale:**
This requirement involves [reason based on analysis]:
- Files to modify: [list from Phase 3]
- Task type: [feature/bugfix/refactor/documentation/optimization]
- Context: [brief explanation of why this skill fits]
The `[skill-name]` skill provides:
[List key capabilities of the skill that apply to this task]
**To implement:** Run `/implement [slug]` which will automatically invoke the `[skill-name]` skill.
**Override:** If you prefer a different approach, edit this section before running `/implement`.
**Secondary tasks:** [If other skills needed, note them here]
---
## Requirements
### Functional Requirements
[From discovery answers - what the feature must do]
1. [Requirement based on discovery Q&A]
2. [Requirement based on discovery Q&A]
3. [Additional requirements inferred]
### User Interactions
[Detailed workflow based on discovery answers]
---
## Technical Implementation
### Architecture Decision
[Based on expert Q&A - chosen approach with rationale]
### Files to Modify
[From Phase 3 analysis and Phase 4 decisions]
- **`[file-path]`**
- What to change: [description]
- Pattern to follow: [reference to similar code]
- **`[file-path]`**
- What to create: [description]
### Technology Stack
[Libraries/frameworks from analysis and decisions]
### Integration Points
[From Phase 3 analysis - how it connects]
---
## Implementation Guide
### Patterns to Follow
```[language]
// From [similar-feature-file]:[line-number]
[code snippet showing pattern to follow]
Apply this pattern for: [explanation]
[file-path] - [what it does similarly, line numbers][file-path] - [pattern to emulate][Based on how similar features are tested]
[From discovery phase and analysis]
[From Phase 3 analysis]
[From discovery answers if applicable]
[From discovery answers and analysis]
[file-path]:[line][file-path] following pattern from [reference-file][test-file-path] (follow existing test structure)[doc-path]04-context-findings.md[file-path] - [what to learn from it][Any assumptions made, open questions, or alternative approaches considered]
**After Phase 5:**
- Update `metadata.json` with recommended skill:
```json
{
"recommendedSkill": "developer",
"skillRationale": "Code implementation with testing required"
}
.requirements/_index.json:
{
"user-logging": {
"created": "2025-10-25T14:30:00Z",
"status": "draft",
"lastModified": "2025-10-25T15:15:00Z",
"lastWorked": null,
"folder": ".requirements/2025-10-25-1430-user-logging/",
"relatedFeatures": ["auth-service", "payment-logging"],
"filesInvolved": 5,
"recommendedSkill": "developer"
}
}
✅ Requirements gathering complete!
📁 All documentation saved to: .requirements/[folder]/
⚠️ IMPORTANT: NO CODE WAS MODIFIED
- This was a READ-ONLY analysis phase
- All findings are documented in requirement files
- No source code files were changed
📋 Next Steps:
1. Review requirements: .requirements/[folder]/07-requirements-spec.md
2. When ready to implement: /implement [slug]
This brainstorm session ONLY gathered requirements.
Implementation is a separate step that you control.
ALLOWED TOOLS (Read-Only):
FORBIDDEN TOOLS (Implementation):
.requirements/ folder ONLY).requirements/), git commit, npm install - NEVER useEXCEPTION: Write tool is allowed ONLY for creating requirement documents in .requirements/[timestamp-slug]/ folder. Never write to source code files.
Guidelines:
The questions adapt to the request - no more generic "what type of feature is this?"
After each phase, clearly announce:
.requirements/[folder]/. NO CODE WAS MODIFIED - implementation is a separate step."/implement [slug] to start implementation."/brainstormYou MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores requirements and design before implementation.
/brainstormUse 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