claude-code-workflow 6.3.26 → 6.3.28

package/.claude/skills/skill-tuning/phases/state-schema.md

@@ -0,0 +1,378 @@
+# State Schema
+
+Defines the state structure for skill-tuning orchestrator.
+
+## State Structure
+
+```typescript
+interface TuningState {
+  // === Core Status ===
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  started_at: string;           // ISO timestamp
+  updated_at: string;           // ISO timestamp
+
+  // === Target Skill Info ===
+  target_skill: {
+    name: string;               // e.g., "software-manual"
+    path: string;               // e.g., ".claude/skills/software-manual"
+    execution_mode: 'sequential' | 'autonomous';
+    phases: string[];           // List of phase files
+    specs: string[];            // List of spec files
+  };
+
+  // === User Input ===
+  user_issue_description: string;  // User's problem description
+  focus_areas: string[];           // User-specified focus (optional)
+
+  // === Diagnosis Results ===
+  diagnosis: {
+    context: DiagnosisResult | null;
+    memory: DiagnosisResult | null;
+    dataflow: DiagnosisResult | null;
+    agent: DiagnosisResult | null;
+    docs: DocsDiagnosisResult | null;  // 文档结构诊断
+    token_consumption: DiagnosisResult | null;  // Token消耗诊断
+  };
+
+  // === Issues Found ===
+  issues: Issue[];
+  issues_by_severity: {
+    critical: number;
+    high: number;
+    medium: number;
+    low: number;
+  };
+
+  // === Fix Management ===
+  proposed_fixes: Fix[];
+  applied_fixes: AppliedFix[];
+  pending_fixes: string[];      // Fix IDs pending application
+
+  // === Iteration Control ===
+  iteration_count: number;
+  max_iterations: number;       // Default: 5
+
+  // === Quality Metrics ===
+  quality_score: number;        // 0-100
+  quality_gate: 'pass' | 'review' | 'fail';
+
+  // === Orchestrator State ===
+  completed_actions: string[];
+  current_action: string | null;
+  action_history: ActionHistoryEntry[];
+
+  // === Error Handling ===
+  errors: ErrorEntry[];
+  error_count: number;
+  max_errors: number;           // Default: 3
+
+  // === Output Paths ===
+  work_dir: string;
+  backup_dir: string;
+
+  // === Final Report (consolidated output) ===
+  final_report: string | null;  // Markdown summary generated on completion
+
+  // === Requirement Analysis (新增) ===
+  requirement_analysis: RequirementAnalysis | null;
+}
+
+interface RequirementAnalysis {
+  status: 'pending' | 'completed' | 'needs_clarification';
+  analyzed_at: string;
+
+  // Phase 1: 维度拆解
+  dimensions: Dimension[];
+
+  // Phase 2: Spec 匹配
+  spec_matches: SpecMatch[];
+
+  // Phase 3: 覆盖度
+  coverage: {
+    total_dimensions: number;
+    with_detection: number;      // 有 taxonomy pattern
+    with_fix_strategy: number;   // 有 tuning strategy (满足判断标准)
+    coverage_rate: number;       // 0-100%
+    status: 'satisfied' | 'partial' | 'unsatisfied';
+  };
+
+  // Phase 4: 歧义
+  ambiguities: Ambiguity[];
+}
+
+interface Dimension {
+  id: string;                    // e.g., "DIM-001"
+  description: string;           // 关注点描述
+  keywords: string[];            // 关键词
+  inferred_category: string;     // 推断的问题类别
+  confidence: number;            // 置信度 0-1
+}
+
+interface SpecMatch {
+  dimension_id: string;
+  taxonomy_match: {
+    category: string;            // e.g., "context_explosion"
+    pattern_ids: string[];       // e.g., ["CTX-001", "CTX-003"]
+    severity_hint: string;
+  } | null;
+  strategy_match: {
+    strategies: string[];        // e.g., ["sliding_window", "path_reference"]
+    risk_levels: string[];
+  } | null;
+  has_fix: boolean;              // 满足性判断核心
+}
+
+interface Ambiguity {
+  dimension_id: string;
+  type: 'multi_category' | 'vague_description' | 'conflicting_keywords';
+  description: string;
+  possible_interpretations: string[];
+  needs_clarification: boolean;
+}
+
+interface DiagnosisResult {
+  status: 'completed' | 'skipped' | 'failed';
+  issues_found: number;
+  severity: 'critical' | 'high' | 'medium' | 'low' | 'none';
+  execution_time_ms: number;
+  details: {
+    patterns_checked: string[];
+    patterns_matched: string[];
+    evidence: Evidence[];
+    recommendations: string[];
+  };
+}
+
+interface DocsDiagnosisResult extends DiagnosisResult {
+  redundancies: Redundancy[];
+  conflicts: Conflict[];
+}
+
+interface Redundancy {
+  id: string;                    // e.g., "DOC-RED-001"
+  type: 'state_schema' | 'strategy_mapping' | 'type_definition' | 'other';
+  files: string[];               // 涉及的文件列表
+  description: string;           // 冗余描述
+  severity: 'high' | 'medium' | 'low';
+  merge_suggestion: string;      // 合并建议
+}
+
+interface Conflict {
+  id: string;                    // e.g., "DOC-CON-001"
+  type: 'priority' | 'mapping' | 'definition';
+  files: string[];               // 涉及的文件列表
+  key: string;                   // 冲突的键/概念
+  definitions: {
+    file: string;
+    value: string;
+    location?: string;
+  }[];
+  resolution_suggestion: string; // 解决建议
+}
+
+interface Evidence {
+  file: string;
+  line?: number;
+  pattern: string;
+  context: string;
+  severity: string;
+}
+
+interface Issue {
+  id: string;                   // e.g., "ISS-001"
+  type: 'context_explosion' | 'memory_loss' | 'dataflow_break' | 'agent_failure' | 'token_consumption';
+  severity: 'critical' | 'high' | 'medium' | 'low';
+  priority: number;             // 1 = highest
+  location: {
+    file: string;
+    line_start?: number;
+    line_end?: number;
+    phase?: string;
+  };
+  description: string;
+  evidence: string[];
+  root_cause: string;
+  impact: string;
+  suggested_fix: string;
+  related_issues: string[];     // Issue IDs
+}
+
+interface Fix {
+  id: string;                   // e.g., "FIX-001"
+  issue_ids: string[];          // Issues this fix addresses
+  strategy: FixStrategy;
+  description: string;
+  rationale: string;
+  changes: FileChange[];
+  risk: 'low' | 'medium' | 'high';
+  estimated_impact: string;
+  verification_steps: string[];
+}
+
+type FixStrategy =
+  | 'context_summarization'     // Add context compression
+  | 'sliding_window'            // Implement sliding context window
+  | 'structured_state'          // Convert to structured state passing
+  | 'constraint_injection'      // Add constraint propagation
+  | 'checkpoint_restore'        // Add checkpointing mechanism
+  | 'schema_enforcement'        // Add data contract validation
+  | 'orchestrator_refactor'     // Refactor agent coordination
+  | 'state_centralization'      // Centralize state management
+  | 'prompt_compression'        // Extract static text, use templates
+  | 'lazy_loading'              // Pass paths instead of content
+  | 'output_minimization'       // Return minimal structured JSON
+  | 'state_field_reduction'     // Audit and consolidate state fields
+  | 'custom';                   // Custom fix
+
+interface FileChange {
+  file: string;
+  action: 'create' | 'modify' | 'delete';
+  old_content?: string;
+  new_content?: string;
+  diff?: string;
+}
+
+interface AppliedFix {
+  fix_id: string;
+  applied_at: string;
+  success: boolean;
+  backup_path: string;
+  verification_result: 'pass' | 'fail' | 'pending';
+  rollback_available: boolean;
+}
+
+interface ActionHistoryEntry {
+  action: string;
+  started_at: string;
+  completed_at: string;
+  result: 'success' | 'failure' | 'skipped';
+  output_files: string[];
+}
+
+interface ErrorEntry {
+  action: string;
+  message: string;
+  timestamp: string;
+  recoverable: boolean;
+}
+```
+
+## Initial State Template
+
+```json
+{
+  "status": "pending",
+  "started_at": null,
+  "updated_at": null,
+  "target_skill": {
+    "name": null,
+    "path": null,
+    "execution_mode": null,
+    "phases": [],
+    "specs": []
+  },
+  "user_issue_description": "",
+  "focus_areas": [],
+  "diagnosis": {
+    "context": null,
+    "memory": null,
+    "dataflow": null,
+    "agent": null,
+    "docs": null,
+    "token_consumption": null
+  },
+  "issues": [],
+  "issues_by_severity": {
+    "critical": 0,
+    "high": 0,
+    "medium": 0,
+    "low": 0
+  },
+  "proposed_fixes": [],
+  "applied_fixes": [],
+  "pending_fixes": [],
+  "iteration_count": 0,
+  "max_iterations": 5,
+  "quality_score": 0,
+  "quality_gate": "fail",
+  "completed_actions": [],
+  "current_action": null,
+  "action_history": [],
+  "errors": [],
+  "error_count": 0,
+  "max_errors": 3,
+  "work_dir": null,
+  "backup_dir": null,
+  "final_report": null,
+  "requirement_analysis": null
+}
+```
+
+## State Transition Diagram
+
+```
+                         ┌─────────────┐
+                         │   pending   │
+                         └──────┬──────┘
+                                │ action-init
+                                ↓
+                         ┌─────────────┐
+              ┌──────────│   running   │──────────┐
+              │          └──────┬──────┘          │
+              │                 │                 │
+    diagnosis │    ┌────────────┼────────────┐    │ error_count >= 3
+    actions   │    │            │            │    │
+              │    ↓            ↓            ↓    │
+              │ context     memory      dataflow  │
+              │    │            │            │    │
+              │    └────────────┼────────────┘    │
+              │                 │                 │
+              │                 ↓                 │
+              │          action-verify            │
+              │                 │                 │
+              │     ┌───────────┼───────────┐     │
+              │     │           │           │     │
+              │     ↓           ↓           ↓     │
+              │  quality    iterate      apply    │
+              │  gate=pass  (< max)       fix     │
+              │     │           │           │     │
+              │     │           └───────────┘     │
+              │     ↓                             ↓
+              │ ┌─────────────┐           ┌─────────────┐
+              └→│  completed  │           │   failed    │
+                └─────────────┘           └─────────────┘
+```
+
+## State Update Rules
+
+### Atomicity
+All state updates must be atomic - read current state, apply changes, write entire state.
+
+### Immutability
+Never mutate state in place. Always create new state object with changes.
+
+### Validation
+Before writing state, validate against schema to prevent corruption.
+
+### Timestamps
+Always update `updated_at` on every state change.
+
+```javascript
+function updateState(workDir, updates) {
+  const currentState = JSON.parse(Read(`${workDir}/state.json`));
+
+  const newState = {
+    ...currentState,
+    ...updates,
+    updated_at: new Date().toISOString()
+  };
+
+  // Validate before write
+  if (!validateState(newState)) {
+    throw new Error('Invalid state update');
+  }
+
+  Write(`${workDir}/state.json`, JSON.stringify(newState, null, 2));
+  return newState;
+}
+```

package/.claude/skills/skill-tuning/specs/category-mappings.json

@@ -0,0 +1,284 @@
+{
+  "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]
+    },
+    "token_consumption": {
+      "pattern_ids": ["TKN-001", "TKN-002", "TKN-003", "TKN-004", "TKN-005"],
+      "severity_hint": "medium",
+      "strategies": ["prompt_compression", "lazy_loading", "output_minimization", "state_field_reduction", "sliding_window"],
+      "risk_levels": ["low", "low", "low", "low", "low"],
+      "detection_focus": "Verbose prompts, excessive state fields, full content passing, unbounded arrays, redundant I/O",
+      "priority_order": [1, 2, 3, 4, 5]
+    }
+  },
+  "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",
+      "token消耗": "token_consumption",
+      "token优化": "token_consumption",
+      "产出简化": "token_consumption",
+      "冗长": "token_consumption",
+      "精简": "token_consumption"
+    },
+    "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",
+      "verbose": "token_consumption",
+      "minimize": "token_consumption",
+      "compress": "token_consumption",
+      "simplify": "token_consumption",
+      "reduction": "token_consumption"
+    }
+  },
+  "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",
+    "token_consumption": "Token Consumption",
+    "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",
+    "token_consumption": "Token Consumption Optimization",
+    "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",
+    "token_consumption": "Excessive token usage from verbose prompts, large state objects, or redundant I/O patterns",
+    "custom": "Requires custom analysis"
+  },
+  "fix_priority_order": {
+    "P0": ["dataflow_break", "authoring_principles_violation"],
+    "P1": ["agent_failure"],
+    "P2": ["context_explosion", "token_consumption"],
+    "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
+  }
+}