feat: Enhance documentation diagnosis and category mapping

- Introduced action to diagnose documentation structure, identifying redundancies and conflicts. - Added centralized category mappings in JSON format for improved detection and strategy application. - Updated existing functions to utilize new mappings for taxonomy and strategy matching. - Implemented new detection patterns for documentation redundancy and conflict. - Expanded state schema to include documentation diagnosis results. - Enhanced severity criteria and strategy selection guide to accommodate new documentation issues.
2026-02-14 02:42:04 +08:00 · 2026-01-14 21:07:52 +08:00
parent 1f5ce9c03a
commit 266f6f11ec
10 changed files with 1340 additions and 946 deletions
--- a/.claude/skills/skill-tuning/specs/category-mappings.json
+++ b/.claude/skills/skill-tuning/specs/category-mappings.json
@@ -0,0 +1,263 @@
+{
+  "version": "1.0.0",
+  "description": "Centralized category mappings for skill-tuning analysis and fix proposal",
+  "categories": {
+    "authoring_principles_violation": {
+      "pattern_ids": ["APV-001", "APV-002", "APV-003", "APV-004", "APV-005", "APV-006"],
+      "severity_hint": "critical",
+      "strategies": ["eliminate_intermediate_files", "minimize_state", "context_passing"],
+      "risk_levels": ["low", "low", "low"],
+      "detection_focus": "Intermediate files, state bloat, file relay patterns",
+      "priority_order": [1, 2, 3]
+    },
+    "context_explosion": {
+      "pattern_ids": ["CTX-001", "CTX-002", "CTX-003", "CTX-004", "CTX-005"],
+      "severity_hint": "high",
+      "strategies": ["sliding_window", "path_reference", "context_summarization", "structured_state"],
+      "risk_levels": ["low", "low", "low", "medium"],
+      "detection_focus": "Token accumulation, content passing patterns",
+      "priority_order": [1, 2, 3, 4]
+    },
+    "memory_loss": {
+      "pattern_ids": ["MEM-001", "MEM-002", "MEM-003", "MEM-004", "MEM-005"],
+      "severity_hint": "high",
+      "strategies": ["constraint_injection", "state_constraints_field", "checkpoint_restore", "goal_embedding"],
+      "risk_levels": ["low", "low", "low", "medium"],
+      "detection_focus": "Constraint propagation, checkpoint mechanisms",
+      "priority_order": [1, 2, 3, 4]
+    },
+    "dataflow_break": {
+      "pattern_ids": ["DF-001", "DF-002", "DF-003", "DF-004", "DF-005"],
+      "severity_hint": "critical",
+      "strategies": ["state_centralization", "schema_enforcement", "field_normalization"],
+      "risk_levels": ["medium", "low", "low"],
+      "detection_focus": "State storage, schema validation",
+      "priority_order": [1, 2, 3]
+    },
+    "agent_failure": {
+      "pattern_ids": ["AGT-001", "AGT-002", "AGT-003", "AGT-004", "AGT-005", "AGT-006"],
+      "severity_hint": "high",
+      "strategies": ["error_wrapping", "result_validation", "flatten_nesting"],
+      "risk_levels": ["low", "low", "medium"],
+      "detection_focus": "Error handling, result validation",
+      "priority_order": [1, 2, 3]
+    },
+    "prompt_quality": {
+      "pattern_ids": [],
+      "severity_hint": "medium",
+      "strategies": ["structured_prompt", "output_schema", "grounding_context", "format_enforcement"],
+      "risk_levels": ["low", "low", "medium", "low"],
+      "detection_focus": null,
+      "needs_gemini_analysis": true,
+      "priority_order": [1, 2, 3, 4]
+    },
+    "architecture": {
+      "pattern_ids": [],
+      "severity_hint": "medium",
+      "strategies": ["phase_decomposition", "interface_contracts", "plugin_architecture", "state_machine"],
+      "risk_levels": ["medium", "medium", "high", "medium"],
+      "detection_focus": null,
+      "needs_gemini_analysis": true,
+      "priority_order": [1, 2, 3, 4]
+    },
+    "performance": {
+      "pattern_ids": ["CTX-001", "CTX-003"],
+      "severity_hint": "medium",
+      "strategies": ["token_budgeting", "parallel_execution", "result_caching", "lazy_loading"],
+      "risk_levels": ["low", "low", "low", "low"],
+      "detection_focus": "Reuses context explosion detection",
+      "priority_order": [1, 2, 3, 4]
+    },
+    "error_handling": {
+      "pattern_ids": ["AGT-001", "AGT-002"],
+      "severity_hint": "medium",
+      "strategies": ["graceful_degradation", "error_propagation", "structured_logging", "error_context"],
+      "risk_levels": ["low", "low", "low", "low"],
+      "detection_focus": "Reuses agent failure detection",
+      "priority_order": [1, 2, 3, 4]
+    },
+    "output_quality": {
+      "pattern_ids": [],
+      "severity_hint": "medium",
+      "strategies": ["quality_gates", "output_validation", "template_enforcement", "completeness_check"],
+      "risk_levels": ["low", "low", "low", "low"],
+      "detection_focus": null,
+      "needs_gemini_analysis": true,
+      "priority_order": [1, 2, 3, 4]
+    },
+    "user_experience": {
+      "pattern_ids": [],
+      "severity_hint": "low",
+      "strategies": ["progress_tracking", "status_communication", "interactive_checkpoints", "guided_workflow"],
+      "risk_levels": ["low", "low", "low", "low"],
+      "detection_focus": null,
+      "needs_gemini_analysis": true,
+      "priority_order": [1, 2, 3, 4]
+    }
+  },
+  "keywords": {
+    "chinese": {
+      "token": "context_explosion",
+      "上下文": "context_explosion",
+      "爆炸": "context_explosion",
+      "太长": "context_explosion",
+      "超限": "context_explosion",
+      "膨胀": "context_explosion",
+      "遗忘": "memory_loss",
+      "忘记": "memory_loss",
+      "指令丢失": "memory_loss",
+      "约束消失": "memory_loss",
+      "目标漂移": "memory_loss",
+      "状态": "dataflow_break",
+      "数据": "dataflow_break",
+      "格式": "dataflow_break",
+      "不一致": "dataflow_break",
+      "丢失": "dataflow_break",
+      "损坏": "dataflow_break",
+      "agent": "agent_failure",
+      "子任务": "agent_failure",
+      "失败": "agent_failure",
+      "嵌套": "agent_failure",
+      "调用": "agent_failure",
+      "协调": "agent_failure",
+      "慢": "performance",
+      "性能": "performance",
+      "效率": "performance",
+      "延迟": "performance",
+      "提示词": "prompt_quality",
+      "输出不稳定": "prompt_quality",
+      "幻觉": "prompt_quality",
+      "架构": "architecture",
+      "结构": "architecture",
+      "模块": "architecture",
+      "耦合": "architecture",
+      "扩展": "architecture",
+      "错误": "error_handling",
+      "异常": "error_handling",
+      "恢复": "error_handling",
+      "降级": "error_handling",
+      "崩溃": "error_handling",
+      "输出": "output_quality",
+      "质量": "output_quality",
+      "验证": "output_quality",
+      "不完整": "output_quality",
+      "交互": "user_experience",
+      "体验": "user_experience",
+      "进度": "user_experience",
+      "反馈": "user_experience",
+      "不清晰": "user_experience",
+      "中间文件": "authoring_principles_violation",
+      "临时文件": "authoring_principles_violation",
+      "文件中转": "authoring_principles_violation",
+      "state膨胀": "authoring_principles_violation"
+    },
+    "english": {
+      "token": "context_explosion",
+      "context": "context_explosion",
+      "explosion": "context_explosion",
+      "overflow": "context_explosion",
+      "bloat": "context_explosion",
+      "forget": "memory_loss",
+      "lost": "memory_loss",
+      "drift": "memory_loss",
+      "constraint": "memory_loss",
+      "goal": "memory_loss",
+      "state": "dataflow_break",
+      "data": "dataflow_break",
+      "format": "dataflow_break",
+      "inconsistent": "dataflow_break",
+      "corrupt": "dataflow_break",
+      "agent": "agent_failure",
+      "subtask": "agent_failure",
+      "fail": "agent_failure",
+      "nested": "agent_failure",
+      "call": "agent_failure",
+      "coordinate": "agent_failure",
+      "slow": "performance",
+      "performance": "performance",
+      "efficiency": "performance",
+      "latency": "performance",
+      "prompt": "prompt_quality",
+      "unstable": "prompt_quality",
+      "hallucination": "prompt_quality",
+      "architecture": "architecture",
+      "structure": "architecture",
+      "module": "architecture",
+      "coupling": "architecture",
+      "error": "error_handling",
+      "exception": "error_handling",
+      "recovery": "error_handling",
+      "crash": "error_handling",
+      "output": "output_quality",
+      "quality": "output_quality",
+      "validation": "output_quality",
+      "incomplete": "output_quality",
+      "interaction": "user_experience",
+      "ux": "user_experience",
+      "progress": "user_experience",
+      "feedback": "user_experience",
+      "intermediate": "authoring_principles_violation",
+      "temp": "authoring_principles_violation",
+      "relay": "authoring_principles_violation"
+    }
+  },
+  "category_labels": {
+    "context_explosion": "Context Explosion",
+    "memory_loss": "Long-tail Forgetting",
+    "dataflow_break": "Data Flow Disruption",
+    "agent_failure": "Agent Coordination Failure",
+    "prompt_quality": "Prompt Quality",
+    "architecture": "Architecture",
+    "performance": "Performance",
+    "error_handling": "Error Handling",
+    "output_quality": "Output Quality",
+    "user_experience": "User Experience",
+    "authoring_principles_violation": "Authoring Principles Violation",
+    "custom": "Custom"
+  },
+  "category_labels_chinese": {
+    "context_explosion": "Context Explosion",
+    "memory_loss": "Long-tail Forgetting",
+    "dataflow_break": "Data Flow Disruption",
+    "agent_failure": "Agent Coordination Failure",
+    "prompt_quality": "Prompt Quality",
+    "architecture": "Architecture Issues",
+    "performance": "Performance Issues",
+    "error_handling": "Error Handling",
+    "output_quality": "Output Quality",
+    "user_experience": "User Experience",
+    "authoring_principles_violation": "Authoring Principles Violation",
+    "custom": "Other Issues"
+  },
+  "category_descriptions": {
+    "context_explosion": "Token accumulation causing prompt size to grow unbounded",
+    "memory_loss": "Early instructions or constraints lost in later phases",
+    "dataflow_break": "State data inconsistency between phases",
+    "agent_failure": "Sub-agent call failures or abnormal results",
+    "prompt_quality": "Vague prompts causing unstable outputs",
+    "architecture": "Improper phase division or module structure",
+    "performance": "Slow execution or high token consumption",
+    "error_handling": "Incomplete error recovery mechanisms",
+    "output_quality": "Output validation or completeness issues",
+    "user_experience": "Interaction or feedback clarity issues",
+    "authoring_principles_violation": "Violation of skill authoring principles",
+    "custom": "Requires custom analysis"
+  },
+  "fix_priority_order": {
+    "P0": ["dataflow_break", "authoring_principles_violation"],
+    "P1": ["agent_failure"],
+    "P2": ["context_explosion"],
+    "P3": ["memory_loss"]
+  },
+  "cross_category_dependencies": {
+    "context_explosion": ["memory_loss"],
+    "dataflow_break": ["agent_failure"],
+    "agent_failure": ["context_explosion"]
+  },
+  "fallback": {
+    "strategies": ["custom"],
+    "risk_levels": ["medium"],
+    "has_fix": true,
+    "needs_gemini_analysis": true
+  }
+}
--- a/.claude/skills/skill-tuning/specs/dimension-mapping.md
+++ b/.claude/skills/skill-tuning/specs/dimension-mapping.md
@@ -29,6 +29,8 @@
 | 错误, 异常, 恢复, 降级, 崩溃 | error, exception, recovery, crash | error_handling | agent_failure |
 | 输出, 质量, 格式, 验证, 不完整 | output, quality, validation, incomplete | output_quality | - |
 | 交互, 体验, 进度, 反馈, 不清晰 | interaction, ux, progress, feedback | user_experience | - |
+| 重复, 冗余, 多处定义, 相同内容 | duplicate, redundant, multiple definitions | doc_redundancy | - |
+| 冲突, 不一致, 定义不同, 矛盾 | conflict, inconsistent, mismatch, contradiction | doc_conflict | - |

 ### Matching Algorithm

@@ -86,6 +88,8 @@ function matchCategory(keywords) {
 | error_handling | AGT-001, AGT-002 | (复用 agent 检测) |
 | output_quality | - | (无内置检测，需 Gemini 分析) |
 | user_experience | - | (无内置检测，需 Gemini 分析) |
+| doc_redundancy | DOC-RED-001, DOC-RED-002, DOC-RED-003 | 重复定义检测 |
+| doc_conflict | DOC-CON-001, DOC-CON-002 | 冲突定义检测 |

 ---

@@ -101,6 +105,8 @@ function matchCategory(keywords) {
 | memory_loss | constraint_injection, state_constraints_field, checkpoint_restore, goal_embedding | Low-Medium |
 | dataflow_break | state_centralization, schema_enforcement, field_normalization | Low-Medium |
 | agent_failure | error_wrapping, result_validation, flatten_nesting | Low-Medium |
+| doc_redundancy | consolidate_to_ssot, centralize_mapping_config | Low-Medium |
+| doc_conflict | reconcile_conflicting_definitions | Low |

 ### Extended Categories (需 Gemini 生成策略)

--- a/.claude/skills/skill-tuning/specs/problem-taxonomy.md
+++ b/.claude/skills/skill-tuning/specs/problem-taxonomy.md
@@ -156,6 +156,53 @@ Classification of skill execution issues with detection patterns and severity cr

 ---

+### 5. Documentation Redundancy (P5)
+
+**Definition**: 同一定义（如 State Schema、映射表、类型定义）在多个文件中重复出现，导致维护困难和不一致风险。
+
+**Root Causes**:
+- 缺乏单一真相来源 (SSOT)
+- 复制粘贴代替引用
+- 硬编码配置代替集中管理
+
+**Detection Patterns**:
+
+| Pattern ID | Regex/Check | Description |
+|------------|-------------|-------------|
+| DOC-RED-001 | 跨文件语义比较 | 找到 State Schema 等核心概念的重复定义 |
+| DOC-RED-002 | 代码块 vs 规范表对比 | action 文件中硬编码与 spec 文档的重复 |
+| DOC-RED-003 | `/interface\s+(\w+)/` 同名扫描 | 多处定义的 interface/type |
+
+**Impact Levels**:
+- **High**: 核心定义（State Schema, 映射表）重复
+- **Medium**: 类型定义重复
+- **Low**: 示例代码重复
+
+---
+
+### 6. Documentation Conflict (P6)
+
+**Definition**: 同一概念在不同文件中定义不一致，导致行为不可预测和文档误导。
+
+**Root Causes**:
+- 定义更新后未同步其他位置
+- 实现与文档漂移
+- 缺乏一致性校验
+
+**Detection Patterns**:
+
+| Pattern ID | Regex/Check | Description |
+|------------|-------------|-------------|
+| DOC-CON-001 | 键值一致性校验 | 同一键（如优先级）在不同文件中值不同 |
+| DOC-CON-002 | 实现 vs 文档对比 | 硬编码配置与文档对应项不一致 |
+
+**Impact Levels**:
+- **Critical**: 优先级/类别定义冲突
+- **High**: 策略映射不一致
+- **Medium**: 示例与实际不符
+
+---
+
 ## Severity Criteria

 ### Global Severity Matrix
@@ -215,6 +262,8 @@ function calculateIssueSeverity(issue) {
 | Long-tail Forgetting | constraint_injection, state_constraints_field, checkpoint | 1, 2, 3 |
 | Data Flow Disruption | state_centralization, schema_enforcement, field_normalization | 1, 2, 3 |
 | Agent Coordination | error_wrapping, result_validation, flatten_nesting | 1, 2, 3 |
+| **Documentation Redundancy** | consolidate_to_ssot, centralize_mapping_config | 1, 2 |
+| **Documentation Conflict** | reconcile_conflicting_definitions | 1 |

 ---

--- a/.claude/skills/skill-tuning/specs/tuning-strategies.md
+++ b/.claude/skills/skill-tuning/specs/tuning-strategies.md
@@ -675,6 +675,144 @@ if (parsedA.needs_agent_b) {

 ---

+## Documentation Strategies
+
+文档去重和冲突解决策略。
+
+---
+
+### Strategy: consolidate_to_ssot
+
+**Purpose**: 将重复定义合并到单一真相来源 (Single Source of Truth)。
+
+**Implementation**:
+```javascript
+// 合并流程
+async function consolidateToSSOT(state, duplicates) {
+  // 1. 识别最完整的定义位置
+  const canonical = selectCanonicalSource(duplicates);
+
+  // 2. 确保规范位置包含完整定义
+  const fullDefinition = mergeDefinitions(duplicates);
+  Write(canonical.file, fullDefinition);
+
+  // 3. 替换其他位置为引用
+  for (const dup of duplicates.filter(d => d.file !== canonical.file)) {
+    const reference = generateReference(canonical.file, dup.type);
+    // 例如: "详见 [state-schema.md](phases/state-schema.md)"
+    replaceWithReference(dup.file, dup.location, reference);
+  }
+
+  return { canonical: canonical.file, removed: duplicates.length - 1 };
+}
+
+function selectCanonicalSource(duplicates) {
+  // 优先级: specs/ > phases/ > SKILL.md
+  const priority = ['specs/', 'phases/', 'SKILL.md'];
+  return duplicates.sort((a, b) => {
+    const aIdx = priority.findIndex(p => a.file.includes(p));
+    const bIdx = priority.findIndex(p => b.file.includes(p));
+    return aIdx - bIdx;
+  })[0];
+}
+```
+
+**Risk**: Low
+**Verification**:
+- 确认只有一处包含完整定义
+- 其他位置包含有效引用链接
+
+---
+
+### Strategy: centralize_mapping_config
+
+**Purpose**: 将硬编码配置提取到集中的 JSON 文件，代码改为加载配置。
+
+**Implementation**:
+```javascript
+// 1. 创建集中配置文件
+const config = {
+  version: "1.0.0",
+  categories: {
+    context_explosion: {
+      pattern_ids: ["CTX-001", "CTX-002"],
+      strategies: ["sliding_window", "path_reference"]
+    }
+    // ... 从硬编码中提取
+  }
+};
+Write('specs/category-mappings.json', JSON.stringify(config, null, 2));
+
+// 2. 重构代码加载配置
+// Before:
+function findTaxonomyMatch(category) {
+  const patternMapping = {
+    'context_explosion': { category: 'context_explosion', pattern_ids: [...] }
+    // 硬编码
+  };
+  return patternMapping[category];
+}
+
+// After:
+function findTaxonomyMatch(category) {
+  const mappings = JSON.parse(Read('specs/category-mappings.json'));
+  const config = mappings.categories[category];
+  if (!config) return null;
+  return { category, pattern_ids: config.pattern_ids, severity_hint: config.severity_hint };
+}
+```
+
+**Risk**: Medium (需要测试配置加载逻辑)
+**Verification**:
+- JSON 文件语法正确
+- 所有原硬编码的值都已迁移
+- 功能行为不变
+
+---
+
+### Strategy: reconcile_conflicting_definitions
+
+**Purpose**: 调和冲突的定义，由用户选择正确版本后统一更新。
+
+**Implementation**:
+```javascript
+async function reconcileConflicts(conflicts) {
+  for (const conflict of conflicts) {
+    // 1. 展示冲突给用户
+    const options = conflict.definitions.map(def => ({
+      label: `${def.file}: ${def.value}`,
+      description: `来自 ${def.file}`
+    }));
+
+    const choice = await AskUserQuestion({
+      questions: [{
+        question: `发现冲突定义: "${conflict.key}"，请选择正确版本`,
+        header: '冲突解决',
+        options: options,
+        multiSelect: false
+      }]
+    });
+
+    // 2. 更新所有文件为选中的版本
+    const selected = conflict.definitions[choice.index];
+    for (const def of conflict.definitions) {
+      if (def.file !== selected.file) {
+        updateDefinition(def.file, conflict.key, selected.value);
+      }
+    }
+  }
+
+  return { resolved: conflicts.length };
+}
+```
+
+**Risk**: Low (用户确认后执行)
+**Verification**:
+- 所有位置的定义一致
+- 无新冲突产生
+
+---
+
 ## Strategy Selection Guide

 ```
@@ -735,6 +873,13 @@ Issue Type: User Experience
 ├── unclear status? → status_communication
 ├── no feedback? → interactive_checkpoints
 └── confusing flow? → guided_workflow
+
+Issue Type: Documentation Redundancy
+├── 核心定义重复? → consolidate_to_ssot
+└── 硬编码配置重复? → centralize_mapping_config
+
+Issue Type: Documentation Conflict
+└── 定义不一致? → reconcile_conflicting_definitions
 ```

 ---