claude-code-workflow 6.3.2 → 6.3.5

package/.claude/skills/project-analyze/phases/03.5-consolidation.md

@@ -0,0 +1,208 @@
+# Phase 3.5: Consolidation Agent
+
+汇总所有分析 Agent 的产出，生成跨章节综合分析，为 Phase 4 索引报告提供内容。
+
+> **写作规范**: [../specs/writing-style.md](../specs/writing-style.md)
+
+## 核心职责
+
+1. **跨章节综合分析**：生成 synthesis（报告综述）
+2. **章节摘要提取**：生成 section_summaries（索引表格内容）
+3. **质量检查**：识别问题并评分
+4. **建议汇总**：生成 recommendations（优先级排序）
+
+## 输入
+
+```typescript
+interface ConsolidationInput {
+  output_dir: string;
+  config: AnalysisConfig;
+  agent_summaries: AgentReturn[];
+  cross_module_notes: string[];
+}
+```
+
+## 执行
+
+```javascript
+Task({
+  subagent_type: "cli-explore-agent",
+  run_in_background: false,
+  prompt: `
+## 规范前置
+首先读取规范文件：
+- Read: ${skillRoot}/specs/quality-standards.md
+- Read: ${skillRoot}/specs/writing-style.md
+严格遵循规范中的质量标准和段落式写作要求。
+
+## 任务
+作为汇总 Agent，读取所有章节文件，执行跨章节分析，生成汇总报告和索引内容。
+
+## 输入
+- 章节文件: ${outputDir}/sections/section-*.md
+- Agent 摘要: ${JSON.stringify(agent_summaries)}
+- 跨模块备注: ${JSON.stringify(cross_module_notes)}
+- 报告类型: ${config.type}
+
+## 核心产出
+
+### 1. 综合分析 (synthesis)
+阅读所有章节，用 2-3 段落描述项目全貌：
+- 第一段：项目定位与核心架构特征
+- 第二段：关键设计决策与技术选型
+- 第三段：整体质量评价与显著特点
+
+### 2. 章节摘要 (section_summaries)
+为每个章节提取一句话核心发现，用于索引表格。
+
+### 3. 架构洞察 (cross_analysis)
+描述章节间的关联性，如：
+- 模块间的依赖关系如何体现在各章节
+- 设计决策如何贯穿多个层面
+- 潜在的一致性或冲突
+
+### 4. 建议汇总 (recommendations)
+按优先级整理各章节的建议，段落式描述。
+
+## 质量检查维度
+
+### 一致性检查
+- 术语一致性：同一概念是否使用相同名称
+- 代码引用：file:line 格式是否正确
+
+### 完整性检查
+- 章节覆盖：是否涵盖所有必需章节
+- 内容深度：每章节是否达到 ${config.depth} 级别
+
+### 质量检查
+- Mermaid 语法：图表是否可渲染
+- 段落式写作：是否符合写作规范（禁止清单罗列）
+
+## 输出文件
+
+写入: ${outputDir}/consolidation-summary.md
+
+### 文件格式
+
+\`\`\`markdown
+# 分析汇总报告
+
+## 综合分析
+
+[2-3 段落的项目全貌描述，段落式写作]
+
+## 章节摘要
+
+| 章节 | 文件 | 核心发现 |
+|------|------|----------|
+| 系统概述 | section-overview.md | 一句话描述 |
+| 层次分析 | section-layers.md | 一句话描述 |
+| ... | ... | ... |
+
+## 架构洞察
+
+[跨章节关联分析，段落式描述]
+
+## 建议汇总
+
+[优先级排序的建议，段落式描述]
+
+---
+
+## 质量评估
+
+### 评分
+
+| 维度 | 得分 | 说明 |
+|------|------|------|
+| 完整性 | 85% | ... |
+| 一致性 | 90% | ... |
+| 深度 | 95% | ... |
+| 可读性 | 88% | ... |
+| 综合 | 89% | ... |
+
+### 发现的问题
+
+#### 严重问题
+| ID | 类型 | 位置 | 描述 |
+|----|------|------|------|
+| E001 | ... | ... | ... |
+
+#### 警告
+| ID | 类型 | 位置 | 描述 |
+|----|------|------|------|
+| W001 | ... | ... | ... |
+
+#### 提示
+| ID | 类型 | 位置 | 描述 |
+|----|------|------|------|
+| I001 | ... | ... | ... |
+
+### 统计
+
+- 章节数: X
+- 图表数: X
+- 总字数: X
+\`\`\`
+
+## 返回格式 (JSON)
+
+{
+  "status": "completed",
+  "output_file": "consolidation-summary.md",
+
+  // Phase 4 索引报告所需
+  "synthesis": "2-3 段落的综合分析文本",
+  "cross_analysis": "跨章节关联分析文本",
+  "recommendations": "优先级排序的建议文本",
+  "section_summaries": [
+    {"file": "section-overview.md", "title": "系统概述", "summary": "一句话核心发现"},
+    {"file": "section-layers.md", "title": "层次分析", "summary": "一句话核心发现"}
+  ],
+
+  // 质量信息
+  "quality_score": {
+    "completeness": 85,
+    "consistency": 90,
+    "depth": 95,
+    "readability": 88,
+    "overall": 89
+  },
+  "issues": {
+    "errors": [...],
+    "warnings": [...],
+    "info": [...]
+  },
+  "stats": {
+    "total_sections": 5,
+    "total_diagrams": 8,
+    "total_words": 3500
+  }
+}
+`
+})
+```
+
+## 问题分类
+
+| 严重级别 | 前缀 | 含义 | 处理方式 |
+|----------|------|------|----------|
+| Error | E | 阻塞报告生成 | 必须修复 |
+| Warning | W | 影响报告质量 | 建议修复 |
+| Info | I | 可改进项 | 可选修复 |
+
+## 问题类型
+
+| 类型 | 说明 |
+|------|------|
+| missing | 缺失章节 |
+| inconsistency | 术语/描述不一致 |
+| invalid_ref | 无效代码引用 |
+| syntax | Mermaid 语法错误 |
+| shallow | 内容过浅 |
+| list_style | 违反段落式写作规范 |
+
+## Output
+
+- **文件**: `consolidation-summary.md`（完整汇总报告）
+- **返回**: JSON 包含 Phase 4 所需的所有字段

package/.claude/skills/project-analyze/phases/04-report-generation.md

@@ -0,0 +1,217 @@
+# Phase 4: Report Generation
+
+生成索引式报告，通过 markdown 链接引用章节文件。
+
+> **规范参考**: [../specs/quality-standards.md](../specs/quality-standards.md)
+
+## 设计原则
+
+1. **引用而非嵌入**：主报告通过链接引用章节，不复制内容
+2. **索引 + 综述**：主报告提供导航和高阶分析
+3. **避免重复**：综述来自 consolidation，不重新生成
+4. **独立可读**：各章节文件可单独阅读
+
+## 输入
+
+```typescript
+interface ReportInput {
+  output_dir: string;
+  config: AnalysisConfig;
+  consolidation: {
+    quality_score: QualityScore;
+    issues: { errors: Issue[], warnings: Issue[], info: Issue[] };
+    stats: Stats;
+    synthesis: string;  // consolidation agent 的综合分析
+    section_summaries: Array<{file: string, summary: string}>;
+  };
+}
+```
+
+## 执行流程
+
+```javascript
+// 1. 质量门禁检查
+if (consolidation.issues.errors.length > 0) {
+  const response = await AskUserQuestion({
+    questions: [{
+      question: `发现 ${consolidation.issues.errors.length} 个严重问题，如何处理？`,
+      header: "质量检查",
+      multiSelect: false,
+      options: [
+        {label: "查看并修复", description: "显示问题列表，手动修复后重试"},
+        {label: "忽略继续", description: "跳过问题检查，继续装配"},
+        {label: "终止", description: "停止报告生成"}
+      ]
+    }]
+  });
+
+  if (response === "查看并修复") {
+    return { action: "fix_required", errors: consolidation.issues.errors };
+  }
+  if (response === "终止") {
+    return { action: "abort" };
+  }
+}
+
+// 2. 生成索引式报告（不读取章节内容）
+const report = generateIndexReport(config, consolidation);
+
+// 3. 写入最终文件
+const fileName = `${config.type.toUpperCase()}-REPORT.md`;
+Write(`${outputDir}/${fileName}`, report);
+```
+
+## 报告模板
+
+### 通用结构
+
+```markdown
+# {报告标题}
+
+> 生成日期：{date}
+> 分析范围：{scope}
+> 分析深度：{depth}
+> 质量评分：{overall}%
+
+---
+
+## 报告综述
+
+{consolidation.synthesis - 来自汇总 Agent 的跨章节综合分析}
+
+---
+
+## 章节索引
+
+| 章节 | 核心发现 | 详情 |
+|------|----------|------|
+{section_summaries 生成的表格行}
+
+---
+
+## 架构洞察
+
+{从 consolidation 提取的跨模块关联分析}
+
+---
+
+## 建议与展望
+
+{consolidation.recommendations - 优先级排序的综合建议}
+
+---
+
+**附录**
+
+- [质量报告](./consolidation-summary.md)
+- [章节文件目录](./sections/)
+```
+
+### 报告标题映射
+
+| 类型 | 标题 |
+|------|------|
+| architecture | 项目架构设计报告 |
+| design | 项目设计模式报告 |
+| methods | 项目核心方法报告 |
+| comprehensive | 项目综合分析报告 |
+
+## 生成函数
+
+```javascript
+function generateIndexReport(config, consolidation) {
+  const titles = {
+    architecture: "项目架构设计报告",
+    design: "项目设计模式报告",
+    methods: "项目核心方法报告",
+    comprehensive: "项目综合分析报告"
+  };
+
+  const date = new Date().toLocaleDateString('zh-CN');
+
+  // 章节索引表格
+  const sectionTable = consolidation.section_summaries
+    .map(s => `| ${s.title} | ${s.summary} | [查看详情](./sections/${s.file}) |`)
+    .join('\n');
+
+  return `# ${titles[config.type]}
+
+> 生成日期：${date}
+> 分析范围：${config.scope}
+> 分析深度：${config.depth}
+> 质量评分：${consolidation.quality_score.overall}%
+
+---
+
+## 报告综述
+
+${consolidation.synthesis}
+
+---
+
+## 章节索引
+
+| 章节 | 核心发现 | 详情 |
+|------|----------|------|
+${sectionTable}
+
+---
+
+## 架构洞察
+
+${consolidation.cross_analysis || '详见各章节分析。'}
+
+---
+
+## 建议与展望
+
+${consolidation.recommendations || '详见质量报告中的改进建议。'}
+
+---
+
+**附录**
+
+- [质量报告](./consolidation-summary.md)
+- [章节文件目录](./sections/)
+`;
+}
+```
+
+## 输出结构
+
+```
+.workflow/.scratchpad/analyze-{timestamp}/
+├── sections/                    # 独立章节（Phase 3 产出）
+│   ├── section-overview.md
+│   ├── section-layers.md
+│   └── ...
+├── consolidation-summary.md     # 质量报告（Phase 3.5 产出）
+└── {TYPE}-REPORT.md             # 索引报告（本阶段产出）
+```
+
+## 与 Phase 3.5 的协作
+
+Phase 3.5 consolidation agent 需要提供：
+
+```typescript
+interface ConsolidationOutput {
+  // ... 原有字段
+  synthesis: string;           // 跨章节综合分析（2-3 段落）
+  cross_analysis: string;      // 架构级关联洞察
+  recommendations: string;     // 优先级排序的建议
+  section_summaries: Array<{
+    file: string;              // 文件名
+    title: string;             // 章节标题
+    summary: string;           // 一句话核心发现
+  }>;
+}
+```
+
+## 关键变更
+
+| 原设计 | 新设计 |
+|--------|--------|
+| 读取章节内容并拼接 | 链接引用，不读取内容 |
+| 重新生成 Executive Summary | 直接使用 consolidation.synthesis |
+| 嵌入质量评分表格 | 链接引用 consolidation-summary.md |
+| 主报告包含全部内容 | 主报告仅为索引 + 综述 |

package/.claude/skills/project-analyze/phases/05-iterative-refinement.md

@@ -0,0 +1,124 @@
+# Phase 5: Iterative Refinement
+
+Discovery-driven refinement based on analysis findings.
+
+## Execution
+
+### Step 1: Extract Discoveries
+
+```javascript
+function extractDiscoveries(deepAnalysis) {
+  return {
+    ambiguities: deepAnalysis.findings.filter(f => f.confidence < 0.7),
+    complexityHotspots: deepAnalysis.findings.filter(f => f.complexity === 'high'),
+    patternDeviations: deepAnalysis.patterns.filter(p => p.consistency < 0.8),
+    unclearDependencies: deepAnalysis.dependencies.filter(d => d.type === 'implicit'),
+    potentialIssues: deepAnalysis.recommendations.filter(r => r.priority === 'investigate'),
+    depthOpportunities: deepAnalysis.sections.filter(s => s.has_more_detail)
+  };
+}
+
+const discoveries = extractDiscoveries(deepAnalysis);
+```
+
+### Step 2: Build Dynamic Questions
+
+Questions emerge from discoveries, NOT predetermined:
+
+```javascript
+function buildDynamicQuestions(discoveries, config) {
+  const questions = [];
+
+  if (discoveries.ambiguities.length > 0) {
+    questions.push({
+      question: `Analysis found ambiguity in "${discoveries.ambiguities[0].area}". Which interpretation is correct?`,
+      header: "Clarify",
+      options: discoveries.ambiguities[0].interpretations
+    });
+  }
+
+  if (discoveries.complexityHotspots.length > 0) {
+    questions.push({
+      question: `These areas have high complexity. Which would you like explained?`,
+      header: "Deep-Dive",
+      multiSelect: true,
+      options: discoveries.complexityHotspots.slice(0, 4).map(h => ({
+        label: h.name,
+        description: h.summary
+      }))
+    });
+  }
+
+  if (discoveries.patternDeviations.length > 0) {
+    questions.push({
+      question: `Found pattern deviations. Should these be highlighted in the report?`,
+      header: "Patterns",
+      options: [
+        {label: "Yes, include analysis", description: "Add section explaining deviations"},
+        {label: "No, skip", description: "Omit from report"}
+      ]
+    });
+  }
+
+  // Always include action question
+  questions.push({
+    question: "How would you like to proceed?",
+    header: "Action",
+    options: [
+      {label: "Continue refining", description: "Address more discoveries"},
+      {label: "Finalize report", description: "Generate final output"},
+      {label: "Change scope", description: "Modify analysis scope"}
+    ]
+  });
+
+  return questions.slice(0, 4); // Max 4 questions
+}
+```
+
+### Step 3: Apply Refinements
+
+```javascript
+if (userAction === "Continue refining") {
+  // Apply selected refinements
+  for (const selection of userSelections) {
+    applyRefinement(selection, deepAnalysis, report);
+  }
+  
+  // Save iteration
+  Write(`${outputDir}/iterations/iteration-${iterationCount}.json`, {
+    timestamp: new Date().toISOString(),
+    discoveries: discoveries,
+    selections: userSelections,
+    changes: appliedChanges
+  });
+  
+  // Loop back to Step 1
+  iterationCount++;
+  goto Step1;
+}
+
+if (userAction === "Finalize report") {
+  // Proceed to final output
+  goto FinalizeReport;
+}
+```
+
+### Step 4: Finalize Report
+
+```javascript
+// Add iteration history to report metadata
+const finalReport = {
+  ...report,
+  metadata: {
+    iterations: iterationCount,
+    refinements_applied: allRefinements,
+    final_discoveries: discoveries
+  }
+};
+
+Write(`${outputDir}/${config.type.toUpperCase()}-REPORT.md`, finalReport);
+```
+
+## Output
+
+Updated report with refinements, saved iterations to `iterations/` folder.

package/.claude/skills/project-analyze/specs/quality-standards.md

@@ -0,0 +1,115 @@
+# Quality Standards
+
+Quality gates and requirements for project analysis reports.
+
+## When to Use
+
+| Phase | Usage | Section |
+|-------|-------|---------|
+| Phase 4 | Check report structure before assembly | Report Requirements |
+| Phase 5 | Validate before each iteration | Quality Gates |
+| Phase 5 | Handle failures during refinement | Error Handling |
+
+---
+
+## Report Requirements
+
+**Use in Phase 4**: Ensure report includes all required elements.
+
+| Requirement | Check | How to Fix |
+|-------------|-------|------------|
+| Executive Summary | 3-5 key takeaways | Extract from analysis findings |
+| Visual diagrams | Valid Mermaid syntax | Use `../_shared/mermaid-utils.md` |
+| Code references | `file:line` format | Link to actual source locations |
+| Recommendations | Actionable, specific | Derive from analysis insights |
+| Consistent depth | Match user's depth level | Adjust detail per config.depth |
+
+---
+
+## Quality Gates
+
+**Use in Phase 5**: Run these checks before asking user questions.
+
+```javascript
+function runQualityGates(report, config, diagrams) {
+  const gates = [
+    {
+      name: "focus_areas_covered",
+      check: () => config.focus_areas.every(area =>
+        report.toLowerCase().includes(area.toLowerCase())
+      ),
+      fix: "Re-analyze missing focus areas"
+    },
+    {
+      name: "diagrams_valid",
+      check: () => diagrams.every(d => d.valid),
+      fix: "Regenerate failed diagrams with mermaid-utils"
+    },
+    {
+      name: "code_refs_accurate",
+      check: () => extractCodeRefs(report).every(ref => fileExists(ref)),
+      fix: "Update invalid file references"
+    },
+    {
+      name: "no_placeholders",
+      check: () => !report.includes('[TODO]') && !report.includes('[PLACEHOLDER]'),
+      fix: "Fill in all placeholder content"
+    },
+    {
+      name: "recommendations_specific",
+      check: () => !report.includes('consider') || report.includes('specifically'),
+      fix: "Make recommendations project-specific"
+    }
+  ];
+
+  const results = gates.map(g => ({...g, passed: g.check()}));
+  const allPassed = results.every(r => r.passed);
+
+  return { allPassed, results };
+}
+```
+
+**Integration with Phase 5**:
+```javascript
+// In 05-iterative-refinement.md
+const { allPassed, results } = runQualityGates(report, config, diagrams);
+
+if (allPassed) {
+  // All gates passed → ask user to confirm or finalize
+} else {
+  // Gates failed → include failed gates in discovery questions
+  const failedGates = results.filter(r => !r.passed);
+  discoveries.qualityIssues = failedGates;
+}
+```
+
+---
+
+## Error Handling
+
+**Use when**: Encountering errors during any phase.
+
+| Error | Detection | Recovery |
+|-------|-----------|----------|
+| CLI timeout | Bash exits with timeout | Reduce scope via `config.scope`, retry |
+| Exploration failure | Agent returns error | Fall back to `Read` + `Grep` directly |
+| User abandons | User selects "cancel" | Save to `iterations/`, allow resume |
+| Invalid scope path | Path doesn't exist | `AskUserQuestion` to correct path |
+| Diagram validation fails | `validateMermaidSyntax` returns issues | Regenerate with stricter escaping |
+
+**Recovery Flow**:
+```javascript
+try {
+  await executePhase(phase);
+} catch (error) {
+  const recovery = ERROR_HANDLERS[error.type];
+  if (recovery) {
+    await recovery.action(error, config);
+    // Retry phase or continue
+  } else {
+    // Save progress and ask user
+    Write(`${outputDir}/error-state.json`, { phase, error, config });
+    AskUserQuestion({ question: "遇到错误，如何处理？", ... });
+  }
+}
+```