claude-code-workflow 6.3.53 → 7.0.0

package/.claude/skills/team-tech-debt/roles/scanner/commands/scan-debt.md

@@ -0,0 +1,388 @@
+# Command: scan-debt
+
+> 三层并行 Fan-out 技术债务扫描。Subagent 结构探索 + CLI 维度分析 + 多视角 Gemini 深度分析，三层并行执行后 Fan-in 聚合。
+
+## When to Use
+
+- Phase 3 of Scanner
+- 需要对代码库进行多维度技术债务扫描
+- 复杂度为 Medium 或 High 时使用并行 Fan-out
+
+**Trigger conditions**:
+- TDSCAN-* 任务进入 Phase 3
+- 复杂度评估为 Medium/High
+- 需要深度分析超出 ACE 搜索能力
+
+## Strategy
+
+### Delegation Mode
+
+**Mode**: Triple Fan-out + Fan-in
+**Subagent**: `cli-explore-agent`（并行结构探索）
+**CLI Tool**: `gemini` (primary)
+**CLI Mode**: `analysis`
+**Parallel Layers**:
+- Fan-out A: 2-3 并行 subagent（结构探索）
+- Fan-out B: 3-5 并行 CLI（维度分析）
+- Fan-out C: 2-4 并行 CLI（多视角 Gemini）
+
+### Decision Logic
+
+```javascript
+// 复杂度决定扫描策略
+if (complexity === 'Low') {
+  // ACE 搜索 + Grep 内联分析（不使用 CLI）
+  mode = 'inline'
+} else if (complexity === 'Medium') {
+  // 双层 Fan-out: subagent 探索 + CLI 3 维度
+  mode = 'dual-fanout'
+  activeDimensions = ['code', 'testing', 'dependency']
+  exploreAngles = ['structure', 'patterns']
+} else {
+  // 三层 Fan-out: subagent 探索 + CLI 5 维度 + 多视角 Gemini
+  mode = 'triple-fanout'
+  activeDimensions = dimensions  // all 5
+  exploreAngles = ['structure', 'patterns', 'dependencies']
+}
+```
+
+## Execution Steps
+
+### Step 1: Context Preparation
+
+```javascript
+// 确定扫描范围
+const projectRoot = Bash(`git rev-parse --show-toplevel 2>/dev/null || pwd`).trim()
+const scanScope = task.description.match(/scope:\s*(.+)/)?.[1] || '**/*'
+
+// 获取变更文件用于聚焦扫描
+const changedFiles = Bash(`git diff --name-only HEAD~10 2>/dev/null || echo ""`)
+  .split('\n').filter(Boolean)
+
+// 构建文件上下文
+const fileContext = changedFiles.length > 0
+  ? changedFiles.map(f => `@${f}`).join(' ')
+  : `@${scanScope}`
+
+// 多视角检测（从 role.md Phase 2 传入）
+// perspectives = detectPerspectives(task.description)
+```
+
+### Step 2: Execute Strategy
+
+```javascript
+if (mode === 'inline') {
+  // 快速内联扫描（Low 复杂度）
+  const aceResults = mcp__ace-tool__search_context({
+    project_root_path: projectRoot,
+    query: "code smells, TODO/FIXME, deprecated APIs, complex functions, dead code, missing tests, circular imports"
+  })
+  // 解析 ACE 结果并分类到维度
+} else {
+  // === 三层并行 Fan-out ===
+  // A、B、C 三层同时启动，互不依赖
+
+  // ─── Fan-out A: Subagent 并行探索（codebase 结构理解）───
+  executeExploreAngles(exploreAngles)
+
+  // ─── Fan-out B: CLI 维度分析（并行 gemini）───
+  executeDimensionAnalysis(activeDimensions)
+
+  // ─── Fan-out C: 多视角 Gemini 深度分析（并行）───
+  if (mode === 'triple-fanout') {
+    executePerspectiveAnalysis(perspectives)
+  }
+
+  // 等待所有 Fan-out 完成（hook 回调通知）
+}
+```
+
+### Step 2a: Fan-out A — Subagent Exploration
+
+> 并行启动 cli-explore-agent 探索代码库结构，为后续分析提供上下文。
+> 每个角度独立执行，不互相依赖。
+
+```javascript
+function executeExploreAngles(angles) {
+  const explorePrompts = {
+    'structure': `Explore the codebase structure and module organization.
+Focus on: directory layout, module boundaries, entry points, build configuration.
+Project root: ${projectRoot}
+Report: module map, key entry files, build system type, framework detection.`,
+
+    'patterns': `Explore coding patterns and conventions used in this codebase.
+Focus on: naming conventions, import patterns, error handling patterns, state management, design patterns.
+Project root: ${projectRoot}
+Report: dominant patterns, anti-patterns found, consistency assessment.`,
+
+    'dependencies': `Explore dependency graph and inter-module relationships.
+Focus on: import/require chains, circular dependencies, external dependency usage, shared utilities.
+Project root: ${projectRoot}
+Report: dependency hotspots, tightly-coupled modules, dependency depth analysis.`
+  }
+
+  // 并行启动所有探索角度（每个 cli-explore-agent 独立执行）
+  for (const angle of angles) {
+    Task({
+      subagent_type: "cli-explore-agent",
+      run_in_background: false,
+      description: `Explore: ${angle}`,
+      prompt: explorePrompts[angle] || `Explore from ${angle} perspective. Project: ${projectRoot}`
+    })
+  }
+
+  // 所有 subagent 返回后，探索结果已可用
+}
+```
+
+### Step 2b: Fan-out B — CLI Dimension Analysis
+
+> 每个维度独立的 gemini CLI 分析，全部并行启动。
+
+```javascript
+function executeDimensionAnalysis(activeDimensions) {
+  const dimensionPrompts = {
+    'code': `PURPOSE: Identify code quality debt - complexity, duplication, code smells
+TASK: • Find functions with cyclomatic complexity > 10 • Detect code duplication (>20 lines) • Identify code smells (God class, long method, feature envy) • Find TODO/FIXME/HACK comments • Detect dead code and unused exports
+MODE: analysis
+CONTEXT: ${fileContext}
+EXPECTED: List of findings with severity (critical/high/medium/low), file:line, description, estimated fix effort (small/medium/large)
+CONSTRAINTS: Focus on actionable items, skip generated code`,
+
+    'architecture': `PURPOSE: Identify architecture debt - coupling, circular dependencies, layering violations
+TASK: • Detect circular dependencies between modules • Find tight coupling between components • Identify layering violations (e.g., UI importing DB) • Check for God modules with too many responsibilities • Find missing abstraction layers
+MODE: analysis
+CONTEXT: ${fileContext}
+EXPECTED: Architecture debt findings with severity, affected modules, dependency graph issues
+CONSTRAINTS: Focus on structural issues, not style`,
+
+    'testing': `PURPOSE: Identify testing debt - coverage gaps, test quality, missing test types
+TASK: • Find modules without any test files • Identify complex logic without test coverage • Check for test anti-patterns (flaky tests, hardcoded values) • Find missing edge case tests • Detect test files that import from test utilities incorrectly
+MODE: analysis
+CONTEXT: ${fileContext}
+EXPECTED: Testing debt findings with severity, affected files, missing test type (unit/integration/e2e)
+CONSTRAINTS: Focus on high-risk untested code paths`,
+
+    'dependency': `PURPOSE: Identify dependency debt - outdated packages, vulnerabilities, unnecessary deps
+TASK: • Find outdated major-version dependencies • Identify known vulnerability packages • Detect unused dependencies • Find duplicate functionality from different packages • Check for pinned vs range versions
+MODE: analysis
+CONTEXT: @package.json @package-lock.json @requirements.txt @go.mod @pom.xml
+EXPECTED: Dependency debt with severity, package name, current vs latest version, CVE references
+CONSTRAINTS: Focus on security and compatibility risks`,
+
+    'documentation': `PURPOSE: Identify documentation debt - missing docs, stale docs, undocumented APIs
+TASK: • Find public APIs without JSDoc/docstrings • Identify README files that are outdated • Check for missing architecture documentation • Find configuration options without documentation • Detect stale comments that don't match code
+MODE: analysis
+CONTEXT: ${fileContext}
+EXPECTED: Documentation debt with severity, file:line, type (missing/stale/incomplete)
+CONSTRAINTS: Focus on public interfaces and critical paths`
+  }
+
+  // 并行启动所有维度分析
+  for (const dimension of activeDimensions) {
+    const prompt = dimensionPrompts[dimension]
+    if (!prompt) continue
+
+    Bash(`ccw cli -p "${prompt}" --tool gemini --mode analysis --rule analysis-analyze-code-patterns`, {
+      run_in_background: true
+    })
+  }
+}
+```
+
+### Step 2c: Fan-out C — Multi-Perspective Gemini Analysis
+
+> 多视角深度分析，每个视角关注不同质量维度。
+> 视角由 `detectPerspectives()` 自动检测，或在 High 复杂度下全量启用。
+> 与 Fan-out B（维度分析）的区别：维度分析按"代码/测试/依赖"横切，视角分析按"安全/性能/质量/架构"纵切，交叉覆盖。
+
+```javascript
+function executePerspectiveAnalysis(perspectives) {
+  const perspectivePrompts = {
+    'security': `PURPOSE: Security-focused analysis of codebase to identify vulnerability debt
+TASK: • Find injection vulnerabilities (SQL, command, XSS, LDAP) • Check authentication/authorization weaknesses • Identify hardcoded secrets or credentials • Detect insecure data handling (sensitive data exposure) • Find missing input validation on trust boundaries • Check for outdated crypto or insecure hash functions
+MODE: analysis
+CONTEXT: ${fileContext}
+EXPECTED: Security findings with: severity (critical/high/medium/low), CWE/OWASP reference, file:line, remediation suggestion
+CONSTRAINTS: Focus on exploitable vulnerabilities, not theoretical risks`,
+
+    'performance': `PURPOSE: Performance-focused analysis to identify performance debt
+TASK: • Find N+1 query patterns in database calls • Detect unnecessary re-renders or recomputations • Identify missing caching opportunities • Find synchronous blocking in async contexts • Detect memory leak patterns (event listener accumulation, unclosed resources) • Check for unoptimized loops or O(n²) algorithms on large datasets
+MODE: analysis
+CONTEXT: ${fileContext}
+EXPECTED: Performance findings with: severity, impact estimate (latency/memory/CPU), file:line, optimization suggestion
+CONSTRAINTS: Focus on measurable impact, not micro-optimizations`,
+
+    'code-quality': `PURPOSE: Code quality deep analysis beyond surface-level linting
+TASK: • Identify functions violating single responsibility principle • Find overly complex conditional chains (>3 nesting levels) • Detect hidden temporal coupling between functions • Find magic numbers and unexplained constants • Identify error handling anti-patterns (empty catch, swallowed errors) • Detect feature envy (methods that access other classes more than their own)
+MODE: analysis
+CONTEXT: ${fileContext}
+EXPECTED: Quality findings with: severity, code smell category, file:line, refactoring suggestion with pattern name
+CONSTRAINTS: Focus on maintainability impact, skip style-only issues`,
+
+    'architecture': `PURPOSE: Architecture-level analysis of system design debt
+TASK: • Identify layering violations (skip-layer calls, reverse dependencies) • Find God modules/classes with >5 distinct responsibilities • Detect missing domain boundaries (business logic in UI/API layer) • Check for abstraction leaks (implementation details in interfaces) • Identify duplicated business logic across modules • Find tightly coupled modules that should be independent
+MODE: analysis
+CONTEXT: ${fileContext}
+EXPECTED: Architecture findings with: severity, affected modules, coupling metric, suggested restructuring
+CONSTRAINTS: Focus on structural issues affecting scalability and team autonomy`
+  }
+
+  // 并行启动所有视角分析
+  for (const perspective of perspectives) {
+    const prompt = perspectivePrompts[perspective]
+    if (!prompt) continue
+
+    Bash(`ccw cli -p "${prompt}" --tool gemini --mode analysis --rule analysis-review-architecture`, {
+      run_in_background: true
+    })
+  }
+}
+```
+
+### Step 3: Fan-in Result Processing
+
+> 三层 Fan-out 结果聚合：探索结果提供上下文，维度分析 + 视角分析交叉去重。
+
+```javascript
+// ─── 3a: 聚合探索结果（来自 Fan-out A）───
+const exploreContext = {
+  structure: exploreResults['structure'] || {},
+  patterns: exploreResults['patterns'] || {},
+  dependencies: exploreResults['dependencies'] || {}
+}
+
+// ─── 3b: 聚合维度分析结果（来自 Fan-out B）───
+const dimensionFindings = []
+for (const dimension of activeDimensions) {
+  const findings = parseCliOutput(cliResults[dimension])
+  for (const finding of findings) {
+    finding.dimension = dimension
+    finding.source = 'dimension-analysis'
+    dimensionFindings.push(finding)
+  }
+}
+
+// ─── 3c: 聚合视角分析结果（来自 Fan-out C）───
+const perspectiveFindings = []
+if (mode === 'triple-fanout') {
+  for (const perspective of perspectives) {
+    const findings = parseCliOutput(cliResults[perspective])
+    for (const finding of findings) {
+      finding.perspective = perspective
+      finding.source = 'perspective-analysis'
+      // 映射视角到最近维度（用于统一归类）
+      finding.dimension = finding.dimension || mapPerspectiveToDimension(perspective)
+      perspectiveFindings.push(finding)
+    }
+  }
+}
+
+// ─── 3d: 合并 + 交叉去重 ───
+const allFindings = [...dimensionFindings, ...perspectiveFindings]
+
+function deduplicateFindings(findings) {
+  const seen = new Map()  // key → finding (保留严重性更高的)
+  for (const f of findings) {
+    const key = `${f.file}:${f.line}`
+    const existing = seen.get(key)
+    if (!existing) {
+      seen.set(key, f)
+    } else {
+      // 同一位置多角度发现 → 合并，提升严重性
+      const severityOrder = { critical: 0, high: 1, medium: 2, low: 3 }
+      if ((severityOrder[f.severity] || 3) < (severityOrder[existing.severity] || 3)) {
+        existing.severity = f.severity
+      }
+      // 记录交叉引用（被多个视角/维度发现的条目更可信）
+      existing.crossRefs = existing.crossRefs || []
+      existing.crossRefs.push({ source: f.source, perspective: f.perspective, dimension: f.dimension })
+    }
+  }
+  return [...seen.values()]
+}
+
+// 视角 → 维度映射
+function mapPerspectiveToDimension(perspective) {
+  const map = {
+    'security': 'code',
+    'performance': 'code',
+    'code-quality': 'code',
+    'architecture': 'architecture'
+  }
+  return map[perspective] || 'code'
+}
+
+const deduped = deduplicateFindings(allFindings)
+
+// ─── 3e: 按严重性排序（交叉引用的条目优先）───
+deduped.sort((a, b) => {
+  // 被多角度发现的条目 → 优先级提升
+  const aBoost = (a.crossRefs?.length || 0) > 0 ? -0.5 : 0
+  const bBoost = (b.crossRefs?.length || 0) > 0 ? -0.5 : 0
+  const order = { critical: 0, high: 1, medium: 2, low: 3 }
+  return ((order[a.severity] || 3) + aBoost) - ((order[b.severity] || 3) + bBoost)
+})
+
+// ─── 3f: 用探索上下文增强发现（可选）───
+// 利用 Fan-out A 的结构探索结果标注模块归属
+for (const finding of deduped) {
+  if (finding.file && exploreContext.structure?.modules) {
+    const module = exploreContext.structure.modules.find(m =>
+      finding.file.startsWith(m.path)
+    )
+    if (module) finding.module = module.name
+  }
+}
+```
+
+## Output Format
+
+```
+## Debt Scan Results
+
+### Scan Mode: [inline|dual-fanout|triple-fanout]
+### Complexity: [Low|Medium|High]
+### Perspectives: [security, performance, code-quality, architecture]
+
+### Findings by Dimension
+#### Code Quality ([count])
+- [file:line] [severity] - [description] [crossRefs: N perspectives]
+
+#### Architecture ([count])
+- [module] [severity] - [description]
+
+#### Testing ([count])
+- [file:line] [severity] - [description]
+
+#### Dependency ([count])
+- [package] [severity] - [description]
+
+#### Documentation ([count])
+- [file:line] [severity] - [description]
+
+### Multi-Perspective Highlights
+#### Security Findings ([count])
+- [file:line] [severity] - [CWE-xxx] [description]
+
+#### Performance Findings ([count])
+- [file:line] [severity] - [impact] [description]
+
+### Cross-Referenced Items (多角度交叉验证)
+- [file:line] confirmed by [N] sources - [description]
+
+### Total Debt Items: [count]
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| CLI tool unavailable | Fall back to ACE search + Grep inline analysis |
+| CLI returns empty for a dimension | Note incomplete dimension, continue others |
+| Subagent explore fails | Skip explore context, proceed with CLI analysis only |
+| Too many findings (>100) | Prioritize critical/high + cross-referenced, summarize rest |
+| Timeout on CLI call | Use partial results, note incomplete dimensions/perspectives |
+| Agent/CLI failure | Retry once, then fallback to inline execution |
+| Perspective analysis timeout | Use dimension-only results, note missing perspectives |
+| All Fan-out layers fail | Fall back to ACE inline scan (guaranteed minimum) |

package/.claude/skills/team-tech-debt/roles/scanner/role.md

@@ -0,0 +1,225 @@
+# Scanner Role
+
+多维度技术债务扫描器。扫描代码库的 5 个维度：代码质量、架构、测试、依赖、文档，生成结构化债务清单。通过 CLI Fan-out 并行分析，产出 debt-inventory.json。
+
+## Identity
+
+- **Name**: `scanner` | **Tag**: `[scanner]`
+- **Task Prefix**: `TDSCAN-*`
+- **Responsibility**: Orchestration (多维度扫描编排)
+
+## Boundaries
+
+### MUST
+- Only process `TDSCAN-*` prefixed tasks
+- All output (SendMessage, team_msg, logs) must carry `[scanner]` identifier
+- Only communicate with coordinator via SendMessage
+- Work strictly within debt scanning responsibility scope
+- Tag all findings with dimension (code, architecture, testing, dependency, documentation)
+
+### MUST NOT
+- Write or modify any code
+- Execute fix operations
+- Create tasks for other roles
+- Communicate directly with other worker roles (must go through coordinator)
+- Omit `[scanner]` identifier in any output
+
+---
+
+## Toolbox
+
+### Available Commands
+
+| Command | File | Phase | Description |
+|---------|------|-------|-------------|
+| `scan-debt` | [commands/scan-debt.md](commands/scan-debt.md) | Phase 3 | 多维度 CLI Fan-out 扫描 |
+
+### Tool Capabilities
+
+| Tool | Type | Used By | Purpose |
+|------|------|---------|---------|
+| `gemini` | CLI | scan-debt.md | 多维度代码分析（dimension fan-out） |
+| `cli-explore-agent` | Subagent | scan-debt.md | 并行代码库结构探索 |
+
+---
+
+## Message Types
+
+| Type | Direction | Trigger | Description |
+|------|-----------|---------|-------------|
+| `scan_complete` | scanner -> coordinator | 扫描完成 | 包含债务清单摘要 |
+| `debt_items_found` | scanner -> coordinator | 发现高优先级债务 | 需要关注的关键发现 |
+| `error` | scanner -> coordinator | 扫描失败 | 阻塞性错误 |
+
+## Message Bus
+
+Before every SendMessage, log via `mcp__ccw-tools__team_msg`:
+
+```
+mcp__ccw-tools__team_msg({
+  operation: "log",
+  team: <session-id>,  // MUST be session ID (e.g., TD-xxx-date), NOT team name. Extract from Session: field in task description.
+  from: "scanner",
+  to: "coordinator",
+  type: <message-type>,
+  summary: "[scanner] <task-prefix> complete: <task-subject>",
+  ref: <artifact-path>
+})
+```
+
+**CLI fallback** (when MCP unavailable):
+
+```
+Bash("ccw team log --team <session-id> --from scanner --to coordinator --type <message-type> --summary \"[scanner] ...\" --ref <artifact-path> --json")
+```
+
+---
+
+## Execution (5-Phase)
+
+### Phase 1: Task Discovery
+
+> See SKILL.md Shared Infrastructure -> Worker Phase 1: Task Discovery
+
+Standard task discovery flow: TaskList -> filter by prefix `TDSCAN-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.
+
+### Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Scan scope | task.description (regex: `scope:\s*(.+)`) | No (default: `**/*`) |
+| Session folder | task.description (regex: `session:\s*(.+)`) | Yes |
+| Shared memory | `<session-folder>/shared-memory.json` | Yes |
+
+**Loading steps**:
+
+1. Extract session path from task description
+2. Read shared-memory.json for team context
+3. Detect project type and framework:
+
+| Detection | Method |
+|-----------|--------|
+| Node.js project | Check for package.json |
+| Python project | Check for pyproject.toml or requirements.txt |
+| Go project | Check for go.mod |
+
+4. Determine scan dimensions (default: code, architecture, testing, dependency, documentation)
+5. Detect perspectives from task description:
+
+| Condition | Perspective |
+|-----------|-------------|
+| `security\|auth\|inject\|xss` | security |
+| `performance\|speed\|optimize` | performance |
+| `quality\|clean\|maintain\|debt` | code-quality |
+| `architect\|pattern\|structure` | architecture |
+| Default | code-quality + architecture |
+
+6. Assess complexity:
+
+| Signal | Weight |
+|--------|--------|
+| `全项目\|全量\|comprehensive\|full` | +3 |
+| `architecture\|架构` | +1 |
+| `multiple\|across\|cross\|多模块` | +2 |
+
+| Score | Complexity |
+|-------|------------|
+| >= 4 | High |
+| 2-3 | Medium |
+| 0-1 | Low |
+
+### Phase 3: Multi-Dimension Scan
+
+Delegate to `commands/scan-debt.md` if available, otherwise execute inline.
+
+**Core Strategy**: Three-layer parallel Fan-out
+
+| Complexity | Strategy |
+|------------|----------|
+| Low | Direct: ACE search + Grep inline scan |
+| Medium/High | Fan-out A: Subagent exploration (cli-explore-agent) + Fan-out B: CLI dimension analysis (gemini per dimension) + Fan-out C: Multi-perspective Gemini analysis |
+
+**Fan-out Architecture**:
+
+```
+Fan-out A: Subagent Exploration (parallel cli-explore)
+  structure perspective | patterns perspective | deps perspective
+                        ↓ merge
+Fan-out B: CLI Dimension Analysis (parallel gemini)
+  code | architecture | testing | dependency | documentation
+                        ↓ merge
+Fan-out C: Multi-Perspective Gemini (parallel)
+  security | performance | code-quality | architecture
+                        ↓ Fan-in aggregate
+                  debt-inventory.json
+```
+
+**Low Complexity Path** (inline):
+
+```
+mcp__ace-tool__search_context({
+  project_root_path: <project-root>,
+  query: "code smells, TODO/FIXME, deprecated APIs, complex functions, missing tests"
+})
+```
+
+### Phase 4: Aggregate into Debt Inventory
+
+**Standardize findings**:
+
+For each finding, create entry:
+
+| Field | Description |
+|-------|-------------|
+| `id` | `TD-NNN` (sequential) |
+| `dimension` | code, architecture, testing, dependency, documentation |
+| `severity` | critical, high, medium, low |
+| `file` | File path |
+| `line` | Line number |
+| `description` | Issue description |
+| `suggestion` | Fix suggestion |
+| `estimated_effort` | small, medium, large, unknown |
+
+**Save outputs**:
+
+1. Update shared-memory.json with `debt_inventory` and `debt_score_before`
+2. Write `<session-folder>/scan/debt-inventory.json`:
+
+| Field | Description |
+|-------|-------------|
+| `scan_date` | ISO timestamp |
+| `dimensions` | Array of scanned dimensions |
+| `total_items` | Count of debt items |
+| `by_dimension` | Count per dimension |
+| `by_severity` | Count per severity level |
+| `items` | Array of debt entries |
+
+### Phase 5: Report to Coordinator
+
+> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report
+
+Standard report flow: team_msg log -> SendMessage with `[scanner]` prefix -> TaskUpdate completed -> Loop to Phase 1 for next task.
+
+**Report content**:
+
+| Field | Value |
+|-------|-------|
+| Task | task.subject |
+| Dimensions | dimensions scanned |
+| Status | "Debt Found" or "Clean" |
+| Summary | Total items with dimension breakdown |
+| Top Debt Items | Top 5 critical/high severity items |
+| Debt Inventory | Path to debt-inventory.json |
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| No TDSCAN-* tasks available | Idle, wait for coordinator assignment |
+| CLI tool unavailable | Fall back to ACE search + Grep inline analysis |
+| Scan scope too broad | Narrow to src/ directory, report partial results |
+| All dimensions return empty | Report clean scan, notify coordinator |
+| CLI timeout | Use partial results, note incomplete dimensions |
+| Critical issue beyond scope | SendMessage debt_items_found to coordinator |