Claude-Code-Workflow/.claude/commands/workflow/brainstorm/artifacts.md

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
artifacts	Multi-phase clarification workflow generating confirmed guidance specification	topic or challenge description for clarification	TodoWrite(*), Read(*), Write(*), AskUserQuestion(*), Bash(*), Glob(*)

Brainstorm Clarification Command

📖 Overview

Purpose

Multi-phase interactive clarification workflow that collects user decisions through intelligent questioning, generating a confirmed guidance specification (declarative statements) rather than open-ended questions (interrogative sentences).

Core Philosophy Change

• ❌ OLD: Generate guidance-specification.md with open questions ("What are...?", "How should...?")
• ✅ NEW: Multi-step clarification → Generate guidance-specification.md with confirmed decisions

User Intent Preservation

Topic description is stored in session metadata and serves as authoritative reference throughout workflow lifecycle.

---

🎯 Usage

Basic Command

/workflow:brainstorm:artifacts "<topic>"

Recommended Structured Format

/workflow:brainstorm:artifacts "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]"

Example

/workflow:brainstorm:artifacts "GOAL: Build real-time collaboration platform SCOPE: Support 100 concurrent users CONTEXT: Existing monolithic architecture needs refactoring"

---

🔄 Multi-Phase Workflow

Workflow Diagram

Phase 1: Intent Classification
   │  (Understand project type and focus)
   │  → 2-3 questions, 3 choices each
   ↓
Phase 2: Role Selection
   │  (Determine participating roles)
   │  → Recommend 3-5 roles, multiSelect
   ↓
Phase 3: Role-Specific Questions
   │  (Collect professional domain decisions)
   │  → 3-5 questions per role, 3 choices each
   ↓
Phase 4: Cross-Role Clarification
   │  (Ensure inter-role consistency)
   │  → 1-2 questions per role from related role perspectives
   ↓
Phase 5: Generate Guidance Specification
   │  (Create confirmed guidance document)
   └─→ guidance-specification.md (declarative statements)

---

📋 Phase 1: Intent Classification

Purpose

Understand project type and focus areas to customize subsequent questions.

Implementation

Use AskUserQuestion tool to intelligently generate 2-3 classification questions based on user's topic description.

Question Types (Intelligently Generated)

1. Project Type: New feature / Optimization / Refactoring
2. Value Focus: UX-driven / Technical capability / Business value
3. System Scale: Small (MVP) / Medium / Large (Enterprise)

Output

• intent_context: Classification results
• Stored in session metadata for Phase 2-4 customization

Example Flow

AskUserQuestion({
  questions: [{
    question: "What is the project type?",
    header: "Project Type",
    multiSelect: false,
    options: [
      {label: "New Feature Development", description: "Build new features or products from scratch"},
      {label: "System Optimization", description: "Improve performance, experience, or architecture"},
      {label: "Architecture Migration", description: "Technology stack upgrade or system migration"}
    ]
  }]
  // ... Generate 2-3 classification questions similarly
})

---

👥 Phase 2: Role Selection

Purpose

Determine which roles should participate in analysis.

Implementation Steps

1. Analyze Topic + Phase 1 Results Intelligently recommend 3-5 relevant roles based on keywords.

2. Role Recommendation Logic

• Technical keywords (architecture, system, performance, database) → system-architect, data-architect, subject-matter-expert
• API/Backend keywords (api, endpoint, rest, graphql, service) → api-designer, system-architect, data-architect
• UX keywords (user, ui, ux, design, experience) → ui-designer, ux-expert, product-manager
• Business keywords (business, process, workflow, cost) → product-manager, product-owner
• Agile keywords (sprint, scrum, team, delivery) → scrum-master, product-owner

3. Present to User Use AskUserQuestion with multiSelect for role selection.

Available Roles

Technical: system-architect, data-architect, subject-matter-expert, api-designer Product & Design: ui-designer, ux-expert, product-manager, product-owner Agile & Quality: scrum-master, test-strategist

Detailed role descriptions: See "Reference Information > Available Roles Reference"

Output

• selected_roles: List of user-selected roles
• Stored in session metadata

---

🎓 Phase 3: Role-Specific Professional Questions

Purpose

Collect decisions for each role's professional domain.

Implementation

For each selected role, intelligently generate 3-5 core questions based on:

• Role's professional expertise area
• User's topic description
• Phase 1 intent context

Question Generation Rules

1. Exactly 3 options per question (MECE principle)
2. Concrete and actionable options
3. Avoid vague options like "depends on situation"
4. Use AskUserQuestion with multiSelect: false

Role Question Focus Areas

system-architect:

• Architecture style (microservices/monolith/hybrid)
• Data consistency (strong/eventual/hybrid)
• Performance priority (latency/throughput/resource)
• Deployment model (cloud-native/VM/serverless)

ui-designer:

• Visual style (minimalist/rich/professional)
• Component complexity (simple/moderate/complex)
• Design system maturity (full/basic/lightweight)
• Responsive strategy (mobile-first/desktop-first/adaptive)

ux-expert:

• User persona (novice/intermediate/expert)
• Interaction complexity (simple/rich/professional)
• Accessibility level (WCAG AA/AAA/basic)
• Testing strategy (comprehensive/targeted/minimal)

product-manager:

• MVP scope (minimal core/core+hooks/full feature set)
• Timeline expectation (fast iteration/standard/robust)
• Priority strategy (user value/technical debt/innovation)
• Success metrics (usage/satisfaction/revenue)

data-architect:

• Storage technology (relational/NoSQL/polyglot)
• Data model complexity (simple/moderate/complex domain)
• Analytics needs (basic/moderate/advanced)
• Compliance requirements (GDPR/HIPAA/none)

Other roles (api-designer, product-owner, scrum-master, subject-matter-expert, test-strategist): Similar 3-5 questions tailored to their domains.

Example: System Architect Questions

For topic "Build real-time collaboration platform":

AskUserQuestion({
  questions: [
    {
      question: "System architecture style preference?",
      header: "Architecture Style",
      multiSelect: false,
      options: [
        {label: "Microservices", description: "Independent service deployment, suitable for large teams"},
        {label: "Modular Monolith", description: "Single deployment unit, suitable for small to medium teams"},
        {label: "Hybrid Architecture", description: "Core monolith + partial microservices"}
      ]
    }
    // ... Generate 3-5 questions similarly
  ]
})

Other roles: Generate similarly based on professional domains (see "Role Question Focus Areas")

Output

• role_decisions: Map of {role: [answers]} for all selected roles
• Stored in session metadata

---

🔗 Phase 4: Cross-Role Clarification Questions

Purpose

Ensure consistency across roles and identify potential conflicts.

Implementation

For each selected role, intelligently generate 1-2 cross-role questions from perspectives of 2-3 related roles.

Cross-Role Relationship Matrix

Current Role	Question from Role Perspectives	Question Topics
system-architect	ui-designer, product-manager, data-architect	Frontend stack, MVP scope, storage choice
ui-designer	ux-expert, system-architect, product-owner	Design system, technical constraints, feature priority
product-manager	system-architect, ux-expert, scrum-master	Technical feasibility, user pain points, delivery rhythm
ux-expert	ui-designer, product-manager, subject-matter-expert	Visual style, user goals, industry norms
data-architect	system-architect, subject-matter-expert, api-designer	Integration patterns, compliance requirements, API design

Example: Cross-Role Question

System-architect asking from ui-designer perspective:

AskUserQuestion({
  questions: [{
    question: "Frontend technology stack choice? (Impacts frontend-backend separation strategy)",
    header: "Frontend Stack",
    multiSelect: false,
    options: [
      {label: "Modern Framework (React/Vue)", description: "Requires dedicated frontend team"},
      {label: "Server-Side Rendering (Next.js)", description: "SEO-friendly"},
      {label: "Lightweight (jQuery)", description: "Backend-driven"}
    ]
  }]
  // ... 1-2 cross-role questions per role
})

Output

• cross_role_decisions: Map of {role: {from_role: [answers]}}
• Stored in session metadata

---

📄 Phase 5: Generate Guidance Specification

Purpose

Based on all user choices, generate a confirmed guidance document with declarative statements, not questions.

Implementation

1. Consolidate all decisions:

   • intent_context (Phase 1)
   • selected_roles (Phase 2)
   • role_decisions (Phase 3)
   • cross_role_decisions (Phase 4)

2. Generate guidance-specification.md with confirmed decisions

Output Document Structure

See "Output Specification" section below for complete template.

Output Location

.workflow/WFS-[topic]/.brainstorming/guidance-specification.md

Detailed file structure: See "Reference Information > File Structure"

---

🔧 Implementation Details

Session Management ⚠️ CRITICAL

⚡ First Step: Check .workflow/.active-* markers

Logic:

• Multiple active sessions → Prompt user to select
• Single active session → Use that session
• No active session → Create new WFS-[topic-slug]

Session Data Storage:

• Decision data: workflow-session.json
• Output file: .brainstorming/guidance-specification.md

Implementation Workflow

Execution Flow:

1. Session Management: Detect or create session
2. Phase 1: Intent classification (2-3 questions)
3. Phase 2: Role selection (recommendations + multiSelect)
4. Phase 3: Role professional questions (3-5 questions per role)
5. Phase 4: Cross-role clarification (1-2 questions per role)
6. Phase 5: Generate guidance-specification.md
7. Update Metadata: Save all decisions to session

TodoWrite tracking: Update progress at each Phase

Decision storage: All user choices saved to workflow-session.json

---

🤖 Intelligent Question Generation

Core Principle

All questions are intelligently generated by Claude based on:

• Role professional domain
• User's topic description
• Previous decision context
• Phase 1 intent classification

No Template Library Required: Questions are dynamically created to fit specific task context.

Question Generation Guidelines

For Phase 3 (Role Questions):

INPUT: role + topic + intent_context
OUTPUT: 3-5 questions, each with 3 MECE options

Example:
- Role: system-architect
- Topic: "Build real-time collaboration platform"
- Intent: {type: "new_feature", scale: "medium", focus: "technical"}

Generated Questions:
1. Architecture style? [Microservices/Modular Monolith/Hybrid]
2. Real-time communication tech? [WebSocket/SSE/Polling]
3. Data consistency? [Strong/Eventual/Hybrid]
4. Deployment model? [Cloud-native/Traditional VM/Serverless]

For Phase 4 (Cross-Role Questions):

INPUT: current_role + related_role + role_decisions + topic
OUTPUT: 1-2 questions from related_role perspective

Example:
- Current: system-architect
- Related: ui-designer
- Topic: "Build real-time collaboration platform"
- Context: ui-designer chose "Modern Framework (React)"

Generated Question:
"Frontend technology stack choice? (Impacts frontend-backend separation strategy)"
[Modern Framework/Server-Side Rendering/Lightweight]

---

✅ Validation & Quality Assurance

Output Validation

Guidance Specification Must Contain:

• ✅ All declarative statements: No question marks in decision sections
• ✅ Clear decisions: Every decision point has explicit choice
• ✅ Decision traceability: Can trace back to user answers
• ✅ Cross-role consistency: Conflicts resolved or noted
• ✅ Actionability: Next steps are clear

Validation Checklist

The generated guidance-specification.md must pass these checks:

✅ No interrogative sentences: Decision sections should not end with question marks ✅ Clear decisions: Every decision point has explicit choice (not "TBD"/"Pending") ✅ Traceable: Every decision can be traced back to user answers ✅ Cross-role consistency: Cross-role decision count ≥ number of selected roles ✅ Actionable: "Next steps" are clear and specific

Automatic validation: Execute checks after generation, prompt if issues found

---

📝 Output Specification

Document Structure Overview

Output file: .workflow/WFS-[topic]/.brainstorming/guidance-specification.md

Template Structure

# [Project] - Confirmed Guidance Specification

**Metadata**: [timestamp, type, focus, roles]

## 1. Project Positioning & Goals
**CONFIRMED**: [objectives, success criteria]

## 2-5. Role-Specific Decisions
Each participating role has one section containing:
- **SELECTED**: [confirmed choices]
- **Rationale**: [reasoning]
- **Constraints/Impact**: [implications]
- **Cross-Role Confirmed**: [dependencies]

## 6. Cross-Role Integration
**CONFIRMED**: [API style, data format, auth, collaboration model]

## 7. Risks & Constraints
**Identified**: [risks with mitigation, constraints]

## 8. Next Steps
**Immediate Actions**: [action items]
**Role Assignments**: [tasks per role]

## Appendix: Decision Tracking
**Key Decisions**: [table]
**Open Items**: [list]

Core principles:

• All decisions use declarative statements (CONFIRMED/SELECTED)
• Every decision is traceable to user answers
• Cross-role decisions ensure consistency
• Next steps are clear and specific

---

🔄 Update Mechanism

Existing Guidance Update

IF guidance-specification.md EXISTS:
    SHOW current guidance summary to user
    ASK: "Guidance exists. Do you want to:"
    OPTIONS:
      1. "Regenerate completely" → Start full clarification flow
      2. "Update specific sections" → Target specific roles/decisions
      3. "Cancel" → Exit without changes
ELSE:
    CREATE new guidance through full clarification

Update Strategies:

1. Complete Regeneration: Backup existing → Full clarification flow
2. Targeted Update: Update specific role sections or cross-role decisions
3. Incremental Addition: Add new roles or decision areas

---

⚠️ Error Handling

Error Type	Handling Strategy
Session creation failed	Error details + retry option + check permissions
AskUserQuestion timeout	Save progress + allow resumption + provide instructions
Incomplete clarification	Mark open items + suggest follow-up clarification
Conflicting decisions	Highlight conflicts + show disagreeing roles + suggest resolution

---

🔗 Integration with Downstream Workflow

Core Principles & Governance Rules

GOVERNANCE_RULES for guidance-specification.md output:

✅ Declarative Statements Only

• All decisions MUST use CONFIRMED/SELECTED format
• NO interrogative sentences (no "?" in decision sections)
• NO open questions or TBD items in confirmed decisions

✅ Decision Traceability

• Every decision MUST trace back to specific user answer
• Cross-reference to Phase 1-4 clarification responses
• Document rationale for each confirmed choice

✅ Cross-Role Consistency

• Cross-role decisions count ≥ number of selected roles
• Conflicts MUST be resolved or explicitly documented
• Dependencies between roles clearly stated

✅ Actionability Requirements

• Next steps MUST be concrete and specific
• Role assignments clearly defined
• Success criteria measurable and verifiable

✅ Session Integrity

• All decisions stored in workflow-session.json
• Topic description preserved as authoritative reference
• Session lifecycle properly managed (active markers, metadata)

CRITICAL: Generated guidance is the single source of truth for all downstream workflow phases. Any ambiguity violates governance rules and MUST be resolved before proceeding.

---

Next Steps After Guidance Generation

Standard Workflow:

/workflow:concept-clarify --session WFS-{session-id}           # Optional: Further clarification
/workflow:plan --session WFS-{session-id}                      # Generate IMPL_PLAN.md and tasks
/workflow:action-plan-verify --session WFS-{session-id}        # Optional: Verify plan quality
/workflow:execute --session WFS-{session-id}                   # Start implementation

---

📚 Reference Information

File Structure

.workflow/WFS-[topic]/
├── workflow-session.json                    # Session metadata with all decisions
└── .brainstorming/
    ├── guidance-specification.md           # ★ PRIMARY OUTPUT (declarative statements)
    └── [role]/
        └── analysis.md                     # Role deepening analysis (generated later)

Available Roles Reference

Technical Roles:

• system-architect: Architecture patterns, scalability, technology stack, integration
• data-architect: Data modeling, storage workflows, analytics, compliance
• subject-matter-expert: Domain expertise, industry standards, best practices
• api-designer: API design, versioning, contracts, authentication

Product & Design Roles:

• ui-designer: User interface, visual design, components, accessibility
• ux-expert: User experience, usability testing, interaction design, design systems
• product-manager: Business value, feature prioritization, market positioning, roadmap
• product-owner: Backlog management, user stories, acceptance criteria, stakeholder alignment

Agile & Quality Roles:

• scrum-master: Sprint planning, team dynamics, process optimization, delivery management
• test-strategist: Testing strategies, quality assurance, test automation, validation approaches

Architecture Reference

• Workflow Architecture: @~/.claude/workflows/workflow-architecture.md
• Clarification Plan: @~/.claude/workflows/brainstorm-clarification-plan.md

Related Commands

• /workflow:brainstorm:auto-parallel - Parallel role analysis execution
• /workflow:brainstorm:synthesis - Synthesize role analyses
• /workflow:brainstorm:[role] - Individual role analysis commands
• /workflow:concept-clarify - Further concept clarification
• /workflow:plan - Generate implementation plan