claude-code-workflow 6.3.26 → 6.3.28

package/.claude/skills/skill-tuning/phases/actions/action-diagnose-docs.md

@@ -0,0 +1,299 @@
+# Action: Diagnose Documentation Structure
+
+检测目标 skill 中的文档冗余和冲突问题。
+
+## Purpose
+
+- 检测重复定义（State Schema、映射表、类型定义等）
+- 检测冲突定义（优先级定义不一致、实现与文档漂移等）
+- 生成合并和解决冲突的建议
+
+## Preconditions
+
+- [ ] `state.status === 'running'`
+- [ ] `state.target_skill !== null`
+- [ ] `!state.diagnosis.docs`
+- [ ] 用户指定 focus_areas 包含 'docs' 或 'all'，或需要全面诊断
+
+## Detection Patterns
+
+### DOC-RED-001: 核心定义重复
+
+检测 State Schema、核心接口等在多处定义：
+
+```javascript
+async function detectDefinitionDuplicates(skillPath) {
+  const patterns = [
+    { name: 'state_schema', regex: /interface\s+(TuningState|State)\s*\{/g },
+    { name: 'fix_strategy', regex: /type\s+FixStrategy\s*=/g },
+    { name: 'issue_type', regex: /type:\s*['"]?(context_explosion|memory_loss|dataflow_break)/g }
+  ];
+  
+  const files = Glob('**/*.md', { cwd: skillPath });
+  const duplicates = [];
+  
+  for (const pattern of patterns) {
+    const matches = [];
+    for (const file of files) {
+      const content = Read(`${skillPath}/${file}`);
+      if (pattern.regex.test(content)) {
+        matches.push({ file, pattern: pattern.name });
+      }
+    }
+    if (matches.length > 1) {
+      duplicates.push({
+        type: pattern.name,
+        files: matches.map(m => m.file),
+        severity: 'high'
+      });
+    }
+  }
+  
+  return duplicates;
+}
+```
+
+### DOC-RED-002: 硬编码配置重复
+
+检测 action 文件中硬编码与 spec 文档的重复：
+
+```javascript
+async function detectHardcodedDuplicates(skillPath) {
+  const actionFiles = Glob('phases/actions/*.md', { cwd: skillPath });
+  const specFiles = Glob('specs/*.md', { cwd: skillPath });
+  
+  const duplicates = [];
+  
+  for (const actionFile of actionFiles) {
+    const content = Read(`${skillPath}/${actionFile}`);
+    
+    // 检测硬编码的映射对象
+    const hardcodedPatterns = [
+      /const\s+\w*[Mm]apping\s*=\s*\{/g,
+      /patternMapping\s*=\s*\{/g,
+      /strategyMapping\s*=\s*\{/g
+    ];
+    
+    for (const pattern of hardcodedPatterns) {
+      if (pattern.test(content)) {
+        duplicates.push({
+          type: 'hardcoded_mapping',
+          file: actionFile,
+          description: '硬编码映射可能与 specs/ 中的定义重复',
+          severity: 'high'
+        });
+      }
+    }
+  }
+  
+  return duplicates;
+}
+```
+
+### DOC-CON-001: 优先级定义冲突
+
+检测 P0-P3 等优先级在不同文件中的定义不一致：
+
+```javascript
+async function detectPriorityConflicts(skillPath) {
+  const files = Glob('**/*.md', { cwd: skillPath });
+  const priorityDefs = {};
+  
+  const priorityPattern = /\*\*P(\d+)\*\*[:\s]+([^\|]+)/g;
+  
+  for (const file of files) {
+    const content = Read(`${skillPath}/${file}`);
+    let match;
+    while ((match = priorityPattern.exec(content)) !== null) {
+      const priority = `P${match[1]}`;
+      const definition = match[2].trim();
+      
+      if (!priorityDefs[priority]) {
+        priorityDefs[priority] = [];
+      }
+      priorityDefs[priority].push({ file, definition });
+    }
+  }
+  
+  const conflicts = [];
+  for (const [priority, defs] of Object.entries(priorityDefs)) {
+    const uniqueDefs = [...new Set(defs.map(d => d.definition))];
+    if (uniqueDefs.length > 1) {
+      conflicts.push({
+        key: priority,
+        definitions: defs,
+        severity: 'critical'
+      });
+    }
+  }
+  
+  return conflicts;
+}
+```
+
+### DOC-CON-002: 实现与文档漂移
+
+检测硬编码与文档表格的不一致：
+
+```javascript
+async function detectImplementationDrift(skillPath) {
+  // 比较 category-mappings.json 与 specs/*.md 中的表格
+  const mappingsFile = `${skillPath}/specs/category-mappings.json`;
+  
+  if (!fileExists(mappingsFile)) {
+    return []; // 无集中配置，跳过
+  }
+  
+  const mappings = JSON.parse(Read(mappingsFile));
+  const conflicts = [];
+  
+  // 与 dimension-mapping.md 对比
+  const dimMapping = Read(`${skillPath}/specs/dimension-mapping.md`);
+  
+  for (const [category, config] of Object.entries(mappings.categories)) {
+    // 检查策略是否在文档中提及
+    for (const strategy of config.strategies || []) {
+      if (!dimMapping.includes(strategy)) {
+        conflicts.push({
+          type: 'mapping',
+          key: `${category}.strategies`,
+          issue: `策略 ${strategy} 在 JSON 中定义但未在文档中提及`
+        });
+      }
+    }
+  }
+  
+  return conflicts;
+}
+```
+
+## Execution
+
+```javascript
+async function executeDiagnosis(state, workDir) {
+  console.log('=== Diagnosing Documentation Structure ===');
+  
+  const skillPath = state.target_skill.path;
+  const issues = [];
+  
+  // 1. 检测冗余
+  const definitionDups = await detectDefinitionDuplicates(skillPath);
+  const hardcodedDups = await detectHardcodedDuplicates(skillPath);
+  
+  for (const dup of [...definitionDups, ...hardcodedDups]) {
+    issues.push({
+      id: `DOC-RED-${issues.length + 1}`,
+      type: 'doc_redundancy',
+      severity: dup.severity,
+      location: { files: dup.files || [dup.file] },
+      description: dup.description || `${dup.type} 在多处定义`,
+      evidence: dup.files || [dup.file],
+      root_cause: '缺乏单一真相来源',
+      impact: '维护困难，易产生不一致',
+      suggested_fix: 'consolidate_to_ssot'
+    });
+  }
+  
+  // 2. 检测冲突
+  const priorityConflicts = await detectPriorityConflicts(skillPath);
+  const driftConflicts = await detectImplementationDrift(skillPath);
+  
+  for (const conflict of priorityConflicts) {
+    issues.push({
+      id: `DOC-CON-${issues.length + 1}`,
+      type: 'doc_conflict',
+      severity: 'critical',
+      location: { files: conflict.definitions.map(d => d.file) },
+      description: `${conflict.key} 在不同文件中定义不一致`,
+      evidence: conflict.definitions.map(d => `${d.file}: ${d.definition}`),
+      root_cause: '定义更新后未同步',
+      impact: '行为不可预测',
+      suggested_fix: 'reconcile_conflicting_definitions'
+    });
+  }
+  
+  // 3. 生成报告
+  const severity = issues.some(i => i.severity === 'critical') ? 'critical' :
+                   issues.some(i => i.severity === 'high') ? 'high' :
+                   issues.length > 0 ? 'medium' : 'none';
+  
+  const result = {
+    status: 'completed',
+    issues_found: issues.length,
+    severity: severity,
+    execution_time_ms: Date.now() - startTime,
+    details: {
+      patterns_checked: ['DOC-RED-001', 'DOC-RED-002', 'DOC-CON-001', 'DOC-CON-002'],
+      patterns_matched: issues.map(i => i.id.split('-').slice(0, 2).join('-')),
+      evidence: issues.flatMap(i => i.evidence),
+      recommendations: generateRecommendations(issues)
+    },
+    redundancies: issues.filter(i => i.type === 'doc_redundancy'),
+    conflicts: issues.filter(i => i.type === 'doc_conflict')
+  };
+  
+  // 写入诊断结果
+  Write(`${workDir}/diagnosis/docs-diagnosis.json`, JSON.stringify(result, null, 2));
+  
+  return {
+    stateUpdates: {
+      'diagnosis.docs': result,
+      issues: [...state.issues, ...issues]
+    },
+    outputFiles: [`${workDir}/diagnosis/docs-diagnosis.json`],
+    summary: `文档诊断完成：发现 ${issues.length} 个问题 (${severity})`
+  };
+}
+
+function generateRecommendations(issues) {
+  const recommendations = [];
+  
+  if (issues.some(i => i.type === 'doc_redundancy')) {
+    recommendations.push('使用 consolidate_to_ssot 策略合并重复定义');
+    recommendations.push('考虑创建 specs/category-mappings.json 集中管理配置');
+  }
+  
+  if (issues.some(i => i.type === 'doc_conflict')) {
+    recommendations.push('使用 reconcile_conflicting_definitions 策略解决冲突');
+    recommendations.push('建立文档同步检查机制');
+  }
+  
+  return recommendations;
+}
+```
+
+## Output
+
+### State Updates
+
+```javascript
+{
+  stateUpdates: {
+    'diagnosis.docs': {
+      status: 'completed',
+      issues_found: N,
+      severity: 'critical|high|medium|low|none',
+      redundancies: [...],
+      conflicts: [...]
+    },
+    issues: [...existingIssues, ...newIssues]
+  }
+}
+```
+
+### Output Files
+
+- `${workDir}/diagnosis/docs-diagnosis.json` - 完整诊断结果
+
+## Error Handling
+
+| Error | Recovery |
+|-------|----------|
+| 文件读取失败 | 记录警告，继续处理其他文件 |
+| 正则匹配超时 | 跳过该模式，记录 skipped |
+| JSON 解析失败 | 跳过配置对比，仅进行模式检测 |
+
+## Next Actions
+
+- 如果发现 critical 问题 → 优先进入 action-propose-fixes
+- 如果无问题 → 继续下一个诊断或 action-generate-report

package/.claude/skills/skill-tuning/phases/actions/action-diagnose-memory.md

@@ -0,0 +1,269 @@
+# Action: Diagnose Long-tail Forgetting
+
+Analyze target skill for long-tail effect and constraint forgetting issues.
+
+## Purpose
+
+- Detect loss of early instructions in long execution chains
+- Identify missing constraint propagation mechanisms
+- Find weak goal alignment between phases
+- Measure instruction retention across phases
+
+## Preconditions
+
+- [ ] state.status === 'running'
+- [ ] state.target_skill.path is set
+- [ ] 'memory' in state.focus_areas OR state.focus_areas is empty
+
+## Detection Patterns
+
+### Pattern 1: Missing Constraint References
+
+```regex
+# Phases that don't reference original requirements
+# Look for absence of: requirements, constraints, original, initial, user_request
+```
+
+### Pattern 2: Goal Drift
+
+```regex
+# Later phases focus on immediate task without global context
+/\[TASK\][^[]*(?!\[CONSTRAINTS\]|\[REQUIREMENTS\])/
+```
+
+### Pattern 3: No Checkpoint Mechanism
+
+```regex
+# Absence of state preservation at key points
+# Look for lack of: checkpoint, snapshot, preserve, restore
+```
+
+### Pattern 4: Implicit State Passing
+
+```regex
+# State passed implicitly through conversation rather than explicitly
+/(?<!state\.)context\./
+```
+
+## Execution
+
+```javascript
+async function execute(state, workDir) {
+  const skillPath = state.target_skill.path;
+  const startTime = Date.now();
+  const issues = [];
+  const evidence = [];
+
+  console.log(`Diagnosing long-tail forgetting in ${skillPath}...`);
+
+  // 1. Analyze phase chain for constraint propagation
+  const phaseFiles = Glob(`${skillPath}/phases/*.md`)
+    .filter(f => !f.includes('orchestrator') && !f.includes('state-schema'))
+    .sort();
+
+  // Extract phase order (for sequential) or action dependencies (for autonomous)
+  const isAutonomous = state.target_skill.execution_mode === 'autonomous';
+
+  // 2. Check each phase for constraint awareness
+  let firstPhaseConstraints = [];
+
+  for (let i = 0; i < phaseFiles.length; i++) {
+    const file = phaseFiles[i];
+    const content = Read(file);
+    const relativePath = file.replace(skillPath + '/', '');
+    const phaseNum = i + 1;
+
+    // Extract constraints from first phase
+    if (i === 0) {
+      const constraintMatch = content.match(/\[CONSTRAINTS?\]([^[]*)/i);
+      if (constraintMatch) {
+        firstPhaseConstraints = constraintMatch[1]
+          .split('\n')
+          .filter(l => l.trim().startsWith('-'))
+          .map(l => l.trim().replace(/^-\s*/, ''));
+      }
+    }
+
+    // Check if later phases reference original constraints
+    if (i > 0 && firstPhaseConstraints.length > 0) {
+      const mentionsConstraints = firstPhaseConstraints.some(c =>
+        content.toLowerCase().includes(c.toLowerCase().slice(0, 20))
+      );
+
+      if (!mentionsConstraints) {
+        issues.push({
+          id: `MEM-${issues.length + 1}`,
+          type: 'memory_loss',
+          severity: 'high',
+          location: { file: relativePath, phase: `Phase ${phaseNum}` },
+          description: `Phase ${phaseNum} does not reference original constraints`,
+          evidence: [`Original constraints: ${firstPhaseConstraints.slice(0, 3).join(', ')}`],
+          root_cause: 'Constraint information not propagated to later phases',
+          impact: 'May produce output violating original requirements',
+          suggested_fix: 'Add explicit constraint injection or reference to state.original_constraints'
+        });
+        evidence.push({
+          file: relativePath,
+          pattern: 'missing_constraint_reference',
+          context: `Phase ${phaseNum} of ${phaseFiles.length}`,
+          severity: 'high'
+        });
+      }
+    }
+
+    // Check for goal drift - task without constraints
+    const hasTask = /\[TASK\]/i.test(content);
+    const hasConstraints = /\[CONSTRAINTS?\]|\[REQUIREMENTS?\]|\[RULES?\]/i.test(content);
+
+    if (hasTask && !hasConstraints && i > 1) {
+      issues.push({
+        id: `MEM-${issues.length + 1}`,
+        type: 'memory_loss',
+        severity: 'medium',
+        location: { file: relativePath },
+        description: 'Phase has TASK but no CONSTRAINTS/RULES section',
+        evidence: ['Task defined without boundary constraints'],
+        root_cause: 'Agent may not adhere to global constraints',
+        impact: 'Potential goal drift from original intent',
+        suggested_fix: 'Add [CONSTRAINTS] section referencing global rules'
+      });
+    }
+
+    // Check for checkpoint mechanism
+    const hasCheckpoint = /checkpoint|snapshot|preserve|savepoint/i.test(content);
+    const isKeyPhase = i === Math.floor(phaseFiles.length / 2) || i === phaseFiles.length - 1;
+
+    if (isKeyPhase && !hasCheckpoint && phaseFiles.length > 3) {
+      issues.push({
+        id: `MEM-${issues.length + 1}`,
+        type: 'memory_loss',
+        severity: 'low',
+        location: { file: relativePath },
+        description: 'Key phase without checkpoint mechanism',
+        evidence: [`Phase ${phaseNum} is a key milestone but has no state preservation`],
+        root_cause: 'Cannot recover from failures or verify constraint adherence',
+        impact: 'No rollback capability if constraints violated',
+        suggested_fix: 'Add checkpoint before major state changes'
+      });
+    }
+  }
+
+  // 3. Check for explicit state schema with constraints field
+  const stateSchemaFile = Glob(`${skillPath}/phases/state-schema.md`)[0];
+  if (stateSchemaFile) {
+    const schemaContent = Read(stateSchemaFile);
+    const hasConstraintsField = /constraints|requirements|original_request/i.test(schemaContent);
+
+    if (!hasConstraintsField) {
+      issues.push({
+        id: `MEM-${issues.length + 1}`,
+        type: 'memory_loss',
+        severity: 'medium',
+        location: { file: 'phases/state-schema.md' },
+        description: 'State schema lacks constraints/requirements field',
+        evidence: ['No dedicated field for preserving original requirements'],
+        root_cause: 'State structure does not support constraint persistence',
+        impact: 'Constraints may be lost during state transitions',
+        suggested_fix: 'Add original_requirements field to state schema'
+      });
+    }
+  }
+
+  // 4. Check SKILL.md for constraint enforcement in execution flow
+  const skillMd = Read(`${skillPath}/SKILL.md`);
+  const hasConstraintVerification = /constraint.*verif|verif.*constraint|quality.*gate/i.test(skillMd);
+
+  if (!hasConstraintVerification && phaseFiles.length > 3) {
+    issues.push({
+      id: `MEM-${issues.length + 1}`,
+      type: 'memory_loss',
+      severity: 'medium',
+      location: { file: 'SKILL.md' },
+      description: 'No constraint verification step in execution flow',
+      evidence: ['Execution flow lacks quality gate or constraint check'],
+      root_cause: 'No mechanism to verify output matches original intent',
+      impact: 'Constraint violations may go undetected',
+      suggested_fix: 'Add verification phase comparing output to original requirements'
+    });
+  }
+
+  // 5. Calculate severity
+  const criticalCount = issues.filter(i => i.severity === 'critical').length;
+  const highCount = issues.filter(i => i.severity === 'high').length;
+  const severity = criticalCount > 0 ? 'critical' :
+                   highCount > 2 ? 'high' :
+                   highCount > 0 ? 'medium' :
+                   issues.length > 0 ? 'low' : 'none';
+
+  // 6. Write diagnosis result
+  const diagnosisResult = {
+    status: 'completed',
+    issues_found: issues.length,
+    severity: severity,
+    execution_time_ms: Date.now() - startTime,
+    details: {
+      patterns_checked: [
+        'constraint_propagation',
+        'goal_drift',
+        'checkpoint_mechanism',
+        'state_schema_constraints'
+      ],
+      patterns_matched: evidence.map(e => e.pattern),
+      evidence: evidence,
+      phase_analysis: {
+        total_phases: phaseFiles.length,
+        first_phase_constraints: firstPhaseConstraints.length,
+        phases_with_constraint_ref: phaseFiles.length - issues.filter(i =>
+          i.description.includes('does not reference')).length
+      },
+      recommendations: [
+        highCount > 0 ? 'Implement constraint injection at each phase' : null,
+        issues.some(i => i.description.includes('checkpoint'))
+          ? 'Add checkpoint/restore mechanism' : null,
+        issues.some(i => i.description.includes('State schema'))
+          ? 'Add original_requirements to state schema' : null
+      ].filter(Boolean)
+    }
+  };
+
+  Write(`${workDir}/diagnosis/memory-diagnosis.json`,
+        JSON.stringify(diagnosisResult, null, 2));
+
+  return {
+    stateUpdates: {
+      'diagnosis.memory': diagnosisResult,
+      issues: [...state.issues, ...issues]
+    },
+    outputFiles: [`${workDir}/diagnosis/memory-diagnosis.json`],
+    summary: `Memory diagnosis: ${issues.length} issues found (severity: ${severity})`
+  };
+}
+```
+
+## State Updates
+
+```javascript
+return {
+  stateUpdates: {
+    'diagnosis.memory': {
+      status: 'completed',
+      issues_found: <count>,
+      severity: '<critical|high|medium|low|none>',
+      // ... full diagnosis result
+    },
+    issues: [...existingIssues, ...newIssues]
+  }
+};
+```
+
+## Error Handling
+
+| Error Type | Recovery |
+|------------|----------|
+| Phase file read error | Skip file, continue analysis |
+| No phases found | Report as structure issue |
+
+## Next Actions
+
+- Success: action-diagnose-dataflow (or next in focus_areas)
+- Skipped: If 'memory' not in focus_areas