refactor(auto-parallel): delegate role selection to artifacts command for interactive user experience

2026-02-05 01:50:27 +08:00 · 2025-10-24 20:32:24 +08:00
parent a208af22af
commit 080c8be87f
2 changed files with 181 additions and 89 deletions
--- a/.claude/commands/workflow/brainstorm/artifacts.md
+++ b/.claude/commands/workflow/brainstorm/artifacts.md
@@ -45,7 +45,8 @@ Five-phase workflow: Extract topic challenges → Select roles → Generate task
 **Steps**:
 1. **Deep topic analysis**: Extract technical entities, identify core challenges (what makes this hard?), constraints (timeline/budget/compliance), success metrics (what defines done?)
 2. **Generate 2-4 probing questions** targeting root challenges, trade-off priorities, and risk tolerance (NOT surface-level "Project Type")
-3. AskUserQuestion → Store to `session.intent_context` with `{extracted_keywords, identified_challenges, user_answers}`
+3. **User interaction via AskUserQuestion tool**: Present 2-4 task-specific questions (multiSelect: false for single-choice questions)
+4. **Storage**: Store answers to `session.intent_context` with `{extracted_keywords, identified_challenges, user_answers}`

 **Example (Task-Specific)**:
 Topic: "Build real-time collaboration platform SCOPE: 100 users"
@@ -75,10 +76,27 @@ Topic: "Build real-time collaboration platform SCOPE: 100 users"
   - Recommend count+2 roles (e.g., if user wants 3 roles, recommend 5 options)
   - Provide clear rationale for each recommended role based on topic context

-2. **User selection via multiSelect**:
-   - Present recommended roles with context-specific rationales
-   - Allow user to select multiple roles (typically count roles, but flexible)
-   - Store selections to `session.selected_roles`
+2. **User selection via AskUserQuestion tool (multiSelect mode)**:
+   - **Tool**: `AskUserQuestion` with `multiSelect: true`
+   - **Question format**: "请选择 {count} 个角色参与头脑风暴分析（可多选）："
+   - **Options**: Each recommended role with label (role name) and description (relevance rationale)
+   - **User interaction**: Allow user to select multiple roles (typically count roles, but flexible)
+   - **Storage**: Store selections to `session.selected_roles`
+
+**AskUserQuestion Syntax**:
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "请选择 {count} 个角色参与头脑风暴分析（可多选）：",
+    header: "角色选择",
+    multiSelect: true,  // Enable multiple selection
+    options: [
+      {label: "{role-name} ({中文名})", description: "{基于topic的相关性说明}"}
+      // count+2 recommended roles
+    ]
+  }]
+});
+```

 **Role Recommendation Rules**:
 - NO hardcoded keyword-to-role mappings
@@ -104,11 +122,19 @@ FOR each selected role:
     Q: "How resolve conflicts when 2 users edit simultaneously?" (explores edge case)
     Options: [Event Sourcing/Centralized/CRDT] (concrete, explain trade-offs for THIS use case)

-  3. Ask questions in batches (max 4 questions per AskUserQuestion call):
-     - If role has 3-4 questions: Single AskUserQuestion call
+  3. Ask questions via AskUserQuestion tool (max 4 questions per call):
+     - Tool: AskUserQuestion with questions array (1-4 questions)
+     - Each question: multiSelect: false (single-choice)
+     - If role has 3-4 questions: Single AskUserQuestion call with multiple questions
     - Store answers to session.role_decisions[role]
 ```

+**AskUserQuestion Tool Usage**:
+- **Batching**: Maximum 4 questions per AskUserQuestion call
+- **Mode**: `multiSelect: false` for each question (single-choice answers)
+- **Language**: Questions MUST be asked in Chinese (用中文提问)
+- **Format**: Each question includes header (short label), question text, and 2-4 options with descriptions
+
 **Question Batching Rules**:
 - ✅ Each role generates 3-4 questions
 - ✅ AskUserQuestion supports maximum 4 questions per call
@@ -144,14 +170,22 @@ FOR each selected role:
 2. FOR each detected conflict:
   Generate clarification questions referencing SPECIFIC Phase 3 choices

-3. Ask in batches (max 4 questions per AskUserQuestion call):
-   - If conflicts ≤ 4: Single round
-   - If conflicts > 4: Multiple rounds of max 4 questions each
+3. Ask via AskUserQuestion tool in batches (max 4 questions per call):
+   - Tool: AskUserQuestion with questions array (1-4 questions)
+   - Each question: multiSelect: false (single-choice)
+   - If conflicts ≤ 4: Single AskUserQuestion call
+   - If conflicts > 4: Multiple AskUserQuestion calls (max 4 questions each)
   - Store answers to session.cross_role_decisions

 4. If NO conflicts: Skip Phase 4 (inform user)
 ```

+**AskUserQuestion Tool Usage**:
+- **Batching**: Maximum 4 questions per AskUserQuestion call
+- **Mode**: `multiSelect: false` for each question (single-choice answers)
+- **Language**: Questions in Chinese (用中文提问)
+- **Multiple rounds**: If conflicts > 4, call AskUserQuestion multiple times sequentially
+
 **Batching Rules**:
 - ✅ Maximum 4 clarification questions per AskUserQuestion call
 - ✅ Multiple rounds if more than 4 conflicts detected
@@ -219,35 +253,90 @@ FOR each selected role:
 | D-003+ | [Role] | [Q] | [A] | 3 | [Why] |
 ```

-## Question Generation Guidelines
+## AskUserQuestion Tool Reference

-### Core Principle
-**Dynamic Generation from Topic**: Extract keywords → Map to roles → Generate task-specific questions
-
-**Process**:
-1. **Phase 1**: Extract challenges from topic → Generate questions about challenges (NOT "Project type?")
-2. **Phase 3**: Map challenges to role expertise → Generate questions addressing role's challenge solution
-3. **Phase 4**: Analyze Phase 3 answers → Detect conflicts → Generate resolution questions
-
-**Anti-Pattern**:
+### Syntax Structure
 ```javascript
-
-// ✅ CORRECT: Dynamic generation
-function generate(role, challenges) {
-  return challenges.map(c => mapChallengeToRoleQuestion(c, role, topic));
-}
+AskUserQuestion({
+  questions: [
+    {
+      question: "{动态生成的问题文本}",
+      header: "{短标签,最多12字符}",
+      multiSelect: false,  // Phase 1,3,4: false | Phase 2: true
+      options: [
+        {label: "{选项标签}", description: "{选项说明}"},
+        // 2-4 options per question
+      ]
+    }
+    // Maximum 4 questions per call
+  ]
+});
 ```

-**Quality Rules**:
- ✅ ALL questions MUST be in Chinese (所有问题必须用中文)
- ✅ Reference topic keywords in every question
- ✅ Options are concrete technical choices (not abstract categories)
- ✅ Descriptions explain relevance to topic
- ❌ Generic questions that apply to any project
+### Usage Rules
+- **Maximum**: 4 questions per AskUserQuestion call
+- **Language**: Questions in Chinese (用中文提问)
+- **multiSelect**:
+  - `false` (Phase 1, 3, 4): Single-choice
+  - `true` (Phase 2): Multiple role selection
+- **Options**: 2-4 options with label + description
+- **Multiple rounds**: Call tool multiple times if > 4 questions needed

-**Examples** (Topic: "real-time collaboration, 100 users"):
- ❌ Generic: "Architecture style?" → [Microservices/Monolith/Hybrid]
- ✅ Task-specific: "State sync for 100+ real-time users?" → [Event Sourcing/Centralized/CRDT]
+## Question Generation Guidelines
+
+### Core Principle: Developer-Facing Questions with User Context
+
+**Target Audience**: 开发者（理解技术但需要从用户需求出发）
+
+**Generation Philosophy**:
+1. **Phase 1**: 用户场景、业务约束、优先级（建立上下文）
+2. **Phase 2**: 基于话题分析的智能角色推荐（非关键词映射）
+3. **Phase 3**: 业务需求 + 技术选型（需求驱动的技术决策）
+4. **Phase 4**: 技术冲突的业务权衡（帮助开发者理解影响）
+
+### Question Quality Rules
+
+**Balanced Question Pattern** (需求 → 技术):
+```
+问题结构：[用户场景/业务需求] + [技术关注点]
+选项格式：[技术方案简称] + [业务影响说明]
+```
+
+**Phase 1 Focus**:
+- 用户使用场景（谁用？怎么用？多频繁？）
+- 业务约束（预算、时间、团队、合规）
+- 成功标准（性能指标、用户体验目标）
+- 优先级排序（MVP vs 长期规划）
+
+**Phase 3 Focus**:
+- 业务需求驱动的技术问题
+- 技术选项带业务影响说明
+- 包含量化指标（并发数、延迟、可用性）
+
+**Phase 4 Focus**:
+- 技术冲突的业务权衡
+- 帮助开发者理解不同选择的影响
+
+**Question Structure**:
+```
+[业务场景/需求前提] + [技术关注点]
+```
+
+**Option Structure**:
+```
+标签：[技术方案简称] + (业务特征)
+说明：[业务影响] + [技术权衡]
+```
+
+**MUST Include**:
+- 业务场景作为问题前提
+- 技术选项的业务影响说明
+- 量化指标和约束条件
+
+**MUST Avoid**:
+- 纯技术选型无业务上下文
+- 过度抽象的用户体验问题
+- 脱离话题的通用架构问题

 ## Validation Checklist

--- a/.claude/commands/workflow/brainstorm/auto-parallel.md
+++ b/.claude/commands/workflow/brainstorm/auto-parallel.md
@@ -23,37 +23,26 @@ allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*

 **⚠️ User Intent Preservation**: Topic description is stored in session metadata as authoritative reference throughout entire brainstorming workflow and plan generation.

-## Role Selection Logic
- **Technical & Architecture**: `architecture|system|performance|database|security` → system-architect, data-architect, security-expert, subject-matter-expert
- **API & Backend**: `api|endpoint|rest|graphql|backend|interface|contract|service` → api-designer, system-architect, data-architect
- **Product & UX**: `user|ui|ux|interface|design|product|feature|experience` → ui-designer, user-researcher, product-manager, ux-expert, product-owner
- **Business & Process**: `business|process|workflow|cost|innovation|testing` → business-analyst, innovation-lead, test-strategist
- **Agile & Delivery**: `agile|sprint|scrum|team|collaboration|delivery` → scrum-master, product-owner
- **Domain Expertise**: `domain|standard|compliance|expertise|regulation` → subject-matter-expert
- **Multi-role**: Complex topics automatically select N complementary roles (N specified by --count, default 3)
- **Default**: `product-manager` if no clear match
- **Count Parameter**: `--count N` determines number of roles to auto-select (default: 3, max: 9)
+## Role Selection Delegation
+- **Role selection**: Fully delegated to artifacts command (intelligent recommendation + user selection)
+- **Count parameter**: `--count N` passed to artifacts command (default: 3, max: 9)
+- **Available roles**: Defined in artifacts command specification
+- **Selection mechanism**: artifacts analyzes topic, recommends count+2 roles, user selects via multiSelect

-**Template Loading**: `bash($(cat "~/.claude/workflows/cli-templates/planning-roles/<role-name>.md"))`
+**Template Loading**: Handled by individual role agents during parallel execution
 **Template Source**: `.claude/workflows/cli-templates/planning-roles/`
-**Available Roles**: api-designer, data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
-
-**Example**:
-```bash
-bash($(cat "~/.claude/workflows/cli-templates/planning-roles/system-architect.md"))
-bash($(cat "~/.claude/workflows/cli-templates/planning-roles/ui-designer.md"))
-```

 ## Core Workflow

 ### Structured Topic Processing → Role Analysis → Synthesis
 The command follows a structured three-phase approach with dedicated document types:

-**Phase 1: Framework Generation** ⚠️ COMMAND EXECUTION
- **Role selection**: Auto-select N roles based on topic keywords and --count parameter (default: 3, see Role Selection Logic)
- **Call artifacts command**: Execute `/workflow:brainstorm:artifacts "{topic}" --roles "{role1,role2,...,roleN}"` using SlashCommand tool
- **Role-specific framework**: Generate framework with sections tailored to selected roles
- **⚠️ User intent storage**: Topic saved in workflow-session.json as primary reference for all downstream phases
+**Phase 1: Interactive Framework Generation** ⚠️ COMMAND EXECUTION
+- **Delegate to artifacts**: Execute `/workflow:brainstorm:artifacts "{topic}" --count N` using SlashCommand tool
+- **Role selection**: artifacts command handles intelligent recommendation and user selection
+- **Interactive flow**: artifacts executes Phase 1-5 (topic analysis, role recommendation, role questions, conflict resolution, guidance generation)
+- **Output**: guidance-specification.md with confirmed decisions and selected_roles stored in session
+- **⚠️ User intent storage**: Topic and all decisions saved in workflow-session.json as primary reference

 **Phase 2: Role Analysis Execution** ⚠️ PARALLEL AGENT ANALYSIS
 - **Parallel execution**: Multiple roles execute simultaneously for faster completion
@@ -73,25 +62,20 @@ The command follows a structured three-phase approach with dedicated document ty
 Auto command coordinates independent specialized commands:

 **Command Sequence**:
-1. **Role Selection**: Auto-select N relevant roles based on topic keywords and --count parameter (default: 3)
-2. **Generate Role-Specific Framework**: Use SlashCommand to execute `/workflow:brainstorm:artifacts "{topic}" --roles "{role1,role2,...,roleN}"` (stores user intent in session)
-3. **Parallel Role Analysis**: Execute selected role agents in parallel, each reading their specific framework section
-4. **Generate Synthesis**: Use SlashCommand to execute `/workflow:brainstorm:synthesis` (loads user intent from session as primary reference)
+1. **Parse Parameters**: Extract --count N from user input (default: 3)
+2. **Interactive Framework Generation**: Use SlashCommand to execute `/workflow:brainstorm:artifacts "{topic}" --count N`
+   - artifacts handles: topic analysis, role recommendation, user selection, role questions, conflict resolution
+   - Output: guidance-specification.md + session with selected_roles
+3. **Load Selected Roles**: Read selected_roles from workflow-session.json (generated by artifacts)
+4. **Parallel Role Analysis**: Execute selected role agents in parallel, each reading guidance-specification.md
+5. **Generate Synthesis**: Use SlashCommand to execute `/workflow:brainstorm:synthesis`

 **SlashCommand Integration**:
-1. **artifacts command**: Called via SlashCommand tool with `--roles` parameter for role-specific framework generation
-2. **role agents**: Each agent reads its dedicated section in the role-specific framework
-3. **synthesis command**: Called via SlashCommand tool for final integration with role-targeted insights
+1. **artifacts command**: Called via SlashCommand tool with `--count N` parameter for interactive framework generation
+2. **role agents**: Each agent reads guidance-specification.md for topic framework
+3. **synthesis command**: Called via SlashCommand tool for final integration
 4. **Command coordination**: SlashCommand handles execution and validation

-**Role Selection Logic**:
- **Technical**: `architecture|system|performance|database` → system-architect, data-architect, subject-matter-expert
- **API & Backend**: `api|endpoint|rest|graphql|backend|interface|contract|service` → api-designer, system-architect, data-architect
- **Product & UX**: `user|ui|ux|interface|design|product|feature|experience` → ui-designer, ux-expert, product-manager, product-owner
- **Agile & Delivery**: `agile|sprint|scrum|team|collaboration|delivery` → scrum-master, product-owner
- **Domain Expertise**: `domain|standard|compliance|expertise|regulation` → subject-matter-expert
- **Auto-select**: N most relevant roles based on topic analysis (N from --count parameter, default: 3)
-
 ### Parameter Parsing

 **Count Parameter Handling**:
@@ -105,14 +89,17 @@ IF user_input CONTAINS "--count":
 ELSE:
    count_value = 3  # Default to 3 roles
 END IF
+
+# Pass to artifacts command
+EXECUTE: /workflow:brainstorm:artifacts "{topic}" --count {count_value}
 ```

-**Role Selection with Count**:
-1. **Analyze topic keywords**: Identify relevant role categories
-2. **Rank roles by relevance**: Score based on keyword matches
-3. **Select top N roles**: Pick N most relevant roles (N = count_value)
-4. **Ensure diversity**: Balance across different expertise areas
-5. **Minimum guarantee**: Always include at least one role (default to product-manager if no matches)
+**Role Selection Mechanism** (delegated to artifacts):
+1. **artifacts analyzes topic**: Extract keywords and challenges
+2. **artifacts recommends roles**: Intelligent recommendation of count+2 roles
+3. **User selects**: multiSelect from recommended roles
+4. **Session stores**: selected_roles saved to workflow-session.json
+5. **auto-parallel reads**: Load selected_roles for parallel execution

 ### Simplified Processing Standards

@@ -124,7 +111,7 @@ END IF
 5. **TodoWrite control** - Progress tracking throughout all phases

 **Implementation Rules**:
- **Role count**: N roles auto-selected based on --count parameter (default: 3, max: 9) and keyword mapping
+- **Role count**: N roles selected interactively via artifacts command (default: 3, max: 9)
 - **No upfront validation**: Agents handle their own context requirements
 - **Parallel execution**: Each agent operates concurrently without dependencies
 - **Synthesis at end**: Integration only after all agents complete
@@ -146,9 +133,15 @@ END IF

 ## Document Generation

-**Command Coordination Workflow**: artifacts → parallel role analysis → synthesis
+**Command Coordination Workflow**:
+1. artifacts (interactive: topic analysis → role selection → guidance generation)
+2. parallel role analysis (agents read guidance-specification.md)
+3. synthesis (integrates role analyses)

-**Output Structure**: Coordinated commands generate framework, role analyses, and synthesis documents as defined in their respective command specifications.
+**Output Structure**:
+- artifacts: guidance-specification.md (confirmed decisions + selected_roles)
+- role agents: role-specific analysis.md files
+- synthesis: synthesis-specification.md (integrated analysis)


 ## Agent Prompt Templates
@@ -258,14 +251,19 @@ TodoWrite({
      activeForm: "Initializing brainstorming session"
    },
    {
-      content: "Parse --count parameter and select N roles based on topic keyword analysis",
+      content: "Parse --count parameter from user input",
      status: "pending",
-      activeForm: "Parsing parameters and selecting roles for brainstorming"
+      activeForm: "Parsing count parameter"
    },
    {
-      content: "Execute artifacts command with selected roles for role-specific framework",
+      content: "Execute artifacts command for interactive framework generation (role selection + guidance)",
      status: "pending",
-      activeForm: "Generating role-specific topic framework"
+      activeForm: "Executing artifacts command for interactive framework"
+    },
+    {
+      content: "Load selected_roles from workflow-session.json (generated by artifacts)",
+      status: "pending",
+      activeForm: "Loading selected roles from session"
    },
    {
      content: "Execute [role-1] analysis [conceptual-planning-agent] [FLOW_CONTROL] addressing framework",
@@ -296,13 +294,18 @@ TodoWrite({
  todos: [
    {
      content: "Initialize brainstorming session and detect active sessions",
-      status: "completed",  // Mark completed preprocessing
+      status: "completed",
      activeForm: "Initializing brainstorming session"
    },
    {
-      content: "Select roles for topic analysis and create workflow-session.json",
-      status: "in_progress",  // Mark current task as in_progress
-      activeForm: "Selecting roles and creating session metadata"
+      content: "Parse --count parameter from user input",
+      status: "completed",
+      activeForm: "Parsing count parameter"
+    },
+    {
+      content: "Execute artifacts command for interactive framework generation (role selection + guidance)",
+      status: "in_progress",
+      activeForm: "Executing artifacts command for interactive framework"
    },
    // ... other tasks remain pending
  ]