catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-15 02:42:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add quality standards and team command design patterns documentation

Browse Source 
- Introduced a new quality standards document outlining assessment criteria for team command .md files, including completeness, pattern compliance, integration, and consistency dimensions.
- Established quality gates and issue classification for errors, warnings, and informational notes.
- Created a comprehensive team command design patterns document detailing infrastructure and collaboration patterns, including message bus integration, YAML front matter requirements, task lifecycle, five-phase execution structure, and error handling.
- Included a pattern selection guide for collaboration scenarios to enhance team interaction models.
This commit is contained in:
catlog22
2026-02-13 23:39:06 +08:00
parent 5ad7a954d4
commit cdb240d2c2
61 changed files with 5181 additions and 14525 deletions
Download Patch File Download Diff File Expand all files Collapse all files

381
.claude/skills/brainstorm/SKILL.md Normal file
View File

@@ -0,0 +1,381 @@
---
name: brainstorm
description: Unified brainstorming skill with dual-mode operation - auto pipeline and single role analysis. Triggers on "brainstorm", "头脑风暴".
allowed-tools: Skill(*), Task(conceptual-planning-agent, context-search-agent), AskUserQuestion(*), TodoWrite(*), Read(*), Write(*), Edit(*), Glob(*), Bash(*)
---
# Brainstorm
Unified brainstorming skill combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis into a single entry point with two operational modes.
## Architecture Overview
```
┌─────────────────────────────────────────────────────────────┐
│ /brainstorm │
│ Unified Entry Point + Interactive Routing │
└───────────────────────┬─────────────────────────────────────┘
│
┌─────────┴─────────┐
↓ ↓
┌─────────────────┐ ┌──────────────────┐
│ Auto Mode │ │ Single Role Mode │
│ (自动模式) │ │ (单角色分析模式) │
└────────┬────────┘ └────────┬─────────┘
│ │
┌────────┼────────┐ │
↓ ↓ ↓ ↓
Phase 2 Phase 3 Phase 4 Phase 3
Artifacts N×Role Synthesis 1×Role
(7步) Analysis (8步) Analysis
并行 (4步)
```
**Data Flow**:
```
Auto Mode:
Phase 2 (artifacts) → guidance-specification.md + selected_roles[]
→ Phase 3 (N × role-analysis) → {role}/analysis*.md
→ Phase 4 (synthesis) → feature-specs/ + feature-index.json
Single Role Mode:
Phase 3 (1 × role-analysis) → {role}/analysis*.md
```
## Key Design Principles
1. **Dual-Mode Routing**: Interactive mode selection via AskUserQuestion, with parameter-based auto-detection
2. **Progressive Phase Loading**: Phase files loaded on-demand via `Ref:` markers, not all at once
3. **Task Attachment/Collapse**: Sub-tasks attached during phase execution, collapsed after completion
4. **Session Continuity**: All phases share session state via workflow-session.json
5. **Auto-Continue Execution**: Phases chain automatically without user intervention between them
## Auto Mode
When `--yes` or `-y`: Auto-select auto mode, skip interactive routing question, auto-select recommended roles, skip all clarification questions, use default answers.
## Execution Flow
### Phase 1: Mode Detection & Interactive Routing
Ref: phases/01-mode-routing.md
Parse arguments, detect mode from flags/parameters, or ask user via AskUserQuestion.
**Mode Detection Rules**:
1. If `--yes` or `-y` flag present → **Auto Mode** (no question asked)
2. If first arg matches a known role name → **Single Role Mode** (no question asked)
3. If `--session` flag present without role name → **Ask user**
4. Otherwise → **Ask user via AskUserQuestion**
**Output**: `execution_mode` ("auto" | "single-role"), parsed parameters
---
### Auto Mode Execution (execution_mode = "auto")
#### Phase 2: Interactive Framework Generation
Ref: phases/02-artifacts.md
Seven-phase interactive workflow: Context collection → Topic analysis → Role selection → Role questions → Conflict resolution → Final check → Generate specification.
**Input**: topic description, --count N, --yes flag
**Output**: guidance-specification.md, workflow-session.json (selected_roles[], session_id)
**TodoWrite**: Attach 7 sub-tasks (Phase 0-5), execute sequentially, collapse on completion.
#### Phase 3: Parallel Role Analysis
Ref: phases/03-role-analysis.md
Execute role analysis for EACH selected role in parallel.
**Input**: selected_roles[] from Phase 2, session_id, guidance-specification.md
**Output**: {role}/analysis*.md for each role
**Parallel Execution**: Launch N role-analysis calls simultaneously (one message with multiple Skill invokes). Each role with `--skip-questions` flag.
For ui-designer: append `--style-skill {package}` if provided.
**TodoWrite**: Attach N parallel sub-tasks, execute concurrently, collapse on completion.
#### Phase 4: Synthesis Integration
Ref: phases/04-synthesis.md
Eight-phase cross-role synthesis: Discovery → File discovery → Cross-role analysis → User interaction → Document updates → Feature spec generation → Feature index → Finalization.
**Input**: session_id from Phase 2, all role analysis files from Phase 3
**Output**: Updated analyses, feature-specs/, feature-index.json
**TodoWrite**: Attach synthesis sub-tasks, execute sequentially, collapse on completion.
---
### Single Role Mode Execution (execution_mode = "single-role")
#### Phase 3: Single Role Analysis
Ref: phases/03-role-analysis.md
Execute role analysis for ONE specified role with optional interactive context gathering.
**Input**: role_name, --session, --update, --include-questions, --skip-questions, --style-skill
**Output**: {role}/analysis*.md
**TodoWrite**: Attach 4 sub-tasks (Detection → Context → Agent → Validation), execute sequentially.
---
**Phase Reference Documents** (read on-demand when phase executes):
| Phase | Document | Purpose | Used By |
|-------|----------|---------|---------|
| 1 | [phases/01-mode-routing.md](phases/01-mode-routing.md) | Parameter parsing, mode detection, interactive routing | Both modes |
| 2 | [phases/02-artifacts.md](phases/02-artifacts.md) | Interactive framework generation (7 phases) | Auto mode only |
| 3 | [phases/03-role-analysis.md](phases/03-role-analysis.md) | Role-specific analysis generation | Both modes |
| 4 | [phases/04-synthesis.md](phases/04-synthesis.md) | Cross-role synthesis and feature specs | Auto mode only |
## Core Rules
1. **Start with Mode Detection**: First action is Phase 1 (parse args + detect mode)
2. **Interactive Routing**: If mode cannot be determined from args, ASK user via AskUserQuestion
3. **No Preliminary Analysis**: Do not analyze topic before Phase 2 - artifacts handles all analysis
4. **Parse Every Output**: Extract selected_roles from workflow-session.json after Phase 2
5. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
6. **Task Attachment Model**: Skill and Task executes attach sub-tasks to current workflow
7. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow in auto mode. After executing all attached tasks, immediately collapse them and execute next phase
8. **Parallel Execution**: Auto mode Phase 3 attaches multiple agent tasks simultaneously for concurrent execution
9. **Single Role Independence**: Single role mode operates independently without requiring artifacts or synthesis
## Input Processing
### Parameter Parsing
```javascript
// Parse from user input (argument string)
const args = parseArguments(user_input);
// Flags
const auto_yes = args.includes('--yes') || args.includes('-y');
const count = extractFlag(args, '--count', 3); // default 3, max 9
const session_id = extractFlag(args, '--session', null);
const update_mode = args.includes('--update');
const include_questions = args.includes('--include-questions');
const skip_questions = args.includes('--skip-questions');
const style_skill = extractFlag(args, '--style-skill', null);
// Role detection
const VALID_ROLES = [
'data-architect', 'product-manager', 'product-owner', 'scrum-master',
'subject-matter-expert', 'system-architect', 'test-strategist',
'ui-designer', 'ux-expert'
];
const first_arg = args[0]; // first non-flag argument
const is_role = VALID_ROLES.includes(first_arg);
// Mode detection
if (auto_yes) {
execution_mode = 'auto';
topic = extractTopic(args);
} else if (is_role) {
execution_mode = 'single-role';
role_name = first_arg;
} else {
execution_mode = null; // Ask user
topic = extractTopic(args);
}
```
### Usage Examples
```bash
# Auto mode - full pipeline
/brainstorm "Build real-time collaboration platform" --count 3
/brainstorm -y "GOAL: Build platform SCOPE: 100 users" --count 5
/brainstorm "Design payment system" --style-skill material-design
# Single role mode - individual analysis
/brainstorm system-architect --session WFS-xxx
/brainstorm ux-expert --include-questions
/brainstorm ui-designer --session WFS-xxx --update --style-skill material-design
/brainstorm product-manager --skip-questions
# Ambiguous - will ask interactively
/brainstorm --session WFS-xxx
/brainstorm
```
## Data Flow
```
Phase 1 (Mode Routing):
Input: user arguments
Output: execution_mode, parsed_params
↓
┌───────┴───────┐
Auto Single Role
↓ ↓
Phase 2: Phase 3:
Input: topic, count, auto_yes
Output: session_id ─────────────→ Input: role_name, session_id
selected_roles[] skip/include questions
guidance-specification.md style_skill
↓ Output: {role}/analysis*.md
Phase 3:
Input: selected_roles[], session_id
guidance-specification.md
style_skill (for ui-designer)
Output: {role}/analysis*.md (N files)
↓
Phase 4:
Input: session_id, all analysis files
Output: Updated analyses
feature-specs/F-{id}-{slug}.md
feature-index.json
```
## TodoWrite Pattern
### Auto Mode Lifecycle
```
Initial → Phase 1 Mode Routing (completed)
→ Phase 2 Artifacts (in_progress)
→ 7 sub-tasks ATTACHED (Phase 0-5)
→ Execute sequentially
→ Sub-tasks COLLAPSED
→ Phase 3 Parallel Role Analysis (in_progress)
→ N role sub-tasks ATTACHED simultaneously
→ Execute concurrently
→ Sub-tasks COLLAPSED
→ Phase 4 Synthesis (in_progress)
→ 8 sub-tasks ATTACHED
→ Execute sequentially
→ Sub-tasks COLLAPSED
→ All completed
```
### Single Role Mode Lifecycle
```
Initial → Phase 1 Mode Routing (completed)
→ Phase 3 Role Analysis (in_progress)
→ 4 sub-tasks ATTACHED (Detection → Context → Agent → Validation)
→ Execute sequentially
→ Sub-tasks COLLAPSED
→ Completed
```
### Initial TodoWrite (Auto Mode)
```json
[
{"content": "Phase 1: Mode detection and parameter parsing", "status": "in_progress", "activeForm": "Detecting mode"},
{"content": "Phase 2: Interactive Framework Generation", "status": "pending", "activeForm": "Generating framework"},
{"content": "Phase 3: Parallel Role Analysis", "status": "pending", "activeForm": "Executing parallel analysis"},
{"content": "Phase 4: Synthesis Integration", "status": "pending", "activeForm": "Executing synthesis"}
]
```
### Initial TodoWrite (Single Role Mode)
```json
[
{"content": "Phase 1: Mode detection and parameter parsing", "status": "in_progress", "activeForm": "Detecting mode"},
{"content": "Phase 3: Single role analysis for {role_name}", "status": "pending", "activeForm": "Executing role analysis"}
]
```
## Session Management
**⚡ FIRST ACTION**: Check `.workflow/active/` for existing sessions
**Multiple Sessions Support**:
- Different Claude instances can have different brainstorming sessions
- If multiple sessions found, prompt user to select
- If single session found, use it
- If no session exists:
- Auto mode: Create `WFS-[topic-slug]`
- Single role mode: ERROR if no session (must run auto mode first)
**Session Continuity**: All phases share session state via `workflow-session.json`
## Available Roles
| Role ID | Title | Focus Area |
|---------|-------|------------|
| `data-architect` | 数据架构师 | Data models, storage strategies, data flow |
| `product-manager` | 产品经理 | Product strategy, roadmap, prioritization |
| `product-owner` | 产品负责人 | Backlog management, user stories, acceptance criteria |
| `scrum-master` | 敏捷教练 | Process facilitation, impediment removal |
| `subject-matter-expert` | 领域专家 | Domain knowledge, business rules, compliance |
| `system-architect` | 系统架构师 | Technical architecture, scalability, integration |
| `test-strategist` | 测试策略师 | Test strategy, quality assurance |
| `ui-designer` | UI设计师 | Visual design, mockups, design systems |
| `ux-expert` | UX专家 | User research, information architecture, journey |
**Role Selection**: Auto mode → handled by artifacts (Phase 2). Single role mode → user specifies directly.
## Output Structure
```
.workflow/active/WFS-{topic}/
├── workflow-session.json # Session metadata ONLY
├── .process/
│ └── context-package.json # Phase 0 output (auto mode)
└── .brainstorming/
├── guidance-specification.md # Framework (Phase 2, auto mode)
├── feature-index.json # Feature index (Phase 4, auto mode)
├── feature-specs/ # Feature specs (Phase 4, auto mode)
│ ├── F-001-{slug}.md
│ └── F-00N-{slug}.md
├── {role}/
│ ├── {role}-context.md # Interactive Q&A responses
│ ├── analysis.md # Main/index document
│ ├── analysis-cross-cutting.md # Cross-feature (feature_mode)
│ └── analysis-F-{id}-{slug}.md # Per-feature (feature_mode)
└── synthesis-specification.md # Integration (Phase 4, auto mode)
```
## Error Handling
| Error | Recovery | Mode |
|-------|----------|------|
| Invalid role name | Show valid roles list, ask again | Single Role |
| No active session | Auto mode: create new. Single role: error with guidance | Both |
| Role selection failure | Default to product-manager | Auto |
| Agent execution failure | Agent-specific retry with minimal dependencies | Both |
| Template loading issues | Graceful degradation | Both |
| Synthesis conflicts | Highlight disagreements without forced resolution | Auto |
| Context overflow (>100KB) | Read only analysis.md index files | Auto |
**Context Overflow Protection**:
- Per-role limits: < 3000 words main, < 2000 words sub-docs, max 5 sub-docs
- Synthesis protection: If total > 100KB, read only `analysis.md` (not sub-documents)
- Recovery: reduce scope (--count 2) → use --summary-only → manual synthesis
## Coordinator Checklist
**Pre-Phase Actions**:
- [ ] Read Phase document via `Ref:` marker
- [ ] Verify prerequisites (session exists, required files present)
- [ ] Mark phase as `in_progress` in TodoWrite
- [ ] Attach sub-tasks if applicable
**Post-Phase Actions**:
- [ ] Validate phase outputs exist
- [ ] Collapse sub-tasks to phase summary
- [ ] Mark phase as `completed` in TodoWrite
- [ ] Auto-continue to next pending phase (auto mode)
- [ ] Report completion (single role mode)
## Related Commands
**Prerequisites**:
- `/workflow:session:start` - Start a new workflow session (optional, brainstorm creates its own)
**Follow-ups** (after brainstorm completes):
- `/workflow:plan --session {sessionId}` - Generate implementation plan
- `/workflow:brainstorm:synthesis --session {sessionId}` - Run synthesis standalone (if skipped)
## Reference Information
**Template Source**: `~/.ccw/workflows/cli-templates/planning-roles/`
**Style SKILL Packages**: `.claude/skills/style-{package-name}/`

207
.claude/skills/brainstorm/phases/01-mode-routing.md Normal file
View File

@@ -0,0 +1,207 @@
# Phase 1: Mode Detection & Interactive Routing
Parse user arguments, detect execution mode from flags/parameters, or interactively ask the user which mode to use via AskUserQuestion.
## Objective
- Parse all command arguments and flags
- Detect execution mode automatically when possible
- Ask user via AskUserQuestion when mode is ambiguous
- Initialize TodoWrite with mode-appropriate task list
- Route to correct execution path
## Execution
### Step 1.1: Parameter Parsing
```javascript
// Parse from user input (argument string)
const args = parseArguments(user_input);
// Flags
const auto_yes = args.includes('--yes') || args.includes('-y');
const count = extractFlag(args, '--count', 3); // default 3, max 9
if (count > 9) count = 9; // Cap at maximum
const session_id = extractFlag(args, '--session', null);
const update_mode = args.includes('--update');
const include_questions = args.includes('--include-questions');
const skip_questions = args.includes('--skip-questions');
const style_skill = extractFlag(args, '--style-skill', null);
// Role detection
const VALID_ROLES = [
'data-architect', 'product-manager', 'product-owner', 'scrum-master',
'subject-matter-expert', 'system-architect', 'test-strategist',
'ui-designer', 'ux-expert'
];
const first_arg = getFirstNonFlagArg(args);
const is_role = VALID_ROLES.includes(first_arg);
// Topic extraction (everything that's not a flag or role)
const topic = is_role ? null : extractTopic(args);
```
### Step 1.2: Style-Skill Validation
```javascript
if (style_skill) {
const skill_path = `.claude/skills/style-${style_skill}/SKILL.md`;
if (fileExists(skill_path)) {
style_skill_package = style_skill;
style_reference_path = `.workflow/reference_style/${style_skill}`;
// "✓ Style SKILL package found: style-{style_skill}"
} else {
// "⚠ WARNING: Style SKILL package not found: {style_skill}"
style_skill_package = null;
}
} else {
style_skill_package = null;
}
```
### Step 1.3: Mode Detection
```javascript
// Auto-detection rules (ordered by priority)
if (auto_yes) {
// --yes flag explicitly requests auto mode
execution_mode = 'auto';
} else if (is_role) {
// First arg is a valid role name → single role mode
execution_mode = 'single-role';
role_name = first_arg;
} else if (topic && !session_id) {
// Topic provided without session → likely auto mode, but ask
execution_mode = null; // Ask user
} else {
// Ambiguous → ask user
execution_mode = null;
}
```
### Step 1.4: Interactive Mode Selection (when mode is null)
```javascript
if (execution_mode === null) {
AskUserQuestion({
questions: [{
question: "请选择头脑风暴模式",
header: "模式选择",
multiSelect: false,
options: [
{
label: "自动模式 (推荐)",
description: "完整流程：框架生成 → 多角色并行分析 → 跨角色综合。适合新主题的全面分析"
},
{
label: "单角色分析",
description: "为单个角色生成分析文档。适合补充已有会话的角色视角或迭代更新"
}
]
}]
});
// Route based on user selection
if (user_selected === "自动模式 (推荐)") {
execution_mode = 'auto';
} else {
execution_mode = 'single-role';
}
}
```
### Step 1.5: Single Role Mode - Role Selection (if needed)
When entering single-role mode without a role name specified:
```javascript
if (execution_mode === 'single-role' && !role_name) {
// Need to ask which role
AskUserQuestion({
questions: [{
question: "请选择要执行分析的角色",
header: "角色选择",
multiSelect: false,
options: [
{ label: "system-architect", description: "系统架构师 - 技术架构、可扩展性、集成模式" },
{ label: "ux-expert", description: "UX专家 - 用户研究、信息架构、用户旅程" },
{ label: "product-manager", description: "产品经理 - 产品策略、路线图、优先级" },
{ label: "ui-designer", description: "UI设计师 - 视觉设计、高保真原型、设计系统" }
]
}]
});
// Note: If user needs a role not in top 4, they select "Other" and type it
role_name = user_selected;
// Validate role name
if (!VALID_ROLES.includes(role_name)) {
// ERROR with valid roles list
// EXIT
}
}
```
### Step 1.6: Session Detection
```javascript
if (!session_id) {
// Find active sessions
const sessions = Glob('.workflow/active/WFS-*/');
if (sessions.length > 1) {
// Multiple sessions → ask user to select
// Use AskUserQuestion with session list
} else if (sessions.length === 1) {
session_id = extractSessionId(sessions[0]);
} else {
if (execution_mode === 'auto') {
// Will be created by artifacts phase
session_id = null; // artifacts handles creation
} else {
// Single role mode requires existing session
// ERROR: "No active session. Run /brainstorm 'topic' first"
// EXIT
}
}
}
```
### Step 1.7: Initialize TodoWrite
```javascript
if (execution_mode === 'auto') {
TodoWrite({
todos: [
{ content: "Phase 1: Mode detection and parameter parsing", status: "completed", activeForm: "Detecting mode" },
{ content: "Phase 2: Interactive Framework Generation", status: "pending", activeForm: "Generating framework" },
{ content: "Phase 3: Parallel Role Analysis", status: "pending", activeForm: "Executing parallel analysis" },
{ content: "Phase 4: Synthesis Integration", status: "pending", activeForm: "Executing synthesis" }
]
});
} else {
TodoWrite({
todos: [
{ content: "Phase 1: Mode detection and parameter parsing", status: "completed", activeForm: "Detecting mode" },
{ content: `Phase 3: ${role_name} analysis`, status: "pending", activeForm: `Executing ${role_name} analysis` }
]
});
}
```
## Output
- **Variable**: `execution_mode` ("auto" | "single-role")
- **Variable**: `role_name` (single-role mode only)
- **Variable**: `topic` (auto mode only)
- **Variable**: `session_id` (may be null for auto mode - artifacts creates it)
- **Variable**: `count` (auto mode, default 3)
- **Variable**: `auto_yes` (boolean)
- **Variable**: `style_skill_package` (optional)
- **Variable**: `update_mode`, `include_questions`, `skip_questions` (single-role flags)
- **TodoWrite**: Phase 1 completed, subsequent phases pending
## Next Phase
Return to orchestrator:
- If `execution_mode === 'auto'` → Continue to [Phase 2: Artifacts](02-artifacts.md)
- If `execution_mode === 'single-role'` → Continue to [Phase 3: Role Analysis](03-role-analysis.md)

457
.claude/skills/brainstorm/phases/02-artifacts.md Normal file
View File

@@ -0,0 +1,457 @@
# Phase 2: Interactive Framework Generation (Artifacts)
Seven-phase interactive workflow generating confirmed guidance specification through role-based analysis and synthesis. This phase handles all user interaction for topic exploration, role selection, and decision gathering.
## Objective
- Collect project context automatically (Phase 0)
- Analyze topic and extract keywords/challenges (Phase 1)
- Select roles via intelligent recommendation + user confirmation (Phase 2)
- Generate deep role-specific questions (Phase 3)
- Resolve cross-role conflicts (Phase 4)
- Final clarification and feature decomposition (Phase 4.5)
- Generate declarative guidance-specification.md (Phase 5)
## Auto Mode
When `--yes` or `-y`: Auto-select recommended roles, skip all clarification questions, use default answers.
## TodoWrite Integration
**TodoWrite Rule**: EXTEND auto-parallel's task list (NOT replace/overwrite)
**When called from auto mode**:
- Find artifacts parent task → Mark "in_progress"
- APPEND sub-tasks (Phase 0-5) → Mark each as completes
- When Phase 5 completes → Mark parent "completed"
- PRESERVE all other auto-parallel tasks
**Standalone Mode**:
```json
[
{"content": "Initialize session", "status": "pending", "activeForm": "Initializing"},
{"content": "Phase 0: Context collection", "status": "pending", "activeForm": "Phase 0"},
{"content": "Phase 1: Topic analysis (2-4 questions)", "status": "pending", "activeForm": "Phase 1"},
{"content": "Phase 2: Role selection", "status": "pending", "activeForm": "Phase 2"},
{"content": "Phase 3: Role questions (per role)", "status": "pending", "activeForm": "Phase 3"},
{"content": "Phase 4: Conflict resolution", "status": "pending", "activeForm": "Phase 4"},
{"content": "Phase 4.5: Final clarification + Feature decomposition", "status": "pending", "activeForm": "Phase 4.5"},
{"content": "Phase 5: Generate specification", "status": "pending", "activeForm": "Phase 5"}
]
```
## Execution
### Session Management
- Check `.workflow/active/` for existing sessions
- Multiple → Prompt selection | Single → Use it | None → Create `WFS-[topic-slug]`
- Parse `--count N` parameter (default: 3)
- Store decisions in `workflow-session.json`
### Phase 0: Context Collection
**Goal**: Gather project context BEFORE user interaction
**Steps**:
1. Check if `context-package.json` exists → Skip if valid
2. Invoke `context-search-agent` (BRAINSTORM MODE - lightweight)
3. Output: `.workflow/active/WFS-{session-id}/.process/context-package.json`
**Graceful Degradation**: If agent fails, continue to Phase 1 without context
```javascript
Task(
subagent_type="context-search-agent",
run_in_background=false,
description="Gather project context for brainstorm",
prompt=`
Execute context-search-agent in BRAINSTORM MODE (Phase 1-2 only).
Session: ${session_id}
Task: ${task_description}
Output: .workflow/${session_id}/.process/context-package.json
Required fields: metadata, project_context, assets, dependencies, conflict_detection
`
)
```
### Phase 1: Topic Analysis
**Goal**: Extract keywords/challenges enriched by Phase 0 context
**Steps**:
1. Load Phase 0 context (tech_stack, modules, conflict_risk)
2. Deep topic analysis (entities, challenges, constraints, metrics)
3. Generate 2-4 context-aware probing questions
4. AskUserQuestion → Store to `session.intent_context`
**Example**:
```javascript
AskUserQuestion({
questions: [
{
question: "实时协作平台的主要技术挑战？",
header: "核心挑战",
multiSelect: false,
options: [
{ label: "实时数据同步", description: "100+用户同时在线，状态同步复杂度高" },
{ label: "可扩展性架构", description: "用户规模增长时的系统扩展能力" },
{ label: "冲突解决机制", description: "多用户同时编辑的冲突处理策略" }
]
},
{
question: "MVP阶段最关注的指标？",
header: "优先级",
multiSelect: false,
options: [
{ label: "功能完整性", description: "实现所有核心功能" },
{ label: "用户体验", description: "流畅的交互体验和响应速度" },
{ label: "系统稳定性", description: "高可用性和数据一致性" }
]
}
]
})
```
**⚠️ CRITICAL**: Questions MUST reference topic keywords. Generic "Project type?" violates dynamic generation.
### Phase 2: Role Selection
**Goal**: User selects roles from intelligent recommendations
**Available Roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
**Steps**:
1. Analyze Phase 1 keywords → Recommend count+2 roles with rationale
2. AskUserQuestion (multiSelect=true) → Store to `session.selected_roles`
3. If count+2 > 4, split into multiple rounds
**Example**:
```javascript
AskUserQuestion({
questions: [{
question: "请选择 3 个角色参与头脑风暴分析",
header: "角色选择",
multiSelect: true,
options: [
{ label: "system-architect", description: "实时同步架构设计和技术选型" },
{ label: "ui-designer", description: "协作界面用户体验和状态展示" },
{ label: "product-manager", description: "功能优先级和MVP范围决策" },
{ label: "data-architect", description: "数据同步模型和存储方案设计" }
]
}]
})
```
**⚠️ CRITICAL**: User MUST interact. NEVER auto-select without confirmation (unless --yes flag).
### Phase 3: Role-Specific Questions
**Goal**: Generate deep questions mapping role expertise to Phase 1 challenges
**Algorithm**:
1. FOR each selected role:
- Map Phase 1 challenges to role domain
- Generate 3-4 questions (implementation depth, trade-offs, edge cases)
- AskUserQuestion per role → Store to `session.role_decisions[role]`
2. Process roles sequentially (one at a time for clarity)
3. If role needs > 4 questions, split into multiple rounds
**Example** (system-architect):
```javascript
AskUserQuestion({
questions: [
{
question: "100+ 用户实时状态同步方案？",
header: "状态同步",
multiSelect: false,
options: [
{ label: "Event Sourcing", description: "完整事件历史，支持回溯，存储成本高" },
{ label: "集中式状态管理", description: "实现简单，单点瓶颈风险" },
{ label: "CRDT", description: "去中心化，自动合并，学习曲线陡" }
]
},
{
question: "两个用户同时编辑冲突如何解决？",
header: "冲突解决",
multiSelect: false,
options: [
{ label: "自动合并", description: "用户无感知，可能产生意外结果" },
{ label: "手动解决", description: "用户控制，增加交互复杂度" },
{ label: "版本控制", description: "保留历史，需要分支管理" }
]
}
]
})
```
### Phase 4: Conflict Resolution
**Goal**: Resolve ACTUAL conflicts from Phase 3 answers
**Algorithm**:
1. Analyze Phase 3 answers for conflicts:
- Contradictory choices (e.g., "fast iteration" vs "complex Event Sourcing")
- Missing integration (e.g., "Optimistic updates" but no conflict handling)
- Implicit dependencies (e.g., "Live cursors" but no auth defined)
2. Generate clarification questions referencing SPECIFIC Phase 3 choices
3. AskUserQuestion (max 4 per call, multi-round) → Store to `session.cross_role_decisions`
4. If NO conflicts: Skip Phase 4 (inform user: "未检测到跨角色冲突，跳过Phase 4")
**Example**:
```javascript
AskUserQuestion({
questions: [{
question: "CRDT 与 UI 回滚期望冲突，如何解决？\n背景：system-architect选择CRDT，ui-designer期望回滚UI",
header: "架构冲突",
multiSelect: false,
options: [
{ label: "采用 CRDT", description: "保持去中心化，调整UI期望" },
{ label: "显示合并界面", description: "增加用户交互，展示冲突详情" },
{ label: "切换到 OT", description: "支持回滚，增加服务器复杂度" }
]
}]
})
```
### Phase 4.5: Final Clarification
**Purpose**: Ensure no important points missed before generating specification
**Steps**:
1. Ask initial check:
```javascript
AskUserQuestion({
questions: [{
question: "在生成最终规范之前，是否有前面未澄清的重点需要补充？",
header: "补充确认",
multiSelect: false,
options: [
{ label: "无需补充", description: "前面的讨论已经足够完整" },
{ label: "需要补充", description: "还有重要内容需要澄清" }
]
}]
})
```
2. If "需要补充":
- Analyze user's additional points
- Generate progressive questions (not role-bound, interconnected)
- AskUserQuestion (max 4 per round) → Store to `session.additional_decisions`
- Repeat until user confirms completion
3. If "无需补充": Proceed to Feature Decomposition
**Progressive Pattern**: Questions interconnected, each round informs next, continue until resolved.
#### Feature Decomposition
After final clarification, extract implementable feature units from all Phase 1-4 decisions.
**Steps**:
1. Analyze all accumulated decisions (`intent_context` + `role_decisions` + `cross_role_decisions` + `additional_decisions`)
2. Extract candidate features: each must be an independently implementable unit with clear boundaries
3. Generate candidate list (max 8 features) with structured format:
- Feature ID: `F-{3-digit}` (e.g., F-001)
- Name: kebab-case slug (e.g., `real-time-sync`, `user-auth`)
- Description: one-sentence summary of the feature's scope
- Related roles: which roles' decisions drive this feature
- Priority: High / Medium / Low
4. Present candidate list to user for confirmation:
```javascript
AskUserQuestion({
questions: [{
question: "以下是从讨论中提取的功能点清单：\n\nF-001: [name] - [description]\nF-002: [name] - [description]\n...\n\n是否需要调整？",
header: "功能点确认",
multiSelect: false,
options: [
{ label: "确认无误", description: "功能点清单完整且合理，继续生成规范" },
{ label: "需要调整", description: "需要增加、删除或修改功能点" }
]
}]
})
```
5. If "需要调整": Collect adjustments and re-present until user confirms
6. Store confirmed list to `session.feature_list`
**Constraints**:
- Maximum 8 features (if more candidates, merge related items)
- Each feature MUST be independently implementable (no implicit cross-feature dependencies)
- Feature ID format: `F-{3-digit}` (F-001, F-002, ...)
- Feature slug: kebab-case, descriptive of the feature scope
**Granularity Guidelines** (用于验证功能点粒度是否合适):
| Signal | Too Coarse | Just Right | Too Fine |
|--------|-----------|------------|----------|
| 实现范围 | 需要 5+ 个独立模块协同 | 1-3 个模块，边界清晰 | 单个函数或单个 API 端点 |
| 角色关注 | 所有角色都深度涉及 | 2-4 个角色有实质贡献 | 仅 1 个角色关注 |
| 可测试性 | 无法写出清晰的验收标准 | 可定义 3-5 条可测量验收标准 | 验收标准等同于单元测试 |
| 依赖关系 | 与其他功能点循环依赖 | 依赖关系单向且可识别 | 无任何外部依赖（可能遗漏） |
**Quality Validation** (Step 3 提取候选功能点后，逐条验证):
1. **独立性检查**: 该功能点是否可以在其他功能点未完成时独立交付？若否 → 考虑合并或重新划分
2. **完整性检查**: 该功能点是否覆盖了一个用户可感知的完整价值？若否 → 可能太细，考虑合并
3. **粒度均衡检查**: 各功能点之间的复杂度是否大致均衡（最大不超过最小的 3 倍）？若否 → 拆分过大的或合并过小的
4. **边界清晰检查**: 是否能用一句话描述该功能点的输入和输出？若否 → 边界模糊，需重新定义
**Handling Vague Requirements** (当用户需求模糊时的额外步骤):
- 如果 Phase 1-4 的决策不足以支撑功能点分解（如缺少具体业务场景、技术选型未定），在 Step 4 确认时**主动告知用户**哪些功能点的粒度可能不够精确
- 对不确定的功能点标注 `Priority: TBD`，在后续 synthesis 阶段通过跨角色分析进一步明确
- 如果候选功能点 ≤ 2 个，可能是需求过于抽象 → 提示用户补充更多具体场景后再分解
### Phase 5: Generate Specification
**Steps**:
1. Load all decisions: `intent_context` + `selected_roles` + `role_decisions` + `cross_role_decisions` + `additional_decisions` + `feature_list`
2. Transform Q&A to declarative: Questions → Headers, Answers → CONFIRMED/SELECTED statements
3. Generate `guidance-specification.md`
4. Update `workflow-session.json` (metadata only)
5. Validate: No interrogative sentences, all decisions traceable
## Question Guidelines
### Core Principle
**Target**: 开发者（理解技术但需要从用户需求出发）
**Question Structure**: `[业务场景/需求前提] + [技术关注点]`
**Option Structure**: `标签：[技术方案] + 说明：[业务影响] + [技术权衡]`
### Quality Rules
**MUST Include**:
- ✅ All questions in Chinese (用中文提问)
- ✅ 业务场景作为问题前提
- ✅ 技术选项的业务影响说明
- ✅ 量化指标和约束条件
**MUST Avoid**:
- ❌ 纯技术选型无业务上下文
- ❌ 过度抽象的用户体验问题
- ❌ 脱离话题的通用架构问题
### Phase-Specific Requirements
| Phase | Focus | Key Requirements |
|-------|-------|------------------|
| 1 | 意图理解 | Reference topic keywords, 用户场景、业务约束、优先级 |
| 2 | 角色推荐 | Intelligent analysis (NOT keyword mapping), explain relevance |
| 3 | 角色问题 | Reference Phase 1 keywords, concrete options with trade-offs |
| 4 | 冲突解决 | Reference SPECIFIC Phase 3 choices, explain impact on both roles |
### Multi-Round Execution Pattern
```javascript
const BATCH_SIZE = 4;
for (let i = 0; i < allQuestions.length; i += BATCH_SIZE) {
const batch = allQuestions.slice(i, i + BATCH_SIZE);
AskUserQuestion({ questions: batch });
// Store responses before next round
}
```
## Output
### Generated Files
**File**: `.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md`
```markdown
# [Project] - Confirmed Guidance Specification
**Metadata**: [timestamp, type, focus, roles]
## 1. Project Positioning & Goals
**CONFIRMED Objectives**: [from topic + Phase 1]
**CONFIRMED Success Criteria**: [from Phase 1 answers]
## 2-N. [Role] Decisions
### SELECTED Choices
**[Question topic]**: [User's answer]
- **Rationale**: [From option description]
- **Impact**: [Implications]
### Cross-Role Considerations
**[Conflict resolved]**: [Resolution from Phase 4]
- **Affected Roles**: [Roles involved]
## Cross-Role Integration
**CONFIRMED Integration Points**: [API/Data/Auth from multiple roles]
## Risks & Constraints
**Identified Risks**: [From answers] → Mitigation: [Approach]
## Next Steps
**⚠️ Automatic Continuation** (when called from auto mode):
- Auto mode assigns agents for role-specific analysis
- Each selected role gets conceptual-planning-agent
- Agents read this guidance-specification.md for context
## Feature Decomposition
**Constraints**: Max 8 features | Each independently implementable | ID format: F-{3-digit}
| Feature ID | Name | Description | Related Roles | Priority |
|------------|------|-------------|---------------|----------|
| F-001 | [kebab-case-slug] | [One-sentence scope] | [role1, role2] | High/Medium/Low |
| F-002 | [kebab-case-slug] | [One-sentence scope] | [role1] | High/Medium/Low |
## Appendix: Decision Tracking
| Decision ID | Category | Question | Selected | Phase | Rationale |
|-------------|----------|----------|----------|-------|-----------|
| D-001 | Intent | [Q] | [A] | 1 | [Why] |
| D-002 | Roles | [Selected] | [Roles] | 2 | [Why] |
| D-003+ | [Role] | [Q] | [A] | 3 | [Why] |
```
### Session Metadata
```json
{
"session_id": "WFS-{topic-slug}",
"type": "brainstorming",
"topic": "{original user input}",
"selected_roles": ["system-architect", "ui-designer", "product-manager"],
"phase_completed": "artifacts",
"timestamp": "2025-10-24T10:30:00Z",
"count_parameter": 3,
"style_skill_package": null
}
```
**⚠️ Rule**: Session JSON stores ONLY metadata. All guidance content goes to guidance-specification.md.
### Validation Checklist
- ✅ No interrogative sentences (use CONFIRMED/SELECTED)
- ✅ Every decision traceable to user answer
- ✅ Cross-role conflicts resolved or documented
- ✅ Next steps concrete and specific
- ✅ No content duplication between .json and .md
- ✅ Feature Decomposition table present with validated entries
### Governance Rules
- All decisions MUST use CONFIRMED/SELECTED (NO "?" in decision sections)
- Every decision MUST trace to user answer
- Conflicts MUST be resolved (not marked "TBD")
- Next steps MUST be actionable
- Topic preserved as authoritative reference
**CRITICAL**: Guidance is single source of truth for downstream phases. Ambiguity violates governance.
### Update Mechanism
```
IF guidance-specification.md EXISTS:
Prompt: "Regenerate completely / Update sections / Cancel"
ELSE:
Run full Phase 0-5 flow
```
- **TodoWrite**: Mark Phase 2 completed, collapse sub-tasks to summary
## Next Phase
Return to orchestrator, then auto-continue to [Phase 3: Role Analysis](03-role-analysis.md) (auto mode: parallel execution for all selected roles).

718
.claude/skills/brainstorm/phases/03-role-analysis.md Normal file
View File

@@ -0,0 +1,718 @@
# Phase 3: Role Analysis
Unified role-specific analysis generation with interactive context gathering, framework alignment, and incremental update support. Supports both parallel execution (auto mode, N roles simultaneously) and single-role execution.
## Objective
- Validate role name and detect session
- Gather interactive context via role-specific questions (optional)
- Execute conceptual-planning-agent with role template and framework
- Support feature-point output organization when feature list available
- Support incremental updates to existing analyses
- Validate output and update session metadata
## Supported Roles
| Role ID | Title | Focus Area | Context Questions |
|---------|-------|------------|-------------------|
| `ux-expert` | UX专家 | User research, information architecture, user journey | 4 |
| `ui-designer` | UI设计师 | Visual design, high-fidelity mockups, design systems | 4 |
| `system-architect` | 系统架构师 | Technical architecture, scalability, integration patterns | 5 |
| `product-manager` | 产品经理 | Product strategy, roadmap, prioritization | 4 |
| `product-owner` | 产品负责人 | Backlog management, user stories, acceptance criteria | 4 |
| `scrum-master` | 敏捷教练 | Process facilitation, impediment removal, team dynamics | 3 |
| `subject-matter-expert` | 领域专家 | Domain knowledge, business rules, compliance | 4 |
| `data-architect` | 数据架构师 | Data models, storage strategies, data flow | 5 |
| `api-designer` | API设计师 | API contracts, versioning, integration patterns | 4 |
## Execution
### Auto Mode Parallel Execution
When called from auto mode, launch N role-analysis calls simultaneously:
```javascript
// Single message with multiple Skill invokes for parallelism
// For each selected role:
Skill(skill="workflow:brainstorm:role-analysis", args="{role-name} --session {session-id} --skip-questions")
// For ui-designer with style-skill:
Skill(skill="workflow:brainstorm:role-analysis", args="ui-designer --session {session-id} --skip-questions --style-skill {style_skill_package}")
```
**Parallel Safety**: Each role operates independently on its own directory. No cross-agent dependencies.
### Step 3.1: Detection & Validation
**Step 3.1.1: Role Validation**
```bash
VALIDATE role_name IN [
ux-expert, ui-designer, system-architect, product-manager,
product-owner, scrum-master, subject-matter-expert,
data-architect, api-designer
]
IF invalid:
ERROR: "Unknown role: {role_name}. Use one of: ux-expert, ui-designer, ..."
EXIT
```
**Step 3.1.2: Session Detection**
```bash
IF --session PROVIDED:
session_id = --session
brainstorm_dir = .workflow/active/{session_id}/.brainstorming/
ELSE:
FIND .workflow/active/WFS-*/
IF multiple:
PROMPT user to select
ELSE IF single:
USE existing
ELSE:
ERROR: "No active session. Run /brainstorm 'topic' first"
EXIT
VALIDATE brainstorm_dir EXISTS
```
**Step 3.1.3: Framework Detection & Feature List Extraction**
```bash
framework_file = {brainstorm_dir}/guidance-specification.md
IF framework_file EXISTS:
framework_mode = true
LOAD framework_content
# Extract Feature Decomposition table from guidance-specification.md
feature_list = EXTRACT_TABLE(framework_content, "Feature Decomposition")
# feature_list format: [{id: "F-001", slug: "real-time-sync", description: "...", roles: [...], priority: "High"}, ...]
IF feature_list NOT EMPTY:
feature_mode = true # Use feature-point organization for sub-documents
ELSE:
feature_mode = false # Fall back to arbitrary-topic organization
ELSE:
WARN: "No framework found - will create standalone analysis"
framework_mode = false
feature_mode = false
```
**Step 3.1.4: Update Mode Detection**
```bash
existing_analysis = {brainstorm_dir}/{role_name}/analysis*.md
IF --update FLAG OR existing_analysis EXISTS:
update_mode = true
IF --update NOT PROVIDED:
ASK: "Analysis exists. Update or regenerate?"
OPTIONS: ["Incremental update", "Full regenerate", "Cancel"]
ELSE:
update_mode = false
```
### Step 3.2: Interactive Context Gathering
**Trigger Conditions**:
- Default: Always ask unless `--skip-questions` provided
- `--include-questions`: Force context gathering even if analysis exists
- `--skip-questions`: Skip all interactive questions
**Step 3.2.1: Load Role Configuration**
```javascript
const roleConfig = {
'ux-expert': {
title: 'UX专家',
focus_area: 'User research, information architecture, user journey',
question_categories: ['User Intent', 'Requirements', 'UX'],
question_count: 4,
template: '~/.ccw/workflows/cli-templates/planning-roles/ux-expert.md'
},
'ui-designer': {
title: 'UI设计师',
focus_area: 'Visual design, high-fidelity mockups, design systems',
question_categories: ['Requirements', 'UX', 'Feasibility'],
question_count: 4,
template: '~/.ccw/workflows/cli-templates/planning-roles/ui-designer.md'
},
'system-architect': {
title: '系统架构师',
focus_area: 'Technical architecture, scalability, integration patterns',
question_categories: ['Scale & Performance', 'Technical Constraints', 'Architecture Complexity', 'Non-Functional Requirements'],
question_count: 5,
template: '~/.ccw/workflows/cli-templates/planning-roles/system-architect.md'
},
'product-manager': {
title: '产品经理',
focus_area: 'Product strategy, roadmap, prioritization',
question_categories: ['User Intent', 'Requirements', 'Process'],
question_count: 4,
template: '~/.ccw/workflows/cli-templates/planning-roles/product-manager.md'
},
'product-owner': {
title: '产品负责人',
focus_area: 'Backlog management, user stories, acceptance criteria',
question_categories: ['Requirements', 'Decisions', 'Process'],
question_count: 4,
template: '~/.ccw/workflows/cli-templates/planning-roles/product-owner.md'
},
'scrum-master': {
title: '敏捷教练',
focus_area: 'Process facilitation, impediment removal, team dynamics',
question_categories: ['Process', 'Risk', 'Decisions'],
question_count: 3,
template: '~/.ccw/workflows/cli-templates/planning-roles/scrum-master.md'
},
'subject-matter-expert': {
title: '领域专家',
focus_area: 'Domain knowledge, business rules, compliance',
question_categories: ['Requirements', 'Feasibility', 'Terminology'],
question_count: 4,
template: '~/.ccw/workflows/cli-templates/planning-roles/subject-matter-expert.md'
},
'data-architect': {
title: '数据架构师',
focus_area: 'Data models, storage strategies, data flow',
question_categories: ['Architecture', 'Scale & Performance', 'Technical Constraints', 'Feasibility'],
question_count: 5,
template: '~/.ccw/workflows/cli-templates/planning-roles/data-architect.md'
},
'api-designer': {
title: 'API设计师',
focus_area: 'API contracts, versioning, integration patterns',
question_categories: ['Architecture', 'Requirements', 'Feasibility', 'Decisions'],
question_count: 4,
template: '~/.ccw/workflows/cli-templates/planning-roles/api-designer.md'
}
};
config = roleConfig[role_name];
```
**Step 3.2.2: Generate Role-Specific Questions**
**9-Category Taxonomy**:
| Category | Focus | Example Question Pattern |
|----------|-------|--------------------------|
| User Intent | 用户目标 | "该分析的核心目标是什么？" |
| Requirements | 需求细化 | "需求的优先级如何排序？" |
| Architecture | 架构决策 | "技术栈的选择考量？" |
| UX | 用户体验 | "交互复杂度的取舍？" |
| Feasibility | 可行性 | "资源约束下的实现范围？" |
| Risk | 风险管理 | "风险容忍度是多少？" |
| Process | 流程规范 | "开发迭代的节奏？" |
| Decisions | 决策确认 | "冲突的解决方案？" |
| Terminology | 术语统一 | "统一使用哪个术语？" |
| Scale & Performance | 性能扩展 | "预期的负载和性能要求？" |
| Technical Constraints | 技术约束 | "现有技术栈的限制？" |
| Architecture Complexity | 架构复杂度 | "架构的复杂度权衡？" |
| Non-Functional Requirements | 非功能需求 | "可用性和可维护性要求？" |
**Question Generation Algorithm**:
```javascript
async function generateQuestions(role_name, framework_content) {
const config = roleConfig[role_name];
const questions = [];
// Parse framework for keywords
const keywords = extractKeywords(framework_content);
// Generate category-specific questions
for (const category of config.question_categories) {
const question = generateCategoryQuestion(category, keywords, role_name);
questions.push(question);
}
return questions.slice(0, config.question_count);
}
```
**Step 3.2.3: Multi-Round Question Execution**
```javascript
const BATCH_SIZE = 4;
const user_context = {};
for (let i = 0; i < questions.length; i += BATCH_SIZE) {
const batch = questions.slice(i, i + BATCH_SIZE);
const currentRound = Math.floor(i / BATCH_SIZE) + 1;
const totalRounds = Math.ceil(questions.length / BATCH_SIZE);
console.log(`\n[Round ${currentRound}/${totalRounds}] ${config.title} 上下文询问\n`);
AskUserQuestion({
questions: batch.map(q => ({
question: q.question,
header: q.category.substring(0, 12),
multiSelect: false,
options: q.options.map(opt => ({
label: opt.label,
description: opt.description
}))
}))
});
// Store responses before next round
for (const answer of responses) {
user_context[answer.question] = {
answer: answer.selected,
category: answer.category,
timestamp: new Date().toISOString()
};
}
}
// Save context to file
Write(
`${brainstorm_dir}/${role_name}/${role_name}-context.md`,
formatUserContext(user_context)
);
```
**Question Quality Rules**:
**MUST Include**:
- ✅ All questions in Chinese (用中文提问)
- ✅ 业务场景作为问题前提
- ✅ 技术选项的业务影响说明
- ✅ 量化指标和约束条件
**MUST Avoid**:
- ❌ 纯技术选型无业务上下文
- ❌ 过度抽象的通用问题
- ❌ 脱离框架的重复询问
### Step 3.3: Agent Execution
**Step 3.3.1: Load Session Metadata**
```bash
session_metadata = Read(.workflow/active/{session_id}/workflow-session.json)
original_topic = session_metadata.topic
selected_roles = session_metadata.selected_roles
```
**Step 3.3.2: Prepare Agent Context**
```javascript
const agentContext = {
role_name: role_name,
role_config: roleConfig[role_name],
output_location: `${brainstorm_dir}/${role_name}/`,
framework_mode: framework_mode,
feature_mode: feature_mode,
feature_list: feature_mode ? feature_list : null,
framework_path: framework_mode ? `${brainstorm_dir}/guidance-specification.md` : null,
update_mode: update_mode,
user_context: user_context,
original_topic: original_topic,
session_id: session_id
};
```
**Step 3.3.3: Execute Conceptual Planning Agent**
**Framework-Based Analysis** (when guidance-specification.md exists):
```javascript
// Build feature list injection block (only when feature_mode is true)
const featureListBlock = feature_mode ? `
## Feature Point List (from guidance-specification.md Feature Decomposition)
${feature_list.map(f => `- **${f.id}** (${f.slug}): ${f.description} [Priority: ${f.priority}]`).join('\n')}
**IMPORTANT - Feature-Point Output Organization**:
- Generate ONE sub-document per feature: analysis-F-{id}-{slug}.md (e.g., analysis-${feature_list[0].id}-${feature_list[0].slug}.md)
- Generate ONE cross-cutting document: analysis-cross-cutting.md
- analysis.md is a role overview INDEX only (< 1500 words), NOT a full analysis
- Each feature sub-document < 2000 words, cross-cutting < 2000 words
- Total across all files < 15000 words
` : `
## Output Organization (fallback: no feature list available)
- Generate analysis.md as main document (< 3000 words)
- Optionally split into analysis-{slug}.md sub-documents (max 5, < 2000 words each)
- Total < 15000 words
`;
Task(
subagent_type="conceptual-planning-agent",
run_in_background=false,
description=`Generate ${role_name} analysis`,
prompt=`
[FLOW_CONTROL]
Execute ${role_name} analysis for existing topic framework
## Context Loading
ASSIGNED_ROLE: ${role_name}
OUTPUT_LOCATION: ${agentContext.output_location}
ANALYSIS_MODE: ${framework_mode ? "framework_based" : "standalone"}
FEATURE_MODE: ${feature_mode}
UPDATE_MODE: ${update_mode}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(${agentContext.framework_path})
- Output: topic_framework_content
2. **load_role_template**
- Action: Load ${role_name} planning template
- Command: Read(${roleConfig[role_name].template})
- Output: role_template_guidelines
3. **load_session_metadata**
- Action: Load session metadata and user intent
- Command: Read(.workflow/active/${session_id}/workflow-session.json)
- Output: session_context
4. **load_user_context** (if exists)
- Action: Load interactive context responses
- Command: Read(${brainstorm_dir}/${role_name}/${role_name}-context.md)
- Output: user_context_answers
5. **${update_mode ? 'load_existing_analysis' : 'skip'}**
${update_mode ? `
- Action: Load existing analysis for incremental update
- Command: Read(${brainstorm_dir}/${role_name}/analysis.md)
- Output: existing_analysis_content
` : ''}
${featureListBlock}
## Analysis Requirements
**Primary Reference**: Original user prompt from workflow-session.json is authoritative
**Framework Source**: Address all discussion points in guidance-specification.md from ${role_name} perspective
**User Context Integration**: Incorporate interactive Q&A responses into analysis
**Role Focus**: ${roleConfig[role_name].focus_area}
**Template Integration**: Apply role template guidelines within framework structure
${feature_mode ? `**Feature Organization**: Organize analysis by feature points - each feature gets its own sub-document. Cross-cutting concerns go into analysis-cross-cutting.md.` : ''}
## Expected Deliverables
${feature_mode ? `
1. **analysis.md** - Role overview index (< 1500 words): role perspective summary, feature point index with @-references to sub-documents, cross-cutting summary
2. **analysis-cross-cutting.md** - Cross-feature decisions (< 2000 words): architecture decisions, technology choices, shared patterns that span multiple features
3. **analysis-F-{id}-{slug}.md** - One per feature (< 2000 words each): role-specific analysis, recommendations, considerations for that feature
4. **Framework Reference**: @../guidance-specification.md (if framework_mode)
5. **User Context Reference**: @./${role_name}-context.md (if user context exists)
6. **User Intent Alignment**: Validate against session_context
` : `
1. **analysis.md** (main document, optionally with analysis-{slug}.md sub-documents)
2. **Framework Reference**: @../guidance-specification.md (if framework_mode)
3. **User Context Reference**: @./${role_name}-context.md (if user context exists)
4. **User Intent Alignment**: Validate against session_context
`}
## Update Requirements (if UPDATE_MODE)
- **Preserve Structure**: Maintain existing analysis structure
- **Add "Clarifications" Section**: Document new user context with timestamp
- **Merge Insights**: Integrate new perspectives without removing existing content
- **Resolve Conflicts**: If new context contradicts existing analysis, document both and recommend resolution
## Completion Criteria
- Address each discussion point from guidance-specification.md with ${role_name} expertise
- Provide actionable recommendations from ${role_name} perspective within analysis files
- All output files MUST start with "analysis" prefix (no recommendations.md or other naming)
${feature_mode ? `- Each feature from the feature list has a corresponding analysis-F-{id}-{slug}.md file
- analysis-cross-cutting.md exists with cross-feature decisions
- analysis.md serves as index (< 1500 words), NOT a full analysis document` : ''}
- Reference framework document using @ notation for integration
- Update workflow-session.json with completion status
`
);
```
### Step 3.4: Validation & Finalization
**Step 3.4.1: Validate Output**
```bash
VERIFY EXISTS: ${brainstorm_dir}/${role_name}/analysis.md
VERIFY CONTAINS: "@../guidance-specification.md" (if framework_mode)
IF user_context EXISTS:
VERIFY CONTAINS: "@./${role_name}-context.md" OR "## Clarifications" section
```
**Step 3.4.2: Update Session Metadata**
```json
{
"phases": {
"BRAINSTORM": {
"${role_name}": {
"status": "${update_mode ? 'updated' : 'completed'}",
"completed_at": "timestamp",
"framework_addressed": true,
"context_gathered": true,
"output_location": "${brainstorm_dir}/${role_name}/analysis.md",
"update_history": [
{
"timestamp": "ISO8601",
"mode": "${update_mode ? 'incremental' : 'initial'}",
"context_questions": "question_count"
}
]
}
}
}
}
```
**Step 3.4.3: Completion Report**
```markdown
✅ ${roleConfig[role_name].title} Analysis Complete
**Output**: ${brainstorm_dir}/${role_name}/analysis.md
**Mode**: ${update_mode ? 'Incremental Update' : 'New Generation'}
**Framework**: ${framework_mode ? '✓ Aligned' : '✗ Standalone'}
**Context Questions**: ${question_count} answered
${update_mode ? '
**Changes**:
- Added "Clarifications" section with new user context
- Merged new insights into existing sections
- Resolved conflicts with framework alignment
' : ''}
**Next Steps**:
${selected_roles.length > 1 ? `
- Continue with other roles: ${selected_roles.filter(r => r !== role_name).join(', ')}
- Run synthesis: /brainstorm --session ${session_id} (auto mode)
` : `
- Clarify insights: /brainstorm --session ${session_id} (auto mode)
- Generate plan: /workflow:plan --session ${session_id}
`}
```
## Output
### Directory Layout
**Feature-point mode** (when `feature_list` available):
```
.workflow/active/WFS-{session}/.brainstorming/
├── guidance-specification.md
└── {role-name}/
├── {role-name}-context.md # Interactive Q&A responses
├── analysis.md # Role overview INDEX (< 1500 words)
├── analysis-cross-cutting.md # Cross-feature decisions (< 2000 words)
├── analysis-F-001-{slug}.md # Per-feature analysis (< 2000 words)
├── analysis-F-002-{slug}.md
└── analysis-F-00N-{slug}.md # One per feature (max 8)
```
**Fallback mode** (when `feature_list` NOT available):
```
.workflow/active/WFS-{session}/.brainstorming/
├── guidance-specification.md
└── {role-name}/
├── {role-name}-context.md # Interactive Q&A responses
├── analysis.md # Main analysis (REQUIRED)
└── analysis-{slug}.md # Section documents (optional, max 5)
```
### Document Structure Templates
#### Feature-Point Mode: analysis.md (Role Overview Index, < 1500 words)
```markdown
# ${roleConfig[role_name].title} Analysis: [Topic from Framework]
## Framework Reference
**Topic Framework**: @../guidance-specification.md
**Role Focus**: ${roleConfig[role_name].focus_area}
**User Context**: @./${role_name}-context.md
## Role Perspective Overview
[Brief summary of this role's perspective on the overall project]
## Feature Point Index
| Feature | Sub-document | Key Insight |
|---------|-------------|-------------|
| F-001: [name] | @./analysis-F-001-{slug}.md | [One-line summary] |
| F-002: [name] | @./analysis-F-002-{slug}.md | [One-line summary] |
## Cross-Cutting Summary
**Full analysis**: @./analysis-cross-cutting.md
[Brief overview of cross-feature decisions and shared patterns]
---
*Generated by ${role_name} analysis addressing structured framework*
```
#### Feature-Point Mode: analysis-cross-cutting.md (< 2000 words)
```markdown
# Cross-Cutting Analysis: ${roleConfig[role_name].title}
## Architecture Decisions
[Decisions that span multiple features]
## Technology Choices
[Shared technology selections and rationale]
## Shared Patterns
[Common patterns, constraints, and conventions across features]
## ${roleConfig[role_name].title} Recommendations
[Role-wide strategic recommendations]
```
#### Feature-Point Mode: analysis-F-{id}-{slug}.md (< 2000 words each)
```markdown
# Feature ${id}: [Feature Name] - ${roleConfig[role_name].title} Analysis
## Feature Overview
[Role-specific perspective on this feature's scope and goals]
## Analysis
[Detailed role-specific analysis for this feature]
## Recommendations
[Actionable recommendations for this feature from role perspective]
## Dependencies & Risks
[Cross-feature dependencies and risks from role viewpoint]
```
#### Fallback Mode: analysis.md (New Generation)
```markdown
# ${roleConfig[role_name].title} Analysis: [Topic from Framework]
## Framework Reference
**Topic Framework**: @../guidance-specification.md
**Role Focus**: ${roleConfig[role_name].focus_area}
**User Context**: @./${role_name}-context.md
## User Context Summary
**Context Gathered**: ${question_count} questions answered
**Categories**: ${question_categories.join(', ')}
${user_context ? formatContextSummary(user_context) : ''}
## Discussion Points Analysis
[Address each point from guidance-specification.md with ${role_name} expertise]
### Core Requirements (from framework)
[Role-specific perspective on requirements]
### Technical Considerations (from framework)
[Role-specific technical analysis]
### User Experience Factors (from framework)
[Role-specific UX considerations]
### Implementation Challenges (from framework)
[Role-specific challenges and solutions]
### Success Metrics (from framework)
[Role-specific metrics and KPIs]
## ${roleConfig[role_name].title} Specific Recommendations
[Role-specific actionable strategies]
---
*Generated by ${role_name} analysis addressing structured framework*
*Context gathered: ${new Date().toISOString()}*
```
#### Incremental Update Structure
```markdown
# ${roleConfig[role_name].title} Analysis: [Topic]
## Framework Reference
[Existing content preserved]
## Clarifications
### Session ${new Date().toISOString().split('T')[0]}
${Object.entries(user_context).map(([q, a]) => `
- **Q**: ${q} (Category: ${a.category})
**A**: ${a.answer}
`).join('\n')}
## User Context Summary
[Updated with new context]
## Discussion Points Analysis
[Existing content enhanced with new insights]
[Rest of sections updated based on clarifications]
```
### Parameter Combinations
| Scenario | Command | Behavior |
|----------|---------|----------|
| New analysis | `/brainstorm ux-expert` | Generate + ask context questions |
| Quick generation | `/brainstorm ux-expert --skip-questions` | Generate without context |
| Update existing | `/brainstorm ux-expert --update` | Ask clarifications + merge |
| Force questions | `/brainstorm ux-expert --include-questions` | Ask even if exists |
| Specific session | `/brainstorm ux-expert --session WFS-xxx` | Target specific session |
### Quality Assurance
**Required Analysis Elements**:
- [ ] Framework discussion points addressed (if framework_mode)
- [ ] User context integrated (if context gathered)
- [ ] Role template guidelines applied
- [ ] Output files follow naming convention (analysis*.md only)
- [ ] Framework reference using @ notation
- [ ] Session metadata updated
- [ ] Feature-point organization used when feature_list available (if feature_mode)
- [ ] analysis.md is index only (< 1500 words) when in feature_mode
- [ ] analysis-cross-cutting.md exists when in feature_mode
- [ ] One analysis-F-{id}-{slug}.md per feature when in feature_mode
**Context Quality**:
- [ ] Questions in Chinese with business context
- [ ] Options include technical trade-offs
- [ ] Categories aligned with role focus
- [ ] No generic questions unrelated to framework
**Update Quality** (if update_mode):
- [ ] "Clarifications" section added with timestamp
- [ ] New insights merged without content loss
- [ ] Conflicts documented and resolved
- [ ] Framework alignment maintained
- **TodoWrite**: Mark Phase 3 completed (auto mode: collapse N parallel sub-tasks to summary)
## Error Handling
| Error | Recovery |
|-------|----------|
| Invalid role name | Show valid roles list, exit |
| No active session | Error with guidance to run /brainstorm first |
| Missing framework | Warn and generate standalone analysis |
| Agent execution failure | Check error.log, retry with --skip-questions |
## Advanced Usage
### Batch Role Generation (via auto mode)
```bash
# Auto mode handles multiple roles in parallel
/brainstorm "topic" --count 3
# → Internally calls role-analysis for each selected role with --skip-questions
```
### Manual Multi-Role Workflow
```bash
# 1. Create framework
/brainstorm "Build real-time collaboration platform" --count 3
# 2. Generate each role with context
/brainstorm system-architect --include-questions
/brainstorm ui-designer --include-questions
/brainstorm product-manager --include-questions
# 3. Synthesize insights
/brainstorm --session WFS-xxx
```
### Iterative Refinement
```bash
# Initial generation
/brainstorm ux-expert
# User reviews and wants more depth
/brainstorm ux-expert --update --include-questions
# → Asks clarification questions, merges new insights
```
## Next Phase
Return to orchestrator:
- If auto mode → Continue to [Phase 4: Synthesis](04-synthesis.md)
- If single-role mode → Workflow complete, report results

783
.claude/skills/brainstorm/phases/04-synthesis.md Normal file
View File

@@ -0,0 +1,783 @@
# Phase 4: Synthesis Integration
Eight-phase workflow to eliminate ambiguities, enhance conceptual depth, and generate per-feature specifications through cross-role analysis and user clarification.
## Objective
- Discover and validate all role analysis files
- Execute cross-role analysis to identify consensus, conflicts, and gaps
- Present enhancement recommendations and clarification questions to user
- Update role analyses in parallel with enhancements and clarifications
- Generate consolidated feature specifications (feature_mode)
- Generate feature index for downstream consumers (feature_mode)
- Update context package and session metadata
## Auto Mode
When `--yes` or `-y`: Auto-select all enhancements, skip clarification questions, use default answers.
## Quick Reference
### Phase Summary
| Phase | Goal | Executor | Output |
|-------|------|----------|--------|
| 1 | Session detection | Main flow | session_id, brainstorm_dir |
| 2 | File discovery | Main flow | role_analysis_paths |
| 3A | Cross-role analysis | Agent | enhancement_recommendations, feature_conflict_map |
| 4 | User interaction | Main flow + AskUserQuestion | update_plan |
| 5 | Document updates | Parallel agents | Updated analysis*.md |
| 6 | Feature spec generation | Parallel agents | feature-specs/F-{id}-{slug}.md [feature_mode] |
| 6.5 | Feature index generation | Main flow | feature-index.json [feature_mode] |
| 7 | Finalization | Main flow | context-package.json, report |
### AskUserQuestion Pattern
```javascript
// Enhancement selection (multi-select)
AskUserQuestion({
questions: [{
question: "请选择要应用的改进建议",
header: "改进选择",
multiSelect: true,
options: [
{ label: "EP-001: API Contract", description: "添加详细的请求/响应 schema 定义" },
{ label: "EP-002: User Intent", description: "明确用户需求优先级和验收标准" }
]
}]
})
// Clarification questions (single-select, multi-round)
AskUserQuestion({
questions: [
{
question: "MVP 阶段的核心目标是什么？",
header: "用户意图",
multiSelect: false,
options: [
{ label: "快速验证", description: "最小功能集，快速上线获取反馈" },
{ label: "技术壁垒", description: "完善架构，为长期发展打基础" },
{ label: "功能完整", description: "覆盖所有规划功能，延迟上线" }
]
}
]
})
```
## Task Tracking
```json
[
{"content": "Detect session and validate analyses", "status": "pending", "activeForm": "Detecting session"},
{"content": "Discover role analysis file paths", "status": "pending", "activeForm": "Discovering paths"},
{"content": "Execute analysis agent (cross-role analysis + feature conflict map)", "status": "pending", "activeForm": "Executing analysis"},
{"content": "Present enhancements via AskUserQuestion", "status": "pending", "activeForm": "Selecting enhancements"},
{"content": "Clarification questions via AskUserQuestion", "status": "pending", "activeForm": "Clarifying"},
{"content": "Execute parallel update agents", "status": "pending", "activeForm": "Updating documents"},
{"content": "Generate parallel feature specs (feature_mode only)", "status": "pending", "activeForm": "Generating feature specs"},
{"content": "Generate feature-index.json (feature_mode only)", "status": "pending", "activeForm": "Building feature index"},
{"content": "Update context package and metadata", "status": "pending", "activeForm": "Finalizing"}
]
```
## Execution
### Phase 1: Discovery & Validation
1. **Detect Session**: Use `--session` parameter or find `.workflow/active/WFS-*`
2. **Validate Files**:
- `guidance-specification.md` (optional, warn if missing)
- `*/analysis*.md` (required, error if empty)
3. **Load User Intent**: Extract from `workflow-session.json`
4. **Detect Feature Mode**: Check if role analyses use feature-point organization
```javascript
// Feature mode is active when:
// 1. guidance-specification.md contains Feature Decomposition table
// 2. Role directories contain analysis-F-{id}-*.md files
const has_feature_decomposition = guidanceSpecContent &&
guidanceSpecContent.includes('Feature Decomposition');
const has_feature_subdocs = Glob(`${brainstorm_dir}/*/analysis-F-*-*.md`).length > 0;
const feature_mode = has_feature_decomposition && has_feature_subdocs;
// Extract feature_list from guidance-spec if feature_mode
if (feature_mode) {
feature_list = extractFeatureDecompositionTable(guidanceSpecContent);
// feature_list: [{id, slug, description, roles, priority}, ...]
}
```
### Phase 2: Role Discovery & Path Preparation
**Main flow prepares file paths for Agent**:
1. **Discover Analysis Files**:
- Glob: `.workflow/active/WFS-{session}/.brainstorming/*/analysis*.md`
- Supports: analysis.md + analysis-{slug}.md (max 5)
2. **Extract Role Information**:
- `role_analysis_paths`: Relative paths
- `participating_roles`: Role names from directories
3. **Pass to Agent**: session_id, brainstorm_dir, role_analysis_paths, participating_roles
### Phase 3A: Analysis & Enhancement Agent
**Agent executes cross-role analysis**:
**Input Optimization (feature_mode)**: When feature_mode is active, only read `{role}/analysis.md` index files (NOT sub-documents like `analysis-F-{id}-*.md` or `analysis-cross-cutting.md`). This reduces input tokens from ~39K to ~4.5K while preserving the role perspective overview, feature point index, and cross-cutting summary needed for conflict detection.
**Input (fallback mode)**: When feature_mode is NOT active, read all `{role}/analysis*.md` files as before.
```javascript
// Prepare input paths based on mode
const analysis_input_paths = feature_mode
? participating_roles.map(r => `${brainstorm_dir}/${r}/analysis.md`) // Index files only (~4.5K total)
: role_analysis_paths; // All analysis files (fallback)
Task(conceptual-planning-agent, `
## Agent Mission
Analyze role documents, identify conflicts/gaps, generate enhancement recommendations.
${feature_mode ? 'Additionally, generate feature_conflict_map for per-feature consensus/conflicts across roles.' : ''}
## Input
- brainstorm_dir: ${brainstorm_dir}
- analysis_input_paths: ${analysis_input_paths}
- participating_roles: ${participating_roles}
- feature_mode: ${feature_mode}
${feature_mode ? `- guidance_spec_path: ${brainstorm_dir}/guidance-specification.md (read Feature Decomposition section only)` : ''}
## Flow Control Steps
1. load_session_metadata → Read workflow-session.json
2. load_role_analyses → Read analysis files from analysis_input_paths
${feature_mode ? '(INDEX files only - each ~500-800 words with role overview, feature index table, cross-cutting summary)' : '(All analysis files)'}
${feature_mode ? `3. load_feature_decomposition → Read Feature Decomposition table from guidance-specification.md
4. cross_role_analysis → Identify consensus, conflicts, gaps, ambiguities
5. generate_feature_conflict_map → For each feature in Feature Decomposition, extract per-feature consensus/conflicts/cross-references from role index summaries
6. generate_recommendations → Format as EP-001, EP-002, ...` : `3. cross_role_analysis → Identify consensus, conflicts, gaps, ambiguities
4. generate_recommendations → Format as EP-001, EP-002, ...`}
## Output Format
### enhancement_recommendations (always)
[
{
"id": "EP-001",
"title": "API Contract Specification",
"affected_roles": ["system-architect", "api-designer"],
"category": "Architecture",
"current_state": "High-level API descriptions",
"enhancement": "Add detailed contract definitions",
"rationale": "Enables precise implementation",
"priority": "High"
}
]
${feature_mode ? `### feature_conflict_map (feature_mode only)
Bridge artifact from Phase 3A to Phase 6. One entry per feature from Feature Decomposition.
{
"F-001": {
"consensus": [
"All roles agree on real-time sync via WebSocket",
"Event-driven architecture preferred"
],
"conflicts": [
{
"topic": "State management approach",
"views": {
"system-architect": "Server-authoritative with CRDT",
"ux-expert": "Optimistic local-first updates"
},
"resolution": "Hybrid: optimistic local with server reconciliation via CRDT because balances UX responsiveness with data consistency, tradeoff: increased client complexity",
"confidence": "[RESOLVED]",
"applies_when": "Online mode with collaborative editing"
}
],
"cross_refs": [
"F-003 (offline-mode) depends on sync conflict resolution strategy"
]
}
}
**feature_conflict_map Rules**:
- One entry per feature ID from guidance-specification.md Feature Decomposition
- consensus[]: Statements where 2+ roles explicitly agree
- conflicts[]: Disagreements with topic, per-role positions, and suggested resolution
- cross_refs[]: References to other features or cross-cutting docs
- If a feature has no conflicts, set conflicts to empty array
- Keep each entry concise: aim for 100-200 words per feature
**Resolution Quality Requirements**:
1. **Actionable**: resolution must be directly executable. Bad: "需要权衡" → Good: "采用 JWT 无状态认证，RefreshToken 存 HttpOnly Cookie"
2. **Justified**: Explain why. Format: "[方案] because [原因]，tradeoff: [代价]"
3. **Scoped**: If limited scope, mark "Applies when: [条件]"
4. **Confidence**: [RESOLVED] | [SUGGESTED] | [UNRESOLVED]
` : ''}
`)
```
**Phase 3A Output Storage**:
```javascript
// Store enhancement_recommendations for Phase 4
const enhancement_recommendations = agent_output.enhancement_recommendations;
// Store feature_conflict_map for Phase 6 (feature_mode only)
const feature_conflict_map = feature_mode ? agent_output.feature_conflict_map : null;
```
### Phase 4: User Interaction
**All interactions via AskUserQuestion (Chinese questions)**
#### Step 1: Enhancement Selection
```javascript
// If enhancements > 4, split into multiple rounds
const enhancements = [...]; // from Phase 3A
const BATCH_SIZE = 4;
for (let i = 0; i < enhancements.length; i += BATCH_SIZE) {
const batch = enhancements.slice(i, i + BATCH_SIZE);
AskUserQuestion({
questions: [{
question: `请选择要应用的改进建议 (第${Math.floor(i/BATCH_SIZE)+1}轮)`,
header: "改进选择",
multiSelect: true,
options: batch.map(ep => ({
label: `${ep.id}: ${ep.title}`,
description: `影响: ${ep.affected_roles.join(', ')} | ${ep.enhancement}`
}))
}]
})
// Store selections before next round
}
// User can also skip: provide "跳过" option
```
#### Step 2: Clarification Questions
```javascript
// Generate questions based on 9-category taxonomy scan
// Categories: User Intent, Requirements, Architecture, UX, Feasibility, Risk, Process, Decisions, Terminology
const clarifications = [...]; // from analysis
const BATCH_SIZE = 4;
for (let i = 0; i < clarifications.length; i += BATCH_SIZE) {
const batch = clarifications.slice(i, i + BATCH_SIZE);
const currentRound = Math.floor(i / BATCH_SIZE) + 1;
const totalRounds = Math.ceil(clarifications.length / BATCH_SIZE);
AskUserQuestion({
questions: batch.map(q => ({
question: q.question,
header: q.category.substring(0, 12),
multiSelect: false,
options: q.options.map(opt => ({
label: opt.label,
description: opt.description
}))
}))
})
// Store answers before next round
}
```
### Question Guidelines
**Target**: 开发者（理解技术但需要从用户需求出发）
**Question Structure**: `[跨角色分析发现] + [需要澄清的决策点]`
**Option Structure**: `标签：[具体方案] + 说明：[业务影响] + [技术权衡]`
**9-Category Taxonomy**:
| Category | Focus | Example Question Pattern |
|----------|-------|--------------------------|
| User Intent | 用户目标 | "MVP阶段核心目标？" + 验证/壁垒/完整性 |
| Requirements | 需求细化 | "功能优先级如何排序？" + 核心/增强/可选 |
| Architecture | 架构决策 | "技术栈选择考量？" + 熟悉度/先进性/成熟度 |
| UX | 用户体验 | "交互复杂度取舍？" + 简洁/丰富/渐进 |
| Feasibility | 可行性 | "资源约束下的范围？" + 最小/标准/完整 |
| Risk | 风险管理 | "风险容忍度？" + 保守/平衡/激进 |
| Process | 流程规范 | "迭代节奏？" + 快速/稳定/灵活 |
| Decisions | 决策确认 | "冲突解决方案？" + 方案A/方案B/折中 |
| Terminology | 术语统一 | "统一使用哪个术语？" + 术语A/术语B |
**Quality Rules**:
**MUST Include**:
- ✅ All questions in Chinese (用中文提问)
- ✅ 基于跨角色分析的具体发现
- ✅ 选项包含业务影响说明
- ✅ 解决实际的模糊点或冲突
**MUST Avoid**:
- ❌ 与角色分析无关的通用问题
- ❌ 重复已在 artifacts 阶段确认的内容
- ❌ 过于细节的实现级问题
#### Step 3: Build Update Plan
```javascript
update_plan = {
"role1": {
"enhancements": ["EP-001", "EP-003"],
"clarifications": [
{"question": "...", "answer": "...", "category": "..."}
]
},
"role2": {
"enhancements": ["EP-002"],
"clarifications": [...]
}
}
```
### Phase 5: Parallel Document Update Agents
**Execute in parallel** (one agent per role):
```javascript
// Single message with multiple Task calls for parallelism
Task(conceptual-planning-agent, `
## Agent Mission
Apply enhancements and clarifications to ${role} analysis
## Input
- role: ${role}
- analysis_path: ${brainstorm_dir}/${role}/analysis.md
- enhancements: ${role_enhancements}
- clarifications: ${role_clarifications}
- original_user_intent: ${intent}
## Flow Control Steps
1. load_current_analysis → Read analysis file
2. add_clarifications_section → Insert Q&A section
3. apply_enhancements → Integrate into relevant sections
4. resolve_contradictions → Remove conflicts
5. enforce_terminology → Align terminology
6. validate_intent → Verify alignment with user intent
7. write_updated_file → Save changes
## Output
Updated ${role}/analysis.md
`)
```
**Agent Characteristics**:
- **Isolation**: Each agent updates exactly ONE role (parallel safe)
- **Dependencies**: Zero cross-agent dependencies
- **Validation**: All updates must align with original_user_intent
### Phase 6: Parallel Feature Spec Generation [feature_mode only]
**Skip condition**: If `feature_mode` is false, skip Phase 6 and Phase 6.5 entirely. Proceed directly to Phase 7.
**Purpose**: Generate one consolidated feature specification per feature by aggregating all role perspectives.
#### Step 1: Prepare Feature Spec Directory
```javascript
const feature_specs_dir = `${brainstorm_dir}/feature-specs`;
// Ensure directory exists (create if not)
```
#### Step 2: Build Per-Feature Input Bundles
```javascript
const feature_bundles = feature_list.map(feature => {
const fid = feature.id;
const slug = feature.slug;
const role_analysis_files = participating_roles
.map(role => `${brainstorm_dir}/${role}/analysis-${fid}-${slug}.md`)
.filter(path => fileExists(path));
return {
feature_id: fid,
feature_slug: slug,
feature_name: feature.description,
feature_priority: feature.priority,
conflict_map_entry: feature_conflict_map[fid],
role_analysis_files: role_analysis_files,
contributing_roles: role_analysis_files.map(f => extractRoleName(f)),
output_path: `${feature_specs_dir}/${fid}-${slug}.md`
};
});
```
#### Step 3: Execute Parallel Feature Spec Agents
**Execute in parallel** (one agent per feature):
```javascript
Task(conceptual-planning-agent, `
## Agent Mission
Generate consolidated feature specification for ${feature.feature_id}: ${feature.feature_name}
by aggregating all role-specific analyses with conflict resolution.
## Input
- feature_id: ${feature.feature_id}
- feature_slug: ${feature.feature_slug}
- feature_name: ${feature.feature_name}
- feature_priority: ${feature.feature_priority}
- role_analysis_files: ${feature.role_analysis_files}
- conflict_map_entry: ${JSON.stringify(feature.conflict_map_entry)}
- output_path: ${feature.output_path}
- guidance_spec_feature_section: (Feature Decomposition row for this feature)
## Flow Control Steps
1. load_role_analyses → Read all role-specific analysis files for this feature
(Each file ~1500-2000 words, total ~6.5K words for 3-4 roles)
2. apply_conflict_map → Use conflict_map_entry to identify resolved/unresolved conflicts
3. four_layer_aggregation → Apply aggregation rules (see below)
4. generate_feature_spec → Write consolidated spec using template
5. write_output → Save to output_path
## Four-Layer Aggregation Rules
### Layer 1: Direct Reference
- Quote role analyses directly when consensus exists
- Format: "[Role] recommends: [direct quote]"
- Use for undisputed technical recommendations
### Layer 2: Structured Extraction
- Extract and organize key information from each role into unified structure
- Merge complementary perspectives
- De-duplicate overlapping content across roles
### Layer 3: Conflict Distillation
- **[RESOLVED]**: State the resolution directly as a design decision. Format: "**Decision**: [resolution]. **Rationale**: [from conflict.resolution]. **Trade-off**: [tradeoff]."
- **[SUGGESTED]**: Adopt the suggested resolution but mark source. Format: "**Recommended**: [resolution] (suggested by Phase 3A cross-role analysis). **Rationale**: [reason]. **Alternative**: [strongest competing view]."
- **[UNRESOLVED]**: Do NOT pick a side. Present all options neutrally. Format: "**[DECISION NEEDED]**: [topic]. **Options**: [role1: approach1] vs [role2: approach2]. **Evaluation**: [pros/cons of each]. **Impact if deferred**: [consequence]."
- **Unresolved escalation**: If 2+ [UNRESOLVED] conflicts, add warning at top of Section 2
### Layer 4: Cross-Feature Annotation
- Add explicit dependency notes with feature IDs
- Document integration points with other features
- Note shared constraints or patterns
## Feature Spec Template (7 Sections, target 1500-2500 words)
---
# Feature Spec: ${feature.feature_id} - ${feature.feature_name}
**Priority**: ${feature.feature_priority}
**Contributing Roles**: [list of roles]
**Status**: Draft (from synthesis)
## 1. Requirements Summary
[Consolidated requirements from all role perspectives]
- Functional requirements (from product-manager, product-owner)
- User experience requirements (from ux-expert, ui-designer)
- Technical requirements (from system-architect, data-architect, api-designer)
- Domain requirements (from subject-matter-expert)
## 2. Design Decisions [CORE SECTION]
[Key architectural and design decisions with rationale - 40%+ of word count]
For each decision:
- **Decision**: [What was decided]
- **Context**: [Why this decision was needed]
- **Options Considered**: [Alternatives from different roles]
- **Chosen Approach**: [Selected option with rationale]
- **Trade-offs**: [What we gain vs. what we sacrifice]
- **Source**: [Which role(s) drove this decision]
## 3. Interface Contract
[API endpoints, data models, component interfaces]
- External interfaces (API contracts from api-designer)
- Internal interfaces (component boundaries from system-architect)
- Data interfaces (schemas from data-architect)
- User interfaces (interaction patterns from ux-expert/ui-designer)
## 4. Constraints & Risks
[Technical constraints, business risks, mitigation strategies]
- Performance constraints (from system-architect)
- Data constraints (from data-architect)
- UX constraints (from ux-expert)
- Business/domain constraints (from subject-matter-expert)
- Risk mitigation strategies (from scrum-master)
## 5. Acceptance Criteria
[Testable criteria for feature completion]
- Functional acceptance (from product-owner user stories)
- Performance acceptance (from system-architect NFRs)
- UX acceptance (from ux-expert usability criteria)
- Data integrity acceptance (from data-architect)
## 6. Detailed Analysis References
[Pointers back to role-specific analysis documents]
- @../{role}/analysis-${feature.feature_id}-${feature.feature_slug}.md for each contributing role
- @../guidance-specification.md#feature-decomposition
## 7. Cross-Feature Dependencies
[Dependencies on and from other features]
- **Depends on**: [Feature IDs this feature requires]
- **Required by**: [Feature IDs that depend on this feature]
- **Shared patterns**: References to analysis-cross-cutting.md patterns
- **Integration points**: [Specific interfaces between features]
---
## Completion Criteria
- All 7 sections populated with aggregated content
- Section 2 (Design Decisions) is the most detailed section (40%+ of word count)
- All conflicts from conflict_map_entry addressed with resolutions
- Cross-feature dependencies explicitly documented
- Word count between 1500-2500
- No placeholder text except [DECISION NEEDED] for genuinely unresolved items
`)
```
**Agent Characteristics (Phase 6)**:
- **Isolation**: Each agent processes exactly ONE feature (parallel safe)
- **Dependencies**: Requires Phase 3A feature_conflict_map and Phase 5 updated role analyses
- **Input budget**: ~6.5K words per agent (3-4 role sub-docs + conflict map entry)
- **Output budget**: 1500-2500 words per feature spec
### Phase 6.5: Feature Index Generation [feature_mode only]
**Skip condition**: Same as Phase 6 - skip if `feature_mode` is false.
**Purpose**: Collect all Phase 6 outputs and generate structured `feature-index.json`.
#### Step 1: Collect Feature Spec Outputs
```javascript
const feature_spec_files = Glob(`${brainstorm_dir}/feature-specs/F-*-*.md`);
const cross_cutting_specs = participating_roles
.map(role => `${brainstorm_dir}/${role}/analysis-cross-cutting.md`)
.filter(path => fileExists(path));
```
#### Step 2: Generate feature-index.json
```javascript
const feature_index = {
"version": "1.0",
"generated_at": new Date().toISOString(),
"session_id": session_id,
"feature_mode": true,
"features": feature_list.map(feature => {
const fid = feature.id;
const slug = feature.slug;
const spec_path = `feature-specs/${fid}-${slug}.md`;
const spec_exists = fileExists(`${brainstorm_dir}/${spec_path}`);
const contributing_roles = participating_roles.filter(role =>
fileExists(`${brainstorm_dir}/${role}/analysis-${fid}-${slug}.md`)
);
const cross_cutting_refs = feature_conflict_map[fid]
? feature_conflict_map[fid].cross_refs
: [];
return {
"id": fid,
"slug": slug,
"name": feature.description,
"priority": feature.priority,
"spec_path": spec_exists ? spec_path : null,
"contributing_roles": contributing_roles,
"cross_cutting_refs": cross_cutting_refs
};
}),
"cross_cutting_specs": cross_cutting_specs.map(path =>
path.replace(brainstorm_dir + '/', '')
)
};
Write(
`${brainstorm_dir}/feature-index.json`,
JSON.stringify(feature_index, null, 2)
);
```
#### feature-index.json Schema
```json
{
"version": "1.0",
"generated_at": "2026-02-11T10:00:00.000Z",
"session_id": "WFS-xxx",
"feature_mode": true,
"features": [
{
"id": "F-001",
"slug": "real-time-sync",
"name": "Real-time collaborative synchronization",
"priority": "High",
"spec_path": "feature-specs/F-001-real-time-sync.md",
"contributing_roles": ["system-architect", "ux-expert", "data-architect"],
"cross_cutting_refs": ["F-003 offline-mode depends on sync strategy"]
}
],
"cross_cutting_specs": [
"system-architect/analysis-cross-cutting.md",
"ux-expert/analysis-cross-cutting.md"
]
}
```
**Consumers**: `action-planning-agent` reads feature-index.json to generate task JSONs. `code-developer` loads individual feature specs as implementation context.
### Phase 7: Finalization
#### Step 1: Update Context Package
```javascript
const context_pkg = Read(".workflow/active/WFS-{session}/.process/context-package.json")
// Update guidance-specification if exists
// Update synthesis-specification if exists
// Re-read all role analysis files
// Update metadata timestamps
// If feature_mode: add feature-index.json and feature-specs paths
if (feature_mode) {
context_pkg.feature_index_path = `${brainstorm_dir}/feature-index.json`;
context_pkg.feature_specs_dir = `${brainstorm_dir}/feature-specs/`;
context_pkg.feature_mode = true;
}
Write(context_pkg_path, JSON.stringify(context_pkg))
```
#### Step 2: Update Session Metadata
```json
{
"phases": {
"BRAINSTORM": {
"status": "clarification_completed",
"clarification_completed": true,
"completed_at": "timestamp",
"participating_roles": ["..."],
"clarification_results": {
"enhancements_applied": ["EP-001", "EP-002"],
"questions_asked": 3,
"categories_clarified": ["Architecture", "UX"],
"roles_updated": ["role1", "role2"]
},
"feature_spec_results": {
"feature_mode": true,
"features_generated": ["F-001", "F-002", "F-003"],
"feature_index_path": ".brainstorming/feature-index.json",
"feature_specs_dir": ".brainstorming/feature-specs/",
"conflict_map_generated": true
},
"quality_metrics": {
"user_intent_alignment": "validated",
"ambiguity_resolution": "complete",
"terminology_consistency": "enforced"
}
}
}
}
```
**Note**: `feature_spec_results` only present when `feature_mode` is true.
#### Step 3: Completion Report
```markdown
## Synthesis Complete
**Session**: {sessionId}
**Enhancements Applied**: EP-001, EP-002, EP-003
**Questions Answered**: 3/5
**Roles Updated**: role1, role2, role3
### Feature Specs (feature_mode only)
**Feature Specs Generated**: F-001, F-002, F-003
**Feature Index**: .brainstorming/feature-index.json
**Spec Directory**: .brainstorming/feature-specs/
### Next Steps
PROCEED: `/workflow:plan --session {session-id}`
```
## Output
**Location (role analyses)**: `.workflow/active/WFS-{session}/.brainstorming/[role]/analysis*.md`
**Location (feature specs)**: `.workflow/active/WFS-{session}/.brainstorming/feature-specs/F-{id}-{slug}.md` [feature_mode]
**Location (feature index)**: `.workflow/active/WFS-{session}/.brainstorming/feature-index.json` [feature_mode]
**Updated Directory Structure** (feature_mode):
```
.workflow/active/WFS-{session}/.brainstorming/
├── guidance-specification.md
├── feature-index.json # Phase 6.5 output
├── feature-specs/ # Phase 6 output directory
│ ├── F-001-{slug}.md # Consolidated feature spec (1500-2500 words)
│ ├── F-002-{slug}.md
│ └── F-00N-{slug}.md
├── {role-1}/
│ ├── analysis.md # Role overview index (read by Phase 3A)
│ ├── analysis-cross-cutting.md
│ ├── analysis-F-001-{slug}.md # Per-feature detail (read by Phase 6)
│ └── analysis-F-002-{slug}.md
└── {role-N}/
└── ...
```
**Updated Role Analysis Structure**:
```markdown
## Clarifications
### Session {date}
- **Q**: {question} (Category: {category})
**A**: {answer}
## {Existing Sections}
{Refined content based on clarifications}
```
**Changes**:
- User intent validated/corrected
- Requirements more specific/measurable
- Architecture with rationale
- Ambiguities resolved, placeholders removed
- Consistent terminology
- Feature specs generated with cross-role conflict resolution [feature_mode]
- Feature index provides structured access for downstream consumers [feature_mode]
## Quality Checklist
**Content**:
- All role analyses loaded/analyzed
- Cross-role analysis (consensus, conflicts, gaps)
- 9-category ambiguity scan
- Questions prioritized
**Analysis**:
- User intent validated
- Cross-role synthesis complete
- Ambiguities resolved
- Terminology consistent
**Documents**:
- Clarifications section formatted
- Sections reflect answers
- No placeholders (TODO/TBD)
- Valid Markdown
**Feature Specs (feature_mode only)**:
- Phase 3A reads only analysis.md index files (not sub-documents), input token <= 5K words
- feature_conflict_map generated with consensus/conflicts/cross_refs per feature
- Phase 6 parallel agents defined: one per feature, input token <= 7K words each
- Feature spec template has 7 sections, Section 2 (Design Decisions) is core
- Four-layer aggregation rules applied
- Each feature spec is 1500-2500 words
- feature-index.json generated with features[] + cross_cutting_specs[]
- feature-specs/ directory created with F-{id}-{slug}.md files
- **TodoWrite**: Mark Phase 4 completed, collapse all sub-tasks to summary
## Next Phase
Return to orchestrator. Auto mode workflow is now complete. Report final summary to user.