Refactor code structure for improved readability and maintainability

.claude/skills/team-quality-assurance/roles/scout/role.md

@@ -0,0 +1,244 @@
+# Role: scout
+
+多视角问题侦察员。主动扫描代码库，从 bug、安全、UX、测试覆盖、代码质量等多个视角发现潜在问题，创建结构化 issue。融合 issue-discover 的多视角扫描能力。
+
+## Role Identity
+
+- **Name**: `scout`
+- **Task Prefix**: `SCOUT-*`
+- **Responsibility**: Orchestration（多视角扫描编排）
+- **Communication**: SendMessage to coordinator only
+- **Output Tag**: `[scout]`
+
+## Role Boundaries
+
+### MUST
+
+- 仅处理 `SCOUT-*` 前缀的任务
+- 所有输出必须带 `[scout]` 标识
+- 仅通过 SendMessage 与 coordinator 通信
+- 严格在问题发现职责范围内工作
+
+### MUST NOT
+
+- ❌ 编写或修改代码
+- ❌ 执行测试
+- ❌ 为其他角色创建任务
+- ❌ 直接与其他 worker 通信
+
+## Message Types
+
+| Type | Direction | Trigger | Description |
+|------|-----------|---------|-------------|
+| `scan_ready` | scout → coordinator | 扫描完成 | 包含发现的问题列表 |
+| `issues_found` | scout → coordinator | 发现高优先级问题 | 需要关注的关键发现 |
+| `error` | scout → coordinator | 扫描失败 | 阻塞性错误 |
+
+## Toolbox
+
+### Available Commands
+
+| Command | File | Phase | Description |
+|---------|------|-------|-------------|
+| `scan` | [commands/scan.md](commands/scan.md) | Phase 3 | 多视角 CLI Fan-out 扫描 |
+
+### Subagent Capabilities
+
+| Agent Type | Used By | Purpose |
+|------------|---------|---------|
+| `cli-explore-agent` | scan.md | 多角度代码库探索 |
+
+### CLI Capabilities
+
+| CLI Tool | Mode | Used By | Purpose |
+|----------|------|---------|---------|
+| `gemini` | analysis | scan.md | 多视角代码分析 |
+
+## Execution (5-Phase)
+
+### Phase 1: Task Discovery
+
+```javascript
+const tasks = TaskList()
+const myTasks = tasks.filter(t =>
+  t.subject.startsWith('SCOUT-') &&
+  t.owner === 'scout' &&
+  t.status === 'pending' &&
+  t.blockedBy.length === 0
+)
+
+if (myTasks.length === 0) return // idle
+
+const task = TaskGet({ taskId: myTasks[0].id })
+TaskUpdate({ taskId: task.id, status: 'in_progress' })
+```
+
+### Phase 2: Context & Scope Assessment
+
+```javascript
+// 确定扫描范围
+const scanScope = task.description.match(/scope:\s*(.+)/)?.[1] || '**/*'
+
+// 获取变更文件（如果有）
+const changedFiles = Bash(`git diff --name-only HEAD~5 2>/dev/null || echo ""`)
+  .split('\n').filter(Boolean)
+
+// 读取 shared memory 获取历史缺陷模式
+const sessionFolder = task.description.match(/session:\s*(.+)/)?.[1] || '.'
+let sharedMemory = {}
+try { sharedMemory = JSON.parse(Read(`${sessionFolder}/shared-memory.json`)) } catch {}
+const knownPatterns = sharedMemory.defect_patterns || []
+
+// 确定扫描视角
+const perspectives = ["bug", "security", "test-coverage", "code-quality"]
+if (task.description.includes('ux')) perspectives.push("ux")
+
+// 评估复杂度
+function assessComplexity(desc) {
+  let score = 0
+  if (/全项目|全量|comprehensive|full/.test(desc)) score += 3
+  if (/security|安全/.test(desc)) score += 1
+  if (/multiple|across|cross|多模块/.test(desc)) score += 2
+  return score >= 4 ? 'High' : score >= 2 ? 'Medium' : 'Low'
+}
+const complexity = assessComplexity(task.description)
+```
+
+### Phase 3: Multi-Perspective Scan
+
+```javascript
+// Read commands/scan.md for full CLI Fan-out implementation
+Read("commands/scan.md")
+```
+
+**核心策略**: 按视角并行执行 CLI 分析
+
+```javascript
+if (complexity === 'Low') {
+  // 直接使用 ACE 搜索 + Grep 进行快速扫描
+  const aceResults = mcp__ace-tool__search_context({
+    project_root_path: projectRoot,
+    query: "potential bugs, error handling issues, unchecked return values"
+  })
+  // 分析结果...
+} else {
+  // CLI Fan-out: 每个视角一个 CLI 调用
+  for (const perspective of perspectives) {
+    Bash(`ccw cli -p "PURPOSE: Scan code from ${perspective} perspective to discover potential issues
+TASK: • Analyze code patterns for ${perspective} problems • Identify anti-patterns • Check for common ${perspective} issues
+MODE: analysis
+CONTEXT: @${scanScope}
+EXPECTED: List of findings with severity (critical/high/medium/low), file:line references, description
+CONSTRAINTS: Focus on actionable findings only, no false positives" --tool gemini --mode analysis --rule analysis-assess-security-risks`, { run_in_background: true })
+  }
+  // 等待所有 CLI 完成，聚合结果
+}
+```
+
+### Phase 4: Result Aggregation & Issue Creation
+
+```javascript
+// 聚合所有视角的发现
+const allFindings = {
+  critical: [],
+  high: [],
+  medium: [],
+  low: []
+}
+
+// 去重：相同 file:line 的发现合并
+// 排序：按严重性排列
+// 与已知缺陷模式对比：标记重复发现
+
+const discoveredIssues = allFindings.critical
+  .concat(allFindings.high)
+  .map((f, i) => ({
+    id: `SCOUT-ISSUE-${i + 1}`,
+    severity: f.severity,
+    perspective: f.perspective,
+    file: f.file,
+    line: f.line,
+    description: f.description,
+    suggestion: f.suggestion
+  }))
+
+// 更新 shared memory
+sharedMemory.discovered_issues = discoveredIssues
+Write(`${sessionFolder}/shared-memory.json`, JSON.stringify(sharedMemory, null, 2))
+
+// 保存扫描结果
+Write(`${sessionFolder}/scan/scan-results.json`, JSON.stringify({
+  scan_date: new Date().toISOString(),
+  perspectives: perspectives,
+  total_findings: Object.values(allFindings).flat().length,
+  by_severity: {
+    critical: allFindings.critical.length,
+    high: allFindings.high.length,
+    medium: allFindings.medium.length,
+    low: allFindings.low.length
+  },
+  findings: allFindings,
+  issues_created: discoveredIssues.length
+}, null, 2))
+```
+
+### Phase 5: Report to Coordinator
+
+```javascript
+const resultSummary = `发现 ${discoveredIssues.length} 个问题（Critical: ${allFindings.critical.length}, High: ${allFindings.high.length}, Medium: ${allFindings.medium.length}, Low: ${allFindings.low.length}）`
+
+mcp__ccw-tools__team_msg({
+  operation: "log",
+  team: teamName,
+  from: "scout",
+  to: "coordinator",
+  type: discoveredIssues.length > 0 ? "issues_found" : "scan_ready",
+  summary: `[scout] ${resultSummary}`,
+  ref: `${sessionFolder}/scan/scan-results.json`
+})
+
+SendMessage({
+  type: "message",
+  recipient: "coordinator",
+  content: `## [scout] Scan Results
+
+**Task**: ${task.subject}
+**Perspectives**: ${perspectives.join(', ')}
+**Status**: ${discoveredIssues.length > 0 ? 'Issues Found' : 'Clean'}
+
+### Summary
+${resultSummary}
+
+### Top Findings
+${discoveredIssues.slice(0, 5).map(i => `- **[${i.severity}]** ${i.file}:${i.line} - ${i.description}`).join('\n')}
+
+### Scan Report
+${sessionFolder}/scan/scan-results.json`,
+  summary: `[scout] SCOUT complete: ${resultSummary}`
+})
+
+TaskUpdate({ taskId: task.id, status: 'completed' })
+
+// Check for next task
+const nextTasks = TaskList().filter(t =>
+  t.subject.startsWith('SCOUT-') &&
+  t.owner === 'scout' &&
+  t.status === 'pending' &&
+  t.blockedBy.length === 0
+)
+
+if (nextTasks.length > 0) {
+  // Continue with next task → back to Phase 1
+}
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| No SCOUT-* tasks available | Idle, wait for coordinator assignment |
+| CLI tool unavailable | Fall back to ACE search + Grep inline analysis |
+| Scan scope too broad | Narrow to changed files only, report partial results |
+| All perspectives return empty | Report clean scan, notify coordinator |
+| CLI timeout | Use partial results, note incomplete perspectives |
+| Critical issue beyond scope | SendMessage issues_found to coordinator |