Skill Tuning Autonomous diagnosis and optimization for skill execution issues. Architecture Core Issues Detected | Priority | Problem | Root Cause | Fix Strategy | |----------|---------|-----------|--------------| | P0 | Authoring Violation | Intermediate files, state bloat, file relay | eliminate intermediate, minimize state | | P1 | Data Flow Disruption | Scattered state, inconsistent formats | state centralization, schema enforcement | | P2 | Agent Coordination | Fragile chains, no error handling | error wrapping, result validation | | P3 | Context Explosion | Unbounded history, full conte…

).replace(/`/g, '\\\\`');\n}\n```\n\n## Output\n\n### State Updates\n\n```javascript\n{\n gemini_analysis: {\n type: 'root_cause' | 'architecture' | 'prompt_optimization' | 'performance' | 'custom',\n status: 'running' | 'completed' | 'failed',\n started_at: '2024-01-01T00:00:00Z',\n completed_at: '2024-01-01T00:05:00Z',\n task_id: 'xxx',\n result: { /* 分析结果 */ },\n error: null\n },\n // 分析结果合并到 issues\n issues: [\n ...state.issues,\n ...newIssuesFromAnalysis\n ]\n}\n```\n\n### Output Files\n\n- `${workDir}/diagnosis/gemini-analysis-${type}.json` - 原始分析结果\n- `${workDir}/diagnosis/gemini-analysis-${type}.md` - 格式化报告\n\n## Post-Execution\n\n分析完成后:\n1. 解析 CLI 输出为结构化数据\n2. 提取新发现的 issues 合并到 state.issues\n3. 更新 recommendations 到 state\n4. 触发下一步动作 (通常是 action-generate-report 或 action-propose-fixes)\n\n## Error Handling\n\n| Error | Recovery |\n|-------|----------|\n| CLI 超时 | 重试一次，仍失败则跳过 Gemini 分析 |\n| 解析失败 | 保存原始输出，手动处理 |\n| 无结果 | 标记为 skipped，继续流程 |\n\n## User Interaction\n\n如果 `state.analysis_type === null` 且无法自动推断，询问用户:\n\n```javascript\nAskUserQuestion({\n questions: [{\n question: '请选择 Gemini 分析类型',\n header: '分析类型',\n options: [\n { label: '问题根因分析', description: '深度分析用户描述的问题' },\n { label: '架构审查', description: '评估整体架构设计' },\n { label: '提示词优化', description: '分析和优化 phase 提示词' },\n { label: '性能分析', description: '分析 Token 消耗和执行效率' }\n ],\n multiSelect: false\n }]\n});\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":9234,"content_sha256":"8135a9c9ecf5f4feaab5d304b409ff1d0aaa603ad1f6679d5798e6bd77bd9fd1"},{"filename":"phases/actions/action-generate-report.md","content":"# Action: Generate Consolidated Report\n\nGenerate a comprehensive tuning report merging all diagnosis results with prioritized recommendations.\n\n## Purpose\n\n- Merge all diagnosis results into unified report\n- Prioritize issues by severity and impact\n- Generate actionable recommendations\n- Create human-readable markdown report\n\n## Preconditions\n\n- [ ] state.status === 'running'\n- [ ] All diagnoses in focus_areas are completed\n- [ ] state.issues.length > 0 OR generate summary report\n\n## Execution\n\n```javascript\nasync function execute(state, workDir) {\n console.log('Generating consolidated tuning report...');\n\n const targetSkill = state.target_skill;\n const issues = state.issues;\n\n // 1. Group issues by type\n const issuesByType = {\n context_explosion: issues.filter(i => i.type === 'context_explosion'),\n memory_loss: issues.filter(i => i.type === 'memory_loss'),\n dataflow_break: issues.filter(i => i.type === 'dataflow_break'),\n agent_failure: issues.filter(i => i.type === 'agent_failure')\n };\n\n // 2. Group issues by severity\n const issuesBySeverity = {\n critical: issues.filter(i => i.severity === 'critical'),\n high: issues.filter(i => i.severity === 'high'),\n medium: issues.filter(i => i.severity === 'medium'),\n low: issues.filter(i => i.severity === 'low')\n };\n\n // 3. Calculate overall health score\n const weights = { critical: 25, high: 15, medium: 5, low: 1 };\n const deductions = Object.entries(issuesBySeverity)\n .reduce((sum, [sev, arr]) => sum + arr.length * weights[sev], 0);\n const healthScore = Math.max(0, 100 - deductions);\n\n // 4. Generate report content\n const report = `# Skill Tuning Report\n\n**Target Skill**: ${targetSkill.name}\n**Path**: ${targetSkill.path}\n**Execution Mode**: ${targetSkill.execution_mode}\n**Generated**: ${new Date().toISOString()}\n\n---\n\n## Executive Summary\n\n| Metric | Value |\n|--------|-------|\n| Health Score | ${healthScore}/100 |\n| Total Issues | ${issues.length} |\n| Critical | ${issuesBySeverity.critical.length} |\n| High | ${issuesBySeverity.high.length} |\n| Medium | ${issuesBySeverity.medium.length} |\n| Low | ${issuesBySeverity.low.length} |\n\n### User Reported Issue\n> ${state.user_issue_description}\n\n### Overall Assessment\n${healthScore >= 80 ? '✅ Skill is in good health with minor issues.' :\n healthScore >= 60 ? '⚠️ Skill has significant issues requiring attention.' :\n healthScore >= 40 ? '🔶 Skill has serious issues affecting reliability.' :\n '❌ Skill has critical issues requiring immediate fixes.'}\n\n---\n\n## Diagnosis Results\n\n### Context Explosion Analysis\n${state.diagnosis.context ?\n `- **Status**: ${state.diagnosis.context.status}\n- **Severity**: ${state.diagnosis.context.severity}\n- **Issues Found**: ${state.diagnosis.context.issues_found}\n- **Key Findings**: ${state.diagnosis.context.details.recommendations.join('; ') || 'None'}` :\n '_Not analyzed_'}\n\n### Long-tail Memory Analysis\n${state.diagnosis.memory ?\n `- **Status**: ${state.diagnosis.memory.status}\n- **Severity**: ${state.diagnosis.memory.severity}\n- **Issues Found**: ${state.diagnosis.memory.issues_found}\n- **Key Findings**: ${state.diagnosis.memory.details.recommendations.join('; ') || 'None'}` :\n '_Not analyzed_'}\n\n### Data Flow Analysis\n${state.diagnosis.dataflow ?\n `- **Status**: ${state.diagnosis.dataflow.status}\n- **Severity**: ${state.diagnosis.dataflow.severity}\n- **Issues Found**: ${state.diagnosis.dataflow.issues_found}\n- **Key Findings**: ${state.diagnosis.dataflow.details.recommendations.join('; ') || 'None'}` :\n '_Not analyzed_'}\n\n### Agent Coordination Analysis\n${state.diagnosis.agent ?\n `- **Status**: ${state.diagnosis.agent.status}\n- **Severity**: ${state.diagnosis.agent.severity}\n- **Issues Found**: ${state.diagnosis.agent.issues_found}\n- **Key Findings**: ${state.diagnosis.agent.details.recommendations.join('; ') || 'None'}` :\n '_Not analyzed_'}\n\n---\n\n## Critical & High Priority Issues\n\n${issuesBySeverity.critical.length + issuesBySeverity.high.length === 0 ?\n '_No critical or high priority issues found._' :\n [...issuesBySeverity.critical, ...issuesBySeverity.high].map((issue, i) => `\n### ${i + 1}. [${issue.severity.toUpperCase()}] ${issue.description}\n\n- **ID**: ${issue.id}\n- **Type**: ${issue.type}\n- **Location**: ${typeof issue.location === 'object' ? issue.location.file : issue.location}\n- **Root Cause**: ${issue.root_cause}\n- **Impact**: ${issue.impact}\n- **Suggested Fix**: ${issue.suggested_fix}\n\n**Evidence**:\n${issue.evidence.map(e => `- \\`${e}\\``).join('\\n')}\n`).join('\\n')}\n\n---\n\n## Medium & Low Priority Issues\n\n${issuesBySeverity.medium.length + issuesBySeverity.low.length === 0 ?\n '_No medium or low priority issues found._' :\n [...issuesBySeverity.medium, ...issuesBySeverity.low].map((issue, i) => `\n### ${i + 1}. [${issue.severity.toUpperCase()}] ${issue.description}\n\n- **ID**: ${issue.id}\n- **Type**: ${issue.type}\n- **Suggested Fix**: ${issue.suggested_fix}\n`).join('\\n')}\n\n---\n\n## Recommended Fix Order\n\nBased on severity and dependencies, apply fixes in this order:\n\n${[...issuesBySeverity.critical, ...issuesBySeverity.high, ...issuesBySeverity.medium]\n .slice(0, 10)\n .map((issue, i) => `${i + 1}. **${issue.id}**: ${issue.suggested_fix}`)\n .join('\\n')}\n\n---\n\n## Quality Gates\n\n| Gate | Threshold | Current | Status |\n|------|-----------|---------|--------|\n| Critical Issues | 0 | ${issuesBySeverity.critical.length} | ${issuesBySeverity.critical.length === 0 ? '✅ PASS' : '❌ FAIL'} |\n| High Issues | ≤ 2 | ${issuesBySeverity.high.length} | ${issuesBySeverity.high.length \u003c= 2 ? '✅ PASS' : '❌ FAIL'} |\n| Health Score | ≥ 60 | ${healthScore} | ${healthScore >= 60 ? '✅ PASS' : '❌ FAIL'} |\n\n**Overall Quality Gate**: ${\n issuesBySeverity.critical.length === 0 &&\n issuesBySeverity.high.length \u003c= 2 &&\n healthScore >= 60 ? '✅ PASS' : '❌ FAIL'}\n\n---\n\n*Report generated by skill-tuning*\n`;\n\n // 5. Write report\n Write(`${workDir}/tuning-report.md`, report);\n\n // 6. Calculate quality gate\n const qualityGate = issuesBySeverity.critical.length === 0 &&\n issuesBySeverity.high.length \u003c= 2 &&\n healthScore >= 60 ? 'pass' :\n healthScore >= 40 ? 'review' : 'fail';\n\n return {\n stateUpdates: {\n quality_score: healthScore,\n quality_gate: qualityGate,\n issues_by_severity: {\n critical: issuesBySeverity.critical.length,\n high: issuesBySeverity.high.length,\n medium: issuesBySeverity.medium.length,\n low: issuesBySeverity.low.length\n }\n },\n outputFiles: [`${workDir}/tuning-report.md`],\n summary: `Report generated: ${issues.length} issues, health score ${healthScore}/100, gate: ${qualityGate}`\n };\n}\n```\n\n## State Updates\n\n```javascript\nreturn {\n stateUpdates: {\n quality_score: \u003c0-100>,\n quality_gate: '\u003cpass|review|fail>',\n issues_by_severity: { critical: N, high: N, medium: N, low: N }\n }\n};\n```\n\n## Error Handling\n\n| Error Type | Recovery |\n|------------|----------|\n| Write error | Retry to alternative path |\n| Empty issues | Generate summary with no issues |\n\n## Next Actions\n\n- If issues.length > 0: action-propose-fixes\n- If issues.length === 0: action-complete\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":7211,"content_sha256":"de09ff8e55a8beb81fdfaa803dcd1b657acc294dfc22170892517a48647dd44e"},{"filename":"phases/actions/action-init.md","content":"# Action: Initialize Tuning Session\n\nInitialize the skill-tuning session by collecting target skill information, creating work directories, and setting up initial state.\n\n## Purpose\n\n- Identify target skill to tune\n- Collect user's problem description\n- Create work directory structure\n- Backup original skill files\n- Initialize state for orchestrator\n\n## Preconditions\n\n- [ ] state.status === 'pending'\n\n## Execution\n\n```javascript\nasync function execute(state, workDir) {\n // 1. Ask user for target skill\n const skillInput = await AskUserQuestion({\n questions: [{\n question: \"Which skill do you want to tune?\",\n header: \"Target Skill\",\n multiSelect: false,\n options: [\n { label: \"Specify path\", description: \"Enter skill directory path\" }\n ]\n }]\n });\n\n const skillPath = skillInput[\"Target Skill\"];\n\n // 2. Validate skill exists and read structure\n const skillMdPath = `${skillPath}/SKILL.md`;\n if (!Glob(`${skillPath}/SKILL.md`).length) {\n throw new Error(`Invalid skill path: ${skillPath} - SKILL.md not found`);\n }\n\n // 3. Read skill metadata\n const skillMd = Read(skillMdPath);\n const frontMatterMatch = skillMd.match(/^---\\n([\\s\\S]*?)\\n---/);\n const skillName = frontMatterMatch\n ? frontMatterMatch[1].match(/name:\\s*(.+)/)?.[1]?.trim()\n : skillPath.split('/').pop();\n\n // 4. Detect execution mode\n const hasOrchestrator = Glob(`${skillPath}/phases/orchestrator.md`).length > 0;\n const executionMode = hasOrchestrator ? 'autonomous' : 'sequential';\n\n // 5. Scan skill structure\n const phases = Glob(`${skillPath}/phases/**/*.md`).map(f => f.replace(skillPath + '/', ''));\n const specs = Glob(`${skillPath}/specs/**/*.md`).map(f => f.replace(skillPath + '/', ''));\n\n // 6. Ask for problem description\n const issueInput = await AskUserQuestion({\n questions: [{\n question: \"Describe the issue or what you want to optimize:\",\n header: \"Issue\",\n multiSelect: false,\n options: [\n { label: \"Context grows too large\", description: \"Token explosion over multiple turns\" },\n { label: \"Instructions forgotten\", description: \"Early constraints lost in long execution\" },\n { label: \"Data inconsistency\", description: \"State format changes between phases\" },\n { label: \"Agent failures\", description: \"Sub-agent calls fail or return unexpected results\" }\n ]\n }]\n });\n\n // 7. Ask for focus areas\n const focusInput = await AskUserQuestion({\n questions: [{\n question: \"Which areas should be diagnosed? (Select all that apply)\",\n header: \"Focus\",\n multiSelect: true,\n options: [\n { label: \"context\", description: \"Context explosion analysis\" },\n { label: \"memory\", description: \"Long-tail forgetting analysis\" },\n { label: \"dataflow\", description: \"Data flow analysis\" },\n { label: \"agent\", description: \"Agent coordination analysis\" }\n ]\n }]\n });\n\n const focusAreas = focusInput[\"Focus\"] || ['context', 'memory', 'dataflow', 'agent'];\n\n // 8. Create backup\n const backupDir = `${workDir}/backups/${skillName}-backup`;\n Bash(`mkdir -p \"${backupDir}\"`);\n Bash(`cp -r \"${skillPath}\"/* \"${backupDir}/\"`);\n\n // 9. Return state updates\n return {\n stateUpdates: {\n status: 'running',\n started_at: new Date().toISOString(),\n target_skill: {\n name: skillName,\n path: skillPath,\n execution_mode: executionMode,\n phases: phases,\n specs: specs\n },\n user_issue_description: issueInput[\"Issue\"],\n focus_areas: Array.isArray(focusAreas) ? focusAreas : [focusAreas],\n work_dir: workDir,\n backup_dir: backupDir\n },\n outputFiles: [],\n summary: `Initialized tuning for \"${skillName}\" (${executionMode} mode), focus: ${focusAreas.join(', ')}`\n };\n}\n```\n\n## State Updates\n\n```javascript\nreturn {\n stateUpdates: {\n status: 'running',\n started_at: '\u003ctimestamp>',\n target_skill: {\n name: '\u003cskill-name>',\n path: '\u003cskill-path>',\n execution_mode: '\u003csequential|autonomous>',\n phases: ['...'],\n specs: ['...']\n },\n user_issue_description: '\u003cuser description>',\n focus_areas: ['context', 'memory', ...],\n work_dir: '\u003cwork-dir>',\n backup_dir: '\u003cbackup-dir>'\n }\n};\n```\n\n## Error Handling\n\n| Error Type | Recovery |\n|------------|----------|\n| Skill path not found | Ask user to re-enter valid path |\n| SKILL.md missing | Suggest path correction |\n| Backup creation failed | Retry with alternative location |\n\n## Next Actions\n\n- Success: Continue to first diagnosis action based on focus_areas\n- Failure: action-abort\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4609,"content_sha256":"f0e1e07af6f6cc8be6b7160f57bb1d2484c2306c82387913b204ac139dbce6e2"},{"filename":"phases/actions/action-propose-fixes.md","content":"# Action: Propose Fixes\n\nGenerate fix proposals for identified issues with implementation strategies.\n\n## Purpose\n\n- Create fix strategies for each issue\n- Generate implementation plans\n- Estimate risk levels\n- Allow user to select fixes to apply\n\n## Preconditions\n\n- [ ] state.status === 'running'\n- [ ] state.issues.length > 0\n- [ ] action-generate-report completed\n\n## Fix Strategy Catalog\n\n### Context Explosion Fixes\n\n| Strategy | Description | Risk |\n|----------|-------------|------|\n| `context_summarization` | Add summarizer agent between phases | low |\n| `sliding_window` | Keep only last N turns in context | low |\n| `structured_state` | Replace text context with JSON state | medium |\n| `path_reference` | Pass file paths instead of content | low |\n\n### Memory Loss Fixes\n\n| Strategy | Description | Risk |\n|----------|-------------|------|\n| `constraint_injection` | Add constraints to each phase prompt | low |\n| `checkpoint_restore` | Save state at milestones | low |\n| `goal_embedding` | Track goal similarity throughout | medium |\n| `state_constraints_field` | Add constraints field to state schema | low |\n\n### Data Flow Fixes\n\n| Strategy | Description | Risk |\n|----------|-------------|------|\n| `state_centralization` | Single state.json for all data | medium |\n| `schema_enforcement` | Add Zod validation | low |\n| `field_normalization` | Normalize field names | low |\n| `transactional_updates` | Atomic state updates | medium |\n\n### Agent Coordination Fixes\n\n| Strategy | Description | Risk |\n|----------|-------------|------|\n| `error_wrapping` | Add try-catch to all Task calls | low |\n| `result_validation` | Validate agent returns | low |\n| `orchestrator_refactor` | Centralize agent coordination | high |\n| `flatten_nesting` | Remove nested agent calls | medium |\n\n## Execution\n\n```javascript\nasync function execute(state, workDir) {\n console.log('Generating fix proposals...');\n\n const issues = state.issues;\n const fixes = [];\n\n // Group issues by type for batch fixes\n const issuesByType = {\n context_explosion: issues.filter(i => i.type === 'context_explosion'),\n memory_loss: issues.filter(i => i.type === 'memory_loss'),\n dataflow_break: issues.filter(i => i.type === 'dataflow_break'),\n agent_failure: issues.filter(i => i.type === 'agent_failure')\n };\n\n // Generate fixes for context explosion\n if (issuesByType.context_explosion.length > 0) {\n const ctxIssues = issuesByType.context_explosion;\n\n if (ctxIssues.some(i => i.description.includes('history accumulation'))) {\n fixes.push({\n id: `FIX-${fixes.length + 1}`,\n issue_ids: ctxIssues.filter(i => i.description.includes('history')).map(i => i.id),\n strategy: 'sliding_window',\n description: 'Implement sliding window for conversation history',\n rationale: 'Prevents unbounded context growth by keeping only recent turns',\n changes: [{\n file: 'phases/orchestrator.md',\n action: 'modify',\n diff: `+ const MAX_HISTORY = 5;\n+ state.history = state.history.slice(-MAX_HISTORY);`\n }],\n risk: 'low',\n estimated_impact: 'Reduces token usage by ~50%',\n verification_steps: ['Run skill with 10+ iterations', 'Verify context size stable']\n });\n }\n\n if (ctxIssues.some(i => i.description.includes('full content'))) {\n fixes.push({\n id: `FIX-${fixes.length + 1}`,\n issue_ids: ctxIssues.filter(i => i.description.includes('content')).map(i => i.id),\n strategy: 'path_reference',\n description: 'Pass file paths instead of full content',\n rationale: 'Agents can read files when needed, reducing prompt size',\n changes: [{\n file: 'phases/*.md',\n action: 'modify',\n diff: `- prompt: \\${content}\n+ prompt: Read file at: \\${filePath}`\n }],\n risk: 'low',\n estimated_impact: 'Significant token reduction',\n verification_steps: ['Verify agents can still access needed content']\n });\n }\n }\n\n // Generate fixes for memory loss\n if (issuesByType.memory_loss.length > 0) {\n const memIssues = issuesByType.memory_loss;\n\n if (memIssues.some(i => i.description.includes('constraint'))) {\n fixes.push({\n id: `FIX-${fixes.length + 1}`,\n issue_ids: memIssues.filter(i => i.description.includes('constraint')).map(i => i.id),\n strategy: 'constraint_injection',\n description: 'Add constraint injection to all phases',\n rationale: 'Ensures original requirements are visible in every phase',\n changes: [{\n file: 'phases/*.md',\n action: 'modify',\n diff: `+ [CONSTRAINTS]\n+ Original requirements from state.original_requirements:\n+ \\${JSON.stringify(state.original_requirements)}`\n }],\n risk: 'low',\n estimated_impact: 'Improves constraint adherence',\n verification_steps: ['Run skill with specific constraints', 'Verify output matches']\n });\n }\n\n if (memIssues.some(i => i.description.includes('State schema'))) {\n fixes.push({\n id: `FIX-${fixes.length + 1}`,\n issue_ids: memIssues.filter(i => i.description.includes('schema')).map(i => i.id),\n strategy: 'state_constraints_field',\n description: 'Add original_requirements field to state schema',\n rationale: 'Preserves original intent throughout execution',\n changes: [{\n file: 'phases/state-schema.md',\n action: 'modify',\n diff: `+ original_requirements: string[]; // User's original constraints\n+ goal_summary: string; // One-line goal statement`\n }],\n risk: 'low',\n estimated_impact: 'Enables constraint tracking',\n verification_steps: ['Verify state includes requirements after init']\n });\n }\n }\n\n // Generate fixes for data flow\n if (issuesByType.dataflow_break.length > 0) {\n const dfIssues = issuesByType.dataflow_break;\n\n if (dfIssues.some(i => i.description.includes('multiple locations'))) {\n fixes.push({\n id: `FIX-${fixes.length + 1}`,\n issue_ids: dfIssues.filter(i => i.description.includes('location')).map(i => i.id),\n strategy: 'state_centralization',\n description: 'Centralize all state to single state.json',\n rationale: 'Single source of truth prevents inconsistencies',\n changes: [{\n file: 'phases/*.md',\n action: 'modify',\n diff: `- Write(\\`\\${workDir}/config.json\\`, ...)\n+ updateState({ config: ... }) // Use state manager`\n }],\n risk: 'medium',\n estimated_impact: 'Eliminates state fragmentation',\n verification_steps: ['Verify all reads come from state.json', 'Test state persistence']\n });\n }\n\n if (dfIssues.some(i => i.description.includes('validation'))) {\n fixes.push({\n id: `FIX-${fixes.length + 1}`,\n issue_ids: dfIssues.filter(i => i.description.includes('validation')).map(i => i.id),\n strategy: 'schema_enforcement',\n description: 'Add Zod schema validation',\n rationale: 'Runtime validation catches schema violations',\n changes: [{\n file: 'phases/state-schema.md',\n action: 'modify',\n diff: `+ import { z } from 'zod';\n+ const StateSchema = z.object({...});\n+ function validateState(s) { return StateSchema.parse(s); }`\n }],\n risk: 'low',\n estimated_impact: 'Catches invalid state early',\n verification_steps: ['Test with invalid state input', 'Verify error thrown']\n });\n }\n }\n\n // Generate fixes for agent coordination\n if (issuesByType.agent_failure.length > 0) {\n const agentIssues = issuesByType.agent_failure;\n\n if (agentIssues.some(i => i.description.includes('error handling'))) {\n fixes.push({\n id: `FIX-${fixes.length + 1}`,\n issue_ids: agentIssues.filter(i => i.description.includes('error')).map(i => i.id),\n strategy: 'error_wrapping',\n description: 'Wrap all Task calls in try-catch',\n rationale: 'Prevents cascading failures from agent errors',\n changes: [{\n file: 'phases/*.md',\n action: 'modify',\n diff: `+ try {\n const result = await Agent({...});\n+ if (!result) throw new Error('Empty result');\n+ } catch (e) {\n+ updateState({ errors: [...errors, e.message], error_count: error_count + 1 });\n+ }`\n }],\n risk: 'low',\n estimated_impact: 'Improves error resilience',\n verification_steps: ['Simulate agent failure', 'Verify graceful handling']\n });\n }\n\n if (agentIssues.some(i => i.description.includes('nested'))) {\n fixes.push({\n id: `FIX-${fixes.length + 1}`,\n issue_ids: agentIssues.filter(i => i.description.includes('nested')).map(i => i.id),\n strategy: 'flatten_nesting',\n description: 'Flatten nested agent calls',\n rationale: 'Reduces complexity and context explosion',\n changes: [{\n file: 'phases/orchestrator.md',\n action: 'modify',\n diff: `// Instead of agent calling agent:\n// Agent A returns {needs_agent_b: true}\n// Orchestrator sees this and calls Agent B next`\n }],\n risk: 'medium',\n estimated_impact: 'Reduces nesting depth',\n verification_steps: ['Verify no nested Task calls', 'Test agent chaining via orchestrator']\n });\n }\n }\n\n // Write fix proposals\n Write(`${workDir}/fixes/fix-proposals.json`, JSON.stringify(fixes, null, 2));\n\n // Ask user to select fixes to apply\n const fixOptions = fixes.slice(0, 4).map(f => ({\n label: f.id,\n description: `[${f.risk.toUpperCase()} risk] ${f.description}`\n }));\n\n if (fixOptions.length > 0) {\n const selection = await AskUserQuestion({\n questions: [{\n question: 'Which fixes would you like to apply?',\n header: 'Fixes',\n multiSelect: true,\n options: fixOptions\n }]\n });\n\n const selectedFixIds = Array.isArray(selection['Fixes'])\n ? selection['Fixes']\n : [selection['Fixes']];\n\n return {\n stateUpdates: {\n proposed_fixes: fixes,\n pending_fixes: selectedFixIds.filter(id => id && fixes.some(f => f.id === id))\n },\n outputFiles: [`${workDir}/fixes/fix-proposals.json`],\n summary: `Generated ${fixes.length} fix proposals, ${selectedFixIds.length} selected for application`\n };\n }\n\n return {\n stateUpdates: {\n proposed_fixes: fixes,\n pending_fixes: []\n },\n outputFiles: [`${workDir}/fixes/fix-proposals.json`],\n summary: `Generated ${fixes.length} fix proposals (none selected)`\n };\n}\n```\n\n## State Updates\n\n```javascript\nreturn {\n stateUpdates: {\n proposed_fixes: [...fixes],\n pending_fixes: [...selectedFixIds]\n }\n};\n```\n\n## Error Handling\n\n| Error Type | Recovery |\n|------------|----------|\n| No issues to fix | Skip to action-complete |\n| User cancels selection | Set pending_fixes to empty |\n\n## Next Actions\n\n- If pending_fixes.length > 0: action-apply-fix\n- If pending_fixes.length === 0: action-complete\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":11036,"content_sha256":"4de77c4ca2ea8927d240d1be35a6dbbaa677be2c46f791a02ba9a8242d30ab25"},{"filename":"phases/actions/action-verify.md","content":"# Action: Verify Applied Fixes\n\nVerify that applied fixes resolved the targeted issues.\n\n## Purpose\n\n- Re-run relevant diagnostics\n- Compare before/after issue counts\n- Update verification status\n- Determine if more iterations needed\n\n## Preconditions\n\n- [ ] state.status === 'running'\n- [ ] state.applied_fixes.length > 0\n- [ ] Some applied_fixes have verification_result === 'pending'\n\n## Execution\n\n```javascript\nasync function execute(state, workDir) {\n console.log('Verifying applied fixes...');\n\n const appliedFixes = state.applied_fixes.filter(f => f.verification_result === 'pending');\n\n if (appliedFixes.length === 0) {\n return {\n stateUpdates: {},\n outputFiles: [],\n summary: 'No fixes pending verification'\n };\n }\n\n const verificationResults = [];\n\n for (const fix of appliedFixes) {\n const proposedFix = state.proposed_fixes.find(f => f.id === fix.fix_id);\n\n if (!proposedFix) {\n verificationResults.push({\n fix_id: fix.fix_id,\n result: 'fail',\n reason: 'Fix definition not found'\n });\n continue;\n }\n\n // Determine which diagnosis to re-run based on fix strategy\n const strategyToDiagnosis = {\n 'context_summarization': 'context',\n 'sliding_window': 'context',\n 'structured_state': 'context',\n 'path_reference': 'context',\n 'constraint_injection': 'memory',\n 'checkpoint_restore': 'memory',\n 'goal_embedding': 'memory',\n 'state_constraints_field': 'memory',\n 'state_centralization': 'dataflow',\n 'schema_enforcement': 'dataflow',\n 'field_normalization': 'dataflow',\n 'transactional_updates': 'dataflow',\n 'error_wrapping': 'agent',\n 'result_validation': 'agent',\n 'orchestrator_refactor': 'agent',\n 'flatten_nesting': 'agent'\n };\n\n const diagnosisType = strategyToDiagnosis[proposedFix.strategy];\n\n // For now, do a lightweight verification\n // Full implementation would re-run the specific diagnosis\n\n // Check if the fix was actually applied (look for markers)\n const targetPath = state.target_skill.path;\n const fixMarker = `Applied fix ${fix.fix_id}`;\n\n let fixFound = false;\n const allFiles = Glob(`${targetPath}/**/*.md`);\n\n for (const file of allFiles) {\n const content = Read(file);\n if (content.includes(fixMarker)) {\n fixFound = true;\n break;\n }\n }\n\n if (fixFound) {\n // Verify by checking if original issues still exist\n const relatedIssues = proposedFix.issue_ids;\n const originalIssueCount = relatedIssues.length;\n\n // Simplified verification: assume fix worked if marker present\n // Real implementation would re-run diagnosis patterns\n\n verificationResults.push({\n fix_id: fix.fix_id,\n result: 'pass',\n reason: `Fix applied successfully, addressing ${originalIssueCount} issues`,\n issues_resolved: relatedIssues\n });\n } else {\n verificationResults.push({\n fix_id: fix.fix_id,\n result: 'fail',\n reason: 'Fix marker not found in target files'\n });\n }\n }\n\n // Update applied fixes with verification results\n const updatedAppliedFixes = state.applied_fixes.map(fix => {\n const result = verificationResults.find(v => v.fix_id === fix.fix_id);\n if (result) {\n return {\n ...fix,\n verification_result: result.result\n };\n }\n return fix;\n });\n\n // Calculate new quality score\n const passedFixes = verificationResults.filter(v => v.result === 'pass').length;\n const totalFixes = verificationResults.length;\n const verificationRate = totalFixes > 0 ? (passedFixes / totalFixes) * 100 : 100;\n\n // Recalculate issues (remove resolved ones)\n const resolvedIssueIds = verificationResults\n .filter(v => v.result === 'pass')\n .flatMap(v => v.issues_resolved || []);\n\n const remainingIssues = state.issues.filter(i => !resolvedIssueIds.includes(i.id));\n\n // Recalculate quality score\n const weights = { critical: 25, high: 15, medium: 5, low: 1 };\n const deductions = remainingIssues.reduce((sum, issue) =>\n sum + (weights[issue.severity] || 0), 0);\n const newHealthScore = Math.max(0, 100 - deductions);\n\n // Determine new quality gate\n const remainingCritical = remainingIssues.filter(i => i.severity === 'critical').length;\n const remainingHigh = remainingIssues.filter(i => i.severity === 'high').length;\n const newQualityGate = remainingCritical === 0 && remainingHigh \u003c= 2 && newHealthScore >= 60\n ? 'pass'\n : newHealthScore >= 40 ? 'review' : 'fail';\n\n // Increment iteration count\n const newIterationCount = state.iteration_count + 1;\n\n // Ask user if they want to continue\n let continueIteration = false;\n if (newQualityGate !== 'pass' && newIterationCount \u003c state.max_iterations) {\n const continueResponse = await AskUserQuestion({\n questions: [{\n question: `Verification complete. Quality gate: ${newQualityGate}. Continue with another iteration?`,\n header: 'Continue',\n multiSelect: false,\n options: [\n { label: 'Yes', description: `Run iteration ${newIterationCount + 1}` },\n { label: 'No', description: 'Finish with current state' }\n ]\n }]\n });\n continueIteration = continueResponse['Continue'] === 'Yes';\n }\n\n // If continuing, reset diagnosis for re-evaluation\n const diagnosisReset = continueIteration ? {\n 'diagnosis.context': null,\n 'diagnosis.memory': null,\n 'diagnosis.dataflow': null,\n 'diagnosis.agent': null\n } : {};\n\n return {\n stateUpdates: {\n applied_fixes: updatedAppliedFixes,\n issues: remainingIssues,\n quality_score: newHealthScore,\n quality_gate: newQualityGate,\n iteration_count: newIterationCount,\n ...diagnosisReset,\n issues_by_severity: {\n critical: remainingIssues.filter(i => i.severity === 'critical').length,\n high: remainingIssues.filter(i => i.severity === 'high').length,\n medium: remainingIssues.filter(i => i.severity === 'medium').length,\n low: remainingIssues.filter(i => i.severity === 'low').length\n }\n },\n outputFiles: [],\n summary: `Verified ${totalFixes} fixes: ${passedFixes} passed. Score: ${newHealthScore}, Gate: ${newQualityGate}, Iteration: ${newIterationCount}`\n };\n}\n```\n\n## State Updates\n\n```javascript\nreturn {\n stateUpdates: {\n applied_fixes: [...updatedWithVerificationResults],\n issues: [...remainingIssues],\n quality_score: newScore,\n quality_gate: newGate,\n iteration_count: iteration + 1\n }\n};\n```\n\n## Error Handling\n\n| Error Type | Recovery |\n|------------|----------|\n| Re-diagnosis fails | Mark as 'inconclusive' |\n| File access error | Skip file verification |\n\n## Next Actions\n\n- If quality_gate === 'pass': action-complete\n- If user chose to continue: restart diagnosis cycle\n- If max_iterations reached: action-complete\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":6887,"content_sha256":"c47a6e3deb86bc61db5e296938ca32950c7791029cf41685b7e1fbbd29760eb9"},{"filename":"phases/orchestrator.md","content":"# Orchestrator\n\nState-driven orchestrator for autonomous skill-tuning workflow.\n\n## Role\n\nRead state → Select action → Execute → Update → Repeat until termination.\n\n## Decision Logic\n\n### Termination Checks (priority order)\n\n| Condition | Action |\n|-----------|--------|\n| `status === 'user_exit'` | null (exit) |\n| `status === 'completed'` | null (exit) |\n| `error_count >= max_errors` | action-abort |\n| `iteration_count >= max_iterations` | action-complete |\n| `quality_gate === 'pass'` | action-complete |\n\n### Action Selection\n\n| Priority | Condition | Action |\n|----------|-----------|--------|\n| 1 | `status === 'pending'` | action-init |\n| 2 | Init done, req analysis missing | action-analyze-requirements |\n| 3 | Req needs clarification | null (wait) |\n| 4 | Req coverage unsatisfied | action-gemini-analysis |\n| 5 | Gemini requested/critical issues | action-gemini-analysis |\n| 6 | Gemini running | null (wait) |\n| 7 | Diagnosis pending (in order) | action-diagnose-{type} |\n| 8 | All diagnosis done, no report | action-generate-report |\n| 9 | Report done, issues exist | action-propose-fixes |\n| 10 | Pending fixes exist | action-apply-fix |\n| 11 | Fixes need verification | action-verify |\n| 12 | New iteration needed | action-diagnose-context (restart) |\n| 13 | Default | action-complete |\n\n**Diagnosis Order**: context → memory → dataflow → agent → docs → token_consumption\n\n**Gemini Triggers**:\n- `gemini_analysis_requested === true`\n- Critical issues detected\n- Focus areas include: architecture, prompt, performance, custom\n- Second iteration with unresolved issues\n\n## State Management\n\n```javascript\n// Read\nconst state = JSON.parse(Read(`${workDir}/state.json`));\n\n// Update (with sliding window for history)\nfunction updateState(workDir, updates) {\n const state = JSON.parse(Read(`${workDir}/state.json`));\n const newState = {\n ...state,\n ...updates,\n updated_at: new Date().toISOString()\n };\n Write(`${workDir}/state.json`, JSON.stringify(newState, null, 2));\n return newState;\n}\n```\n\n## Execution Loop\n\n```javascript\nasync function runOrchestrator(workDir) {\n let iteration = 0;\n const MAX_LOOP = 50;\n\n while (iteration++ \u003c MAX_LOOP) {\n // 1. Read state\n const state = JSON.parse(Read(`${workDir}/state.json`));\n\n // 2. Select action\n const actionId = selectNextAction(state);\n if (!actionId) break;\n\n // 3. Update: mark current action (sliding window)\n updateState(workDir, {\n current_action: actionId,\n action_history: [...state.action_history, {\n action: actionId,\n started_at: new Date().toISOString()\n }].slice(-10) // Keep last 10\n });\n\n // 4. Execute action\n try {\n const actionPrompt = Read(`phases/actions/${actionId}.md`);\n\n // Pass state path + key fields (not full state)\n const stateKeyInfo = {\n status: state.status,\n iteration_count: state.iteration_count,\n quality_gate: state.quality_gate,\n target_skill: { name: state.target_skill.name, path: state.target_skill.path }\n };\n\n const result = await Agent({\n subagent_type: 'universal-executor',\n description: `Execute skill-tuning action: ${actionId}`,\n run_in_background: false,\n prompt: `\n[CONTEXT]\nAction: ${actionId}\nWork directory: ${workDir}\n\n[STATE KEY INFO]\n${JSON.stringify(stateKeyInfo, null, 2)}\n\n[FULL STATE PATH]\n${workDir}/state.json\n(Read full state from this file if needed)\n\n[ACTION INSTRUCTIONS]\n${actionPrompt}\n\n[OUTPUT]\nReturn JSON: { stateUpdates: {}, outputFiles: [], summary: \"...\" }\n`\n });\n\n // 5. Parse result\n let actionResult = result;\n try { actionResult = JSON.parse(result); } catch {}\n\n // 6. Update: mark complete\n updateState(workDir, {\n current_action: null,\n completed_actions: [...state.completed_actions, actionId],\n ...actionResult.stateUpdates\n });\n\n } catch (error) {\n // Error handling (sliding window for errors)\n updateState(workDir, {\n current_action: null,\n errors: [...state.errors, {\n action: actionId,\n message: error.message,\n timestamp: new Date().toISOString()\n }].slice(-5), // Keep last 5\n error_count: state.error_count + 1\n });\n }\n }\n}\n```\n\n## Action Preconditions\n\n| Action | Precondition |\n|--------|-------------|\n| action-init | status='pending' |\n| action-analyze-requirements | Init complete, not done |\n| action-diagnose-* | status='running', focus area includes type |\n| action-gemini-analysis | Requested OR critical issues OR high complexity |\n| action-generate-report | All diagnosis complete |\n| action-propose-fixes | Report generated, issues > 0 |\n| action-apply-fix | pending_fixes > 0 |\n| action-verify | applied_fixes with pending verification |\n| action-complete | Quality gates pass OR max iterations |\n| action-abort | error_count >= max_errors |\n\n## User Interaction Points\n\n1. **action-init**: Confirm target skill, describe issue\n2. **action-propose-fixes**: Select which fixes to apply\n3. **action-verify**: Review verification, decide to continue or stop\n4. **action-complete**: Review final summary\n\n## Error Recovery\n\n| Error Type | Strategy |\n|------------|----------|\n| Action execution failed | Retry up to 3 times, then skip |\n| State parse error | Restore from backup |\n| File write error | Retry with alternative path |\n| User abort | Save state and exit gracefully |\n\n## Termination Conditions\n\n- Normal: `status === 'completed'`, `quality_gate === 'pass'`\n- User: `status === 'user_exit'`\n- Error: `status === 'failed'`, `error_count >= max_errors`\n- Iteration limit: `iteration_count >= max_iterations`\n- Clarification wait: `requirement_analysis.status === 'needs_clarification'` (pause, not terminate)\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":5793,"content_sha256":"b850da7a5129eb75044250660a642981ccf45f9726a33ec629dd619683de8209"},{"filename":"phases/state-schema.md","content":"# State Schema\n\nDefines the state structure for skill-tuning orchestrator.\n\n## State Structure\n\n```typescript\ninterface TuningState {\n // === Core Status ===\n status: 'pending' | 'running' | 'completed' | 'failed';\n started_at: string; // ISO timestamp\n updated_at: string; // ISO timestamp\n\n // === Target Skill Info ===\n target_skill: {\n name: string; // e.g., \"software-manual\"\n path: string; // e.g., \".claude/skills/software-manual\"\n execution_mode: 'sequential' | 'autonomous';\n phases: string[]; // List of phase files\n specs: string[]; // List of spec files\n };\n\n // === User Input ===\n user_issue_description: string; // User's problem description\n focus_areas: string[]; // User-specified focus (optional)\n\n // === Diagnosis Results ===\n diagnosis: {\n context: DiagnosisResult | null;\n memory: DiagnosisResult | null;\n dataflow: DiagnosisResult | null;\n agent: DiagnosisResult | null;\n docs: DocsDiagnosisResult | null; // 文档结构诊断\n token_consumption: DiagnosisResult | null; // Token消耗诊断\n };\n\n // === Issues Found ===\n issues: Issue[];\n issues_by_severity: {\n critical: number;\n high: number;\n medium: number;\n low: number;\n };\n\n // === Fix Management ===\n proposed_fixes: Fix[];\n applied_fixes: AppliedFix[];\n pending_fixes: string[]; // Fix IDs pending application\n\n // === Iteration Control ===\n iteration_count: number;\n max_iterations: number; // Default: 5\n\n // === Quality Metrics ===\n quality_score: number; // 0-100\n quality_gate: 'pass' | 'review' | 'fail';\n\n // === Orchestrator State ===\n completed_actions: string[];\n current_action: string | null;\n action_history: ActionHistoryEntry[];\n\n // === Error Handling ===\n errors: ErrorEntry[];\n error_count: number;\n max_errors: number; // Default: 3\n\n // === Output Paths ===\n work_dir: string;\n backup_dir: string;\n\n // === Final Report (consolidated output) ===\n final_report: string | null; // Markdown summary generated on completion\n\n // === Requirement Analysis (新增) ===\n requirement_analysis: RequirementAnalysis | null;\n}\n\ninterface RequirementAnalysis {\n status: 'pending' | 'completed' | 'needs_clarification';\n analyzed_at: string;\n\n // Phase 1: 维度拆解\n dimensions: Dimension[];\n\n // Phase 2: Spec 匹配\n spec_matches: SpecMatch[];\n\n // Phase 3: 覆盖度\n coverage: {\n total_dimensions: number;\n with_detection: number; // 有 taxonomy pattern\n with_fix_strategy: number; // 有 tuning strategy (满足判断标准)\n coverage_rate: number; // 0-100%\n status: 'satisfied' | 'partial' | 'unsatisfied';\n };\n\n // Phase 4: 歧义\n ambiguities: Ambiguity[];\n}\n\ninterface Dimension {\n id: string; // e.g., \"DIM-001\"\n description: string; // 关注点描述\n keywords: string[]; // 关键词\n inferred_category: string; // 推断的问题类别\n confidence: number; // 置信度 0-1\n}\n\ninterface SpecMatch {\n dimension_id: string;\n taxonomy_match: {\n category: string; // e.g., \"context_explosion\"\n pattern_ids: string[]; // e.g., [\"CTX-001\", \"CTX-003\"]\n severity_hint: string;\n } | null;\n strategy_match: {\n strategies: string[]; // e.g., [\"sliding_window\", \"path_reference\"]\n risk_levels: string[];\n } | null;\n has_fix: boolean; // 满足性判断核心\n}\n\ninterface Ambiguity {\n dimension_id: string;\n type: 'multi_category' | 'vague_description' | 'conflicting_keywords';\n description: string;\n possible_interpretations: string[];\n needs_clarification: boolean;\n}\n\ninterface DiagnosisResult {\n status: 'completed' | 'skipped' | 'failed';\n issues_found: number;\n severity: 'critical' | 'high' | 'medium' | 'low' | 'none';\n execution_time_ms: number;\n details: {\n patterns_checked: string[];\n patterns_matched: string[];\n evidence: Evidence[];\n recommendations: string[];\n };\n}\n\ninterface DocsDiagnosisResult extends DiagnosisResult {\n redundancies: Redundancy[];\n conflicts: Conflict[];\n}\n\ninterface Redundancy {\n id: string; // e.g., \"DOC-RED-001\"\n type: 'state_schema' | 'strategy_mapping' | 'type_definition' | 'other';\n files: string[]; // 涉及的文件列表\n description: string; // 冗余描述\n severity: 'high' | 'medium' | 'low';\n merge_suggestion: string; // 合并建议\n}\n\ninterface Conflict {\n id: string; // e.g., \"DOC-CON-001\"\n type: 'priority' | 'mapping' | 'definition';\n files: string[]; // 涉及的文件列表\n key: string; // 冲突的键/概念\n definitions: {\n file: string;\n value: string;\n location?: string;\n }[];\n resolution_suggestion: string; // 解决建议\n}\n\ninterface Evidence {\n file: string;\n line?: number;\n pattern: string;\n context: string;\n severity: string;\n}\n\ninterface Issue {\n id: string; // e.g., \"ISS-001\"\n type: 'context_explosion' | 'memory_loss' | 'dataflow_break' | 'agent_failure' | 'token_consumption';\n severity: 'critical' | 'high' | 'medium' | 'low';\n priority: number; // 1 = highest\n location: {\n file: string;\n line_start?: number;\n line_end?: number;\n phase?: string;\n };\n description: string;\n evidence: string[];\n root_cause: string;\n impact: string;\n suggested_fix: string;\n related_issues: string[]; // Issue IDs\n}\n\ninterface Fix {\n id: string; // e.g., \"FIX-001\"\n issue_ids: string[]; // Issues this fix addresses\n strategy: FixStrategy;\n description: string;\n rationale: string;\n changes: FileChange[];\n risk: 'low' | 'medium' | 'high';\n estimated_impact: string;\n verification_steps: string[];\n}\n\ntype FixStrategy =\n | 'context_summarization' // Add context compression\n | 'sliding_window' // Implement sliding context window\n | 'structured_state' // Convert to structured state passing\n | 'constraint_injection' // Add constraint propagation\n | 'checkpoint_restore' // Add checkpointing mechanism\n | 'schema_enforcement' // Add data contract validation\n | 'orchestrator_refactor' // Refactor agent coordination\n | 'state_centralization' // Centralize state management\n | 'prompt_compression' // Extract static text, use templates\n | 'lazy_loading' // Pass paths instead of content\n | 'output_minimization' // Return minimal structured JSON\n | 'state_field_reduction' // Audit and consolidate state fields\n | 'custom'; // Custom fix\n\ninterface FileChange {\n file: string;\n action: 'create' | 'modify' | 'delete';\n old_content?: string;\n new_content?: string;\n diff?: string;\n}\n\ninterface AppliedFix {\n fix_id: string;\n applied_at: string;\n success: boolean;\n backup_path: string;\n verification_result: 'pass' | 'fail' | 'pending';\n rollback_available: boolean;\n}\n\ninterface ActionHistoryEntry {\n action: string;\n started_at: string;\n completed_at: string;\n result: 'success' | 'failure' | 'skipped';\n output_files: string[];\n}\n\ninterface ErrorEntry {\n action: string;\n message: string;\n timestamp: string;\n recoverable: boolean;\n}\n```\n\n## Initial State Template\n\n```json\n{\n \"status\": \"pending\",\n \"started_at\": null,\n \"updated_at\": null,\n \"target_skill\": {\n \"name\": null,\n \"path\": null,\n \"execution_mode\": null,\n \"phases\": [],\n \"specs\": []\n },\n \"user_issue_description\": \"\",\n \"focus_areas\": [],\n \"diagnosis\": {\n \"context\": null,\n \"memory\": null,\n \"dataflow\": null,\n \"agent\": null,\n \"docs\": null,\n \"token_consumption\": null\n },\n \"issues\": [],\n \"issues_by_severity\": {\n \"critical\": 0,\n \"high\": 0,\n \"medium\": 0,\n \"low\": 0\n },\n \"proposed_fixes\": [],\n \"applied_fixes\": [],\n \"pending_fixes\": [],\n \"iteration_count\": 0,\n \"max_iterations\": 5,\n \"quality_score\": 0,\n \"quality_gate\": \"fail\",\n \"completed_actions\": [],\n \"current_action\": null,\n \"action_history\": [],\n \"errors\": [],\n \"error_count\": 0,\n \"max_errors\": 3,\n \"work_dir\": null,\n \"backup_dir\": null,\n \"final_report\": null,\n \"requirement_analysis\": null\n}\n```\n\n## State Transition Diagram\n\n```\n ┌─────────────┐\n │ pending │\n └──────┬──────┘\n │ action-init\n ↓\n ┌─────────────┐\n ┌──────────│ running │──────────┐\n │ └──────┬──────┘ │\n │ │ │\n diagnosis │ ┌────────────┼────────────┐ │ error_count >= 3\n actions │ │ │ │ │\n │ ↓ ↓ ↓ │\n │ context memory dataflow │\n │ │ │ │ │\n │ └────────────┼────────────┘ │\n │ │ │\n │ ↓ │\n │ action-verify │\n │ │ │\n │ ┌───────────┼───────────┐ │\n │ │ │ │ │\n │ ↓ ↓ ↓ │\n │ quality iterate apply │\n │ gate=pass (\u003c max) fix │\n │ │ │ │ │\n │ │ └───────────┘ │\n │ ↓ ↓\n │ ┌─────────────┐ ┌─────────────┐\n └→│ completed │ │ failed │\n └─────────────┘ └─────────────┘\n```\n\n## State Update Rules\n\n### Atomicity\nAll state updates must be atomic - read current state, apply changes, write entire state.\n\n### Immutability\nNever mutate state in place. Always create new state object with changes.\n\n### Validation\nBefore writing state, validate against schema to prevent corruption.\n\n### Timestamps\nAlways update `updated_at` on every state change.\n\n```javascript\nfunction updateState(workDir, updates) {\n const currentState = JSON.parse(Read(`${workDir}/state.json`));\n\n const newState = {\n ...currentState,\n ...updates,\n updated_at: new Date().toISOString()\n };\n\n // Validate before write\n if (!validateState(newState)) {\n throw new Error('Invalid state update');\n }\n\n Write(`${workDir}/state.json`, JSON.stringify(newState, null, 2));\n return newState;\n}\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":11278,"content_sha256":"13ebd2e10e28ee3bb4fbe812e242be85aba5d3612163db2498258b655afac345"},{"filename":"specs/category-mappings.json","content":"{\n \"version\": \"1.0.0\",\n \"description\": \"Centralized category mappings for skill-tuning analysis and fix proposal\",\n \"categories\": {\n \"authoring_principles_violation\": {\n \"pattern_ids\": [\"APV-001\", \"APV-002\", \"APV-003\", \"APV-004\", \"APV-005\", \"APV-006\"],\n \"severity_hint\": \"critical\",\n \"strategies\": [\"eliminate_intermediate_files\", \"minimize_state\", \"context_passing\"],\n \"risk_levels\": [\"low\", \"low\", \"low\"],\n \"detection_focus\": \"Intermediate files, state bloat, file relay patterns\",\n \"priority_order\": [1, 2, 3]\n },\n \"context_explosion\": {\n \"pattern_ids\": [\"CTX-001\", \"CTX-002\", \"CTX-003\", \"CTX-004\", \"CTX-005\"],\n \"severity_hint\": \"high\",\n \"strategies\": [\"sliding_window\", \"path_reference\", \"context_summarization\", \"structured_state\"],\n \"risk_levels\": [\"low\", \"low\", \"low\", \"medium\"],\n \"detection_focus\": \"Token accumulation, content passing patterns\",\n \"priority_order\": [1, 2, 3, 4]\n },\n \"memory_loss\": {\n \"pattern_ids\": [\"MEM-001\", \"MEM-002\", \"MEM-003\", \"MEM-004\", \"MEM-005\"],\n \"severity_hint\": \"high\",\n \"strategies\": [\"constraint_injection\", \"state_constraints_field\", \"checkpoint_restore\", \"goal_embedding\"],\n \"risk_levels\": [\"low\", \"low\", \"low\", \"medium\"],\n \"detection_focus\": \"Constraint propagation, checkpoint mechanisms\",\n \"priority_order\": [1, 2, 3, 4]\n },\n \"dataflow_break\": {\n \"pattern_ids\": [\"DF-001\", \"DF-002\", \"DF-003\", \"DF-004\", \"DF-005\"],\n \"severity_hint\": \"critical\",\n \"strategies\": [\"state_centralization\", \"schema_enforcement\", \"field_normalization\"],\n \"risk_levels\": [\"medium\", \"low\", \"low\"],\n \"detection_focus\": \"State storage, schema validation\",\n \"priority_order\": [1, 2, 3]\n },\n \"agent_failure\": {\n \"pattern_ids\": [\"AGT-001\", \"AGT-002\", \"AGT-003\", \"AGT-004\", \"AGT-005\", \"AGT-006\"],\n \"severity_hint\": \"high\",\n \"strategies\": [\"error_wrapping\", \"result_validation\", \"flatten_nesting\"],\n \"risk_levels\": [\"low\", \"low\", \"medium\"],\n \"detection_focus\": \"Error handling, result validation\",\n \"priority_order\": [1, 2, 3]\n },\n \"prompt_quality\": {\n \"pattern_ids\": [],\n \"severity_hint\": \"medium\",\n \"strategies\": [\"structured_prompt\", \"output_schema\", \"grounding_context\", \"format_enforcement\"],\n \"risk_levels\": [\"low\", \"low\", \"medium\", \"low\"],\n \"detection_focus\": null,\n \"needs_gemini_analysis\": true,\n \"priority_order\": [1, 2, 3, 4]\n },\n \"architecture\": {\n \"pattern_ids\": [],\n \"severity_hint\": \"medium\",\n \"strategies\": [\"phase_decomposition\", \"interface_contracts\", \"plugin_architecture\", \"state_machine\"],\n \"risk_levels\": [\"medium\", \"medium\", \"high\", \"medium\"],\n \"detection_focus\": null,\n \"needs_gemini_analysis\": true,\n \"priority_order\": [1, 2, 3, 4]\n },\n \"performance\": {\n \"pattern_ids\": [\"CTX-001\", \"CTX-003\"],\n \"severity_hint\": \"medium\",\n \"strategies\": [\"token_budgeting\", \"parallel_execution\", \"result_caching\", \"lazy_loading\"],\n \"risk_levels\": [\"low\", \"low\", \"low\", \"low\"],\n \"detection_focus\": \"Reuses context explosion detection\",\n \"priority_order\": [1, 2, 3, 4]\n },\n \"error_handling\": {\n \"pattern_ids\": [\"AGT-001\", \"AGT-002\"],\n \"severity_hint\": \"medium\",\n \"strategies\": [\"graceful_degradation\", \"error_propagation\", \"structured_logging\", \"error_context\"],\n \"risk_levels\": [\"low\", \"low\", \"low\", \"low\"],\n \"detection_focus\": \"Reuses agent failure detection\",\n \"priority_order\": [1, 2, 3, 4]\n },\n \"output_quality\": {\n \"pattern_ids\": [],\n \"severity_hint\": \"medium\",\n \"strategies\": [\"quality_gates\", \"output_validation\", \"template_enforcement\", \"completeness_check\"],\n \"risk_levels\": [\"low\", \"low\", \"low\", \"low\"],\n \"detection_focus\": null,\n \"needs_gemini_analysis\": true,\n \"priority_order\": [1, 2, 3, 4]\n },\n \"user_experience\": {\n \"pattern_ids\": [],\n \"severity_hint\": \"low\",\n \"strategies\": [\"progress_tracking\", \"status_communication\", \"interactive_checkpoints\", \"guided_workflow\"],\n \"risk_levels\": [\"low\", \"low\", \"low\", \"low\"],\n \"detection_focus\": null,\n \"needs_gemini_analysis\": true,\n \"priority_order\": [1, 2, 3, 4]\n },\n \"token_consumption\": {\n \"pattern_ids\": [\"TKN-001\", \"TKN-002\", \"TKN-003\", \"TKN-004\", \"TKN-005\"],\n \"severity_hint\": \"medium\",\n \"strategies\": [\"prompt_compression\", \"lazy_loading\", \"output_minimization\", \"state_field_reduction\", \"sliding_window\"],\n \"risk_levels\": [\"low\", \"low\", \"low\", \"low\", \"low\"],\n \"detection_focus\": \"Verbose prompts, excessive state fields, full content passing, unbounded arrays, redundant I/O\",\n \"priority_order\": [1, 2, 3, 4, 5]\n }\n },\n \"keywords\": {\n \"chinese\": {\n \"token\": \"context_explosion\",\n \"上下文\": \"context_explosion\",\n \"爆炸\": \"context_explosion\",\n \"太长\": \"context_explosion\",\n \"超限\": \"context_explosion\",\n \"膨胀\": \"context_explosion\",\n \"遗忘\": \"memory_loss\",\n \"忘记\": \"memory_loss\",\n \"指令丢失\": \"memory_loss\",\n \"约束消失\": \"memory_loss\",\n \"目标漂移\": \"memory_loss\",\n \"状态\": \"dataflow_break\",\n \"数据\": \"dataflow_break\",\n \"格式\": \"dataflow_break\",\n \"不一致\": \"dataflow_break\",\n \"丢失\": \"dataflow_break\",\n \"损坏\": \"dataflow_break\",\n \"agent\": \"agent_failure\",\n \"子任务\": \"agent_failure\",\n \"失败\": \"agent_failure\",\n \"嵌套\": \"agent_failure\",\n \"调用\": \"agent_failure\",\n \"协调\": \"agent_failure\",\n \"慢\": \"performance\",\n \"性能\": \"performance\",\n \"效率\": \"performance\",\n \"延迟\": \"performance\",\n \"提示词\": \"prompt_quality\",\n \"输出不稳定\": \"prompt_quality\",\n \"幻觉\": \"prompt_quality\",\n \"架构\": \"architecture\",\n \"结构\": \"architecture\",\n \"模块\": \"architecture\",\n \"耦合\": \"architecture\",\n \"扩展\": \"architecture\",\n \"错误\": \"error_handling\",\n \"异常\": \"error_handling\",\n \"恢复\": \"error_handling\",\n \"降级\": \"error_handling\",\n \"崩溃\": \"error_handling\",\n \"输出\": \"output_quality\",\n \"质量\": \"output_quality\",\n \"验证\": \"output_quality\",\n \"不完整\": \"output_quality\",\n \"交互\": \"user_experience\",\n \"体验\": \"user_experience\",\n \"进度\": \"user_experience\",\n \"反馈\": \"user_experience\",\n \"不清晰\": \"user_experience\",\n \"中间文件\": \"authoring_principles_violation\",\n \"临时文件\": \"authoring_principles_violation\",\n \"文件中转\": \"authoring_principles_violation\",\n \"state膨胀\": \"authoring_principles_violation\",\n \"token消耗\": \"token_consumption\",\n \"token优化\": \"token_consumption\",\n \"产出简化\": \"token_consumption\",\n \"冗长\": \"token_consumption\",\n \"精简\": \"token_consumption\"\n },\n \"english\": {\n \"token\": \"context_explosion\",\n \"context\": \"context_explosion\",\n \"explosion\": \"context_explosion\",\n \"overflow\": \"context_explosion\",\n \"bloat\": \"context_explosion\",\n \"forget\": \"memory_loss\",\n \"lost\": \"memory_loss\",\n \"drift\": \"memory_loss\",\n \"constraint\": \"memory_loss\",\n \"goal\": \"memory_loss\",\n \"state\": \"dataflow_break\",\n \"data\": \"dataflow_break\",\n \"format\": \"dataflow_break\",\n \"inconsistent\": \"dataflow_break\",\n \"corrupt\": \"dataflow_break\",\n \"agent\": \"agent_failure\",\n \"subtask\": \"agent_failure\",\n \"fail\": \"agent_failure\",\n \"nested\": \"agent_failure\",\n \"call\": \"agent_failure\",\n \"coordinate\": \"agent_failure\",\n \"slow\": \"performance\",\n \"performance\": \"performance\",\n \"efficiency\": \"performance\",\n \"latency\": \"performance\",\n \"prompt\": \"prompt_quality\",\n \"unstable\": \"prompt_quality\",\n \"hallucination\": \"prompt_quality\",\n \"architecture\": \"architecture\",\n \"structure\": \"architecture\",\n \"module\": \"architecture\",\n \"coupling\": \"architecture\",\n \"error\": \"error_handling\",\n \"exception\": \"error_handling\",\n \"recovery\": \"error_handling\",\n \"crash\": \"error_handling\",\n \"output\": \"output_quality\",\n \"quality\": \"output_quality\",\n \"validation\": \"output_quality\",\n \"incomplete\": \"output_quality\",\n \"interaction\": \"user_experience\",\n \"ux\": \"user_experience\",\n \"progress\": \"user_experience\",\n \"feedback\": \"user_experience\",\n \"intermediate\": \"authoring_principles_violation\",\n \"temp\": \"authoring_principles_violation\",\n \"relay\": \"authoring_principles_violation\",\n \"verbose\": \"token_consumption\",\n \"minimize\": \"token_consumption\",\n \"compress\": \"token_consumption\",\n \"simplify\": \"token_consumption\",\n \"reduction\": \"token_consumption\"\n }\n },\n \"category_labels\": {\n \"context_explosion\": \"Context Explosion\",\n \"memory_loss\": \"Long-tail Forgetting\",\n \"dataflow_break\": \"Data Flow Disruption\",\n \"agent_failure\": \"Agent Coordination Failure\",\n \"prompt_quality\": \"Prompt Quality\",\n \"architecture\": \"Architecture\",\n \"performance\": \"Performance\",\n \"error_handling\": \"Error Handling\",\n \"output_quality\": \"Output Quality\",\n \"user_experience\": \"User Experience\",\n \"authoring_principles_violation\": \"Authoring Principles Violation\",\n \"token_consumption\": \"Token Consumption\",\n \"custom\": \"Custom\"\n },\n \"category_labels_chinese\": {\n \"context_explosion\": \"Context Explosion\",\n \"memory_loss\": \"Long-tail Forgetting\",\n \"dataflow_break\": \"Data Flow Disruption\",\n \"agent_failure\": \"Agent Coordination Failure\",\n \"prompt_quality\": \"Prompt Quality\",\n \"architecture\": \"Architecture Issues\",\n \"performance\": \"Performance Issues\",\n \"error_handling\": \"Error Handling\",\n \"output_quality\": \"Output Quality\",\n \"user_experience\": \"User Experience\",\n \"authoring_principles_violation\": \"Authoring Principles Violation\",\n \"token_consumption\": \"Token Consumption Optimization\",\n \"custom\": \"Other Issues\"\n },\n \"category_descriptions\": {\n \"context_explosion\": \"Token accumulation causing prompt size to grow unbounded\",\n \"memory_loss\": \"Early instructions or constraints lost in later phases\",\n \"dataflow_break\": \"State data inconsistency between phases\",\n \"agent_failure\": \"Sub-agent call failures or abnormal results\",\n \"prompt_quality\": \"Vague prompts causing unstable outputs\",\n \"architecture\": \"Improper phase division or module structure\",\n \"performance\": \"Slow execution or high token consumption\",\n \"error_handling\": \"Incomplete error recovery mechanisms\",\n \"output_quality\": \"Output validation or completeness issues\",\n \"user_experience\": \"Interaction or feedback clarity issues\",\n \"authoring_principles_violation\": \"Violation of skill authoring principles\",\n \"token_consumption\": \"Excessive token usage from verbose prompts, large state objects, or redundant I/O patterns\",\n \"custom\": \"Requires custom analysis\"\n },\n \"fix_priority_order\": {\n \"P0\": [\"dataflow_break\", \"authoring_principles_violation\"],\n \"P1\": [\"agent_failure\"],\n \"P2\": [\"context_explosion\", \"token_consumption\"],\n \"P3\": [\"memory_loss\"]\n },\n \"cross_category_dependencies\": {\n \"context_explosion\": [\"memory_loss\"],\n \"dataflow_break\": [\"agent_failure\"],\n \"agent_failure\": [\"context_explosion\"]\n },\n \"fallback\": {\n \"strategies\": [\"custom\"],\n \"risk_levels\": [\"medium\"],\n \"has_fix\": true,\n \"needs_gemini_analysis\": true\n }\n}\n","content_type":"application/json; charset=utf-8","language":"json","size":11487,"content_sha256":"b281db49137420a97400a483a8d8ae7366a433c2d59b7768eef4830d7c633f63"},{"filename":"specs/dimension-mapping.md","content":"# Dimension to Spec Mapping\n\n维度关键词到 Spec 的映射规则，用于 action-analyze-requirements 阶段的自动匹配。\n\n## When to Use\n\n| Phase | Usage |\n|-------|-------|\n| action-analyze-requirements | 维度→类别→Spec 自动匹配 |\n| action-propose-fixes | 策略选择参考 |\n\n---\n\n## Keyword → Category Mapping\n\n基于关键词将用户描述的维度映射到问题类别。\n\n### 中英文关键词表\n\n| Keywords (中文) | Keywords (英文) | Primary Category | Secondary |\n|----------------|-----------------|------------------|-----------|\n| token, 上下文, 爆炸, 太长, 超限, 膨胀 | token, context, explosion, overflow, bloat | context_explosion | - |\n| 遗忘, 忘记, 指令丢失, 约束消失, 目标漂移 | forget, lost, drift, constraint, goal | memory_loss | - |\n| 状态, 数据, 格式, 不一致, 丢失, 损坏 | state, data, format, inconsistent, corrupt | dataflow_break | - |\n| agent, 子任务, 失败, 嵌套, 调用, 协调 | agent, subtask, fail, nested, call, coordinate | agent_failure | - |\n| 慢, 性能, 效率, token 消耗, 延迟 | slow, performance, efficiency, latency | performance | context_explosion |\n| 提示词, prompt, 输出不稳定, 幻觉 | prompt, unstable, hallucination | prompt_quality | - |\n| 架构, 结构, 模块, 耦合, 扩展 | architecture, structure, module, coupling | architecture | - |\n| 错误, 异常, 恢复, 降级, 崩溃 | error, exception, recovery, crash | error_handling | agent_failure |\n| 输出, 质量, 格式, 验证, 不完整 | output, quality, validation, incomplete | output_quality | - |\n| 交互, 体验, 进度, 反馈, 不清晰 | interaction, ux, progress, feedback | user_experience | - |\n| 重复, 冗余, 多处定义, 相同内容 | duplicate, redundant, multiple definitions | doc_redundancy | - |\n| 冲突, 不一致, 定义不同, 矛盾 | conflict, inconsistent, mismatch, contradiction | doc_conflict | - |\n\n### Matching Algorithm\n\n```javascript\nfunction matchCategory(keywords) {\n const categoryScores = {};\n \n for (const keyword of keywords) {\n const normalizedKeyword = keyword.toLowerCase();\n \n for (const [category, categoryKeywords] of Object.entries(KEYWORD_MAP)) {\n if (categoryKeywords.some(k => normalizedKeyword.includes(k) || k.includes(normalizedKeyword))) {\n categoryScores[category] = (categoryScores[category] || 0) + 1;\n }\n }\n }\n \n // 返回得分最高的类别\n const sorted = Object.entries(categoryScores).sort((a, b) => b[1] - a[1]);\n \n if (sorted.length === 0) return null;\n \n // 如果前两名得分相同，返回多类别（需澄清）\n if (sorted.length > 1 && sorted[0][1] === sorted[1][1]) {\n return {\n primary: sorted[0][0],\n secondary: sorted[1][0],\n ambiguous: true\n };\n }\n \n return {\n primary: sorted[0][0],\n secondary: sorted[1]?.[0] || null,\n ambiguous: false\n };\n}\n```\n\n---\n\n## Category → Taxonomy Pattern Mapping\n\n将问题类别映射到 problem-taxonomy.md 中的检测模式。\n\n| Category | Pattern IDs | Detection Focus |\n|----------|-------------|-----------------|\n| context_explosion | CTX-001, CTX-002, CTX-003, CTX-004, CTX-005 | Token 累积、内容传递模式 |\n| memory_loss | MEM-001, MEM-002, MEM-003, MEM-004, MEM-005 | 约束传播、检查点机制 |\n| dataflow_break | DF-001, DF-002, DF-003, DF-004, DF-005 | 状态存储、Schema 验证 |\n| agent_failure | AGT-001, AGT-002, AGT-003, AGT-004, AGT-005, AGT-006 | 错误处理、结果验证 |\n| prompt_quality | - | (无内置检测，需 Gemini 分析) |\n| architecture | - | (无内置检测，需 Gemini 分析) |\n| performance | CTX-001, CTX-003 | (复用 context 检测) |\n| error_handling | AGT-001, AGT-002 | (复用 agent 检测) |\n| output_quality | - | (无内置检测，需 Gemini 分析) |\n| user_experience | - | (无内置检测，需 Gemini 分析) |\n| doc_redundancy | DOC-RED-001, DOC-RED-002, DOC-RED-003 | 重复定义检测 |\n| doc_conflict | DOC-CON-001, DOC-CON-002 | 冲突定义检测 |\n\n---\n\n## Category → Strategy Mapping\n\n将问题类别映射到 tuning-strategies.md 中的修复策略。\n\n### Core Categories (有完整策略)\n\n| Category | Available Strategies | Risk Level |\n|----------|---------------------|------------|\n| context_explosion | sliding_window, path_reference, context_summarization, structured_state | Low-Medium |\n| memory_loss | constraint_injection, state_constraints_field, checkpoint_restore, goal_embedding | Low-Medium |\n| dataflow_break | state_centralization, schema_enforcement, field_normalization | Low-Medium |\n| agent_failure | error_wrapping, result_validation, flatten_nesting | Low-Medium |\n| doc_redundancy | consolidate_to_ssot, centralize_mapping_config | Low-Medium |\n| doc_conflict | reconcile_conflicting_definitions | Low |\n\n### Extended Categories (需 Gemini 生成策略)\n\n| Category | Available Strategies | Risk Level |\n|----------|---------------------|------------|\n| prompt_quality | structured_prompt, output_schema, grounding_context, format_enforcement | Low |\n| architecture | phase_decomposition, interface_contracts, plugin_architecture, state_machine | Medium-High |\n| performance | token_budgeting, parallel_execution, result_caching, lazy_loading | Low-Medium |\n| error_handling | graceful_degradation, error_propagation, structured_logging, error_context | Low |\n| output_quality | quality_gates, output_validation, template_enforcement, completeness_check | Low |\n| user_experience | progress_tracking, status_communication, interactive_checkpoints, guided_workflow | Low |\n\n---\n\n## Coverage Rules\n\n### Satisfaction Criteria\n\n判断\"是否满足需求\"的标准：\n\n```javascript\nfunction evaluateSatisfaction(specMatch) {\n // 核心标准：有可用的修复策略\n const hasFix = specMatch.strategy_match !== null && \n specMatch.strategy_match.strategies.length > 0;\n \n // 辅助标准：有检测手段\n const hasDetection = specMatch.taxonomy_match !== null;\n \n return {\n satisfied: hasFix,\n detection_available: hasDetection,\n needs_gemini: !hasDetection // 无内置检测时需要 Gemini 分析\n };\n}\n```\n\n### Coverage Status Thresholds\n\n| Status | Condition |\n|--------|-----------|\n| satisfied | coverage_rate >= 80% |\n| partial | 50% \u003c= coverage_rate \u003c 80% |\n| unsatisfied | coverage_rate \u003c 50% |\n\n---\n\n## Fallback Rules\n\n当无法匹配到具体类别时的处理：\n\n```javascript\nfunction handleUnmatchedDimension(dimension) {\n return {\n dimension_id: dimension.id,\n taxonomy_match: null,\n strategy_match: {\n strategies: ['custom'], // Fallback to custom strategy\n risk_levels: ['medium']\n },\n has_fix: true, // custom 策略视为\"可满足\"\n needs_gemini_analysis: true,\n fallback_reason: 'no_keyword_match'\n };\n}\n```\n\n---\n\n## Usage Example\n\n```javascript\n// 输入：用户描述 \"skill 执行太慢，而且有时候会忘记最初的指令\"\n\n// Step 1: Gemini 拆解为维度\nconst dimensions = [\n { id: 'DIM-001', description: '执行太慢', keywords: ['慢', '执行'], confidence: 0.9 },\n { id: 'DIM-002', description: '忘记最初指令', keywords: ['忘记', '指令'], confidence: 0.85 }\n];\n\n// Step 2: 匹配类别\n// DIM-001 → performance (慢)\n// DIM-002 → memory_loss (忘记, 指令)\n\n// Step 3: 匹配 Spec\nconst specMatches = [\n {\n dimension_id: 'DIM-001',\n taxonomy_match: { category: 'performance', pattern_ids: ['CTX-001', 'CTX-003'], severity_hint: 'medium' },\n strategy_match: { strategies: ['token_budgeting', 'parallel_execution'], risk_levels: ['low', 'low'] },\n has_fix: true\n },\n {\n dimension_id: 'DIM-002',\n taxonomy_match: { category: 'memory_loss', pattern_ids: ['MEM-001', 'MEM-002'], severity_hint: 'high' },\n strategy_match: { strategies: ['constraint_injection', 'checkpoint_restore'], risk_levels: ['low', 'low'] },\n has_fix: true\n }\n];\n\n// Step 4: 评估覆盖度\n// 2/2 = 100% → satisfied\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":7964,"content_sha256":"799f9d72fbe0400754c475012cb9a514ad0ae88e282e9a861d7f8591d7d5efed"},{"filename":"specs/problem-taxonomy.md","content":"# Problem Taxonomy\n\nClassification of skill execution issues with detection patterns and severity criteria.\n\n## Quick Reference\n\n| Category | Priority | Detection | Fix Strategy |\n|----------|----------|-----------|--------------|\n| Authoring Violation | P0 | Intermediate files, state bloat, file relay | eliminate_intermediate, minimize_state |\n| Data Flow Disruption | P1 | Scattered state, inconsistent formats | state_centralization, schema_enforcement |\n| Agent Coordination | P2 | Fragile chains, no error handling | error_wrapping, result_validation |\n| Context Explosion | P3 | Unbounded history, full content passing | sliding_window, path_reference |\n| Long-tail Forgetting | P4 | Early constraint loss | constraint_injection, checkpoint_restore |\n| Token Consumption | P5 | Verbose prompts, redundant I/O | prompt_compression, lazy_loading |\n| Doc Redundancy | P6 | Repeated definitions | consolidate_to_ssot |\n| Doc Conflict | P7 | Inconsistent definitions | reconcile_definitions |\n\n---\n\n## 0. Authoring Principles Violation (P0)\n\n**Definition**: Violates skill authoring principles (simplicity, no intermediate files, context passing).\n\n**Detection Patterns**:\n\n| Pattern ID | Check | Description |\n|------------|-------|-------------|\n| APV-001 | `/Write\\([^)]*temp-\\|intermediate-/` | Intermediate file writes |\n| APV-002 | `/Write\\([^)]+\\)[\\s\\S]{0,50}Read\\([^)]+\\)/` | Write-then-read relay |\n| APV-003 | State schema > 15 fields | Excessive state fields |\n| APV-004 | `/_history\\s*[.=].*push\\|concat/` | Unbounded array growth |\n| APV-005 | `/debug_\\|_cache\\|_temp/` in state | Debug/cache field residue |\n| APV-006 | Same data in multiple fields | Duplicate storage |\n\n**Impact**: Critical (>5 intermediate files), High (>20 state fields), Medium (debug fields), Low (naming issues)\n\n---\n\n## 1. Context Explosion (P3)\n\n**Definition**: Unbounded token accumulation causing prompt size growth.\n\n**Detection Patterns**:\n\n| Pattern ID | Check | Description |\n|------------|-------|-------------|\n| CTX-001 | `/history\\s*[.=].*push\\|concat/` | History array growth |\n| CTX-002 | `/JSON\\.stringify\\s*\\(\\s*state\\s*\\)/` | Full state serialization |\n| CTX-003 | `/Read\\([^)]+\\)\\s*[\\+,]/` | Multiple file content concatenation |\n| CTX-004 | `/return\\s*\\{[^}]*content:/` | Agent returning full content |\n| CTX-005 | File > 5000 chars without summarization | Long prompts |\n\n**Impact**: Critical (>128K tokens), High (>50K per iteration), Medium (10%+ growth), Low (manageable)\n\n---\n\n## 2. Long-tail Forgetting (P4)\n\n**Definition**: Loss of early instructions/constraints in long chains.\n\n**Detection Patterns**:\n\n| Pattern ID | Check | Description |\n|------------|-------|-------------|\n| MEM-001 | Later phases missing constraint reference | Constraint not forwarded |\n| MEM-002 | `/\\[TASK\\][^[]*(?!\\[CONSTRAINTS\\])/` | Task without constraints section |\n| MEM-003 | Key phases without checkpoint | Missing state preservation |\n| MEM-004 | State lacks `original_requirements` | No constraint persistence |\n| MEM-005 | No verification phase | Output not checked against intent |\n\n**Impact**: Critical (goal lost), High (constraints ignored), Medium (some missing), Low (minor drift)\n\n---\n\n## 3. Data Flow Disruption (P1)\n\n**Definition**: Inconsistent state management causing data loss/corruption.\n\n**Detection Patterns**:\n\n| Pattern ID | Check | Description |\n|------------|-------|-------------|\n| DF-001 | Multiple state file writes | Scattered state storage |\n| DF-002 | Same concept, different names | Field naming inconsistency |\n| DF-003 | JSON.parse without validation | Missing schema validation |\n| DF-004 | Files written but never read | Orphaned outputs |\n| DF-005 | Autonomous skill without state-schema | Undefined state structure |\n\n**Impact**: Critical (data loss), High (state inconsistency), Medium (potential inconsistency), Low (naming)\n\n---\n\n## 4. Agent Coordination Failure (P2)\n\n**Definition**: Fragile agent call patterns causing cascading failures.\n\n**Detection Patterns**:\n\n| Pattern ID | Check | Description |\n|------------|-------|-------------|\n| AGT-001 | Task without try-catch | Missing error handling |\n| AGT-002 | Result used without validation | No return value check |\n| AGT-003 | >3 different agent types | Agent type proliferation |\n| AGT-004 | Nested Task in prompt | Agent calling agent |\n| AGT-005 | Task used but not in allowed-tools | Tool declaration mismatch |\n| AGT-006 | Multiple return formats | Inconsistent agent output |\n\n**Impact**: Critical (crash on failure), High (unpredictable behavior), Medium (occasional issues), Low (minor)\n\n---\n\n## 5. Documentation Redundancy (P6)\n\n**Definition**: Same definition (State Schema, mappings, types) repeated across files.\n\n**Detection Patterns**:\n\n| Pattern ID | Check | Description |\n|------------|-------|-------------|\n| DOC-RED-001 | Cross-file semantic comparison | State Schema duplication |\n| DOC-RED-002 | Code block vs spec comparison | Hardcoded config duplication |\n| DOC-RED-003 | `/interface\\s+(\\w+)/` same-name scan | Interface/type duplication |\n\n**Impact**: High (core definitions), Medium (type definitions), Low (example code)\n\n---\n\n## 6. Token Consumption (P5)\n\n**Definition**: Excessive token usage from verbose prompts, large state, inefficient I/O.\n\n**Detection Patterns**:\n\n| Pattern ID | Check | Description |\n|------------|-------|-------------|\n| TKN-001 | File size > 4KB | Verbose prompt files |\n| TKN-002 | State fields > 15 | Excessive state schema |\n| TKN-003 | `/Read\\([^)]+\\)\\s*[\\+,]/` | Full content passing |\n| TKN-004 | `/.push\\|concat(?!.*\\.slice)/` | Unbounded array growth |\n| TKN-005 | `/Write\\([^)]+\\)[\\s\\S]{0,100}Read\\([^)]+\\)/` | Write-then-read pattern |\n\n**Impact**: High (multiple TKN-003/004), Medium (verbose files), Low (minor optimization)\n\n---\n\n## 7. Documentation Conflict (P7)\n\n**Definition**: Same concept defined inconsistently across files.\n\n**Detection Patterns**:\n\n| Pattern ID | Check | Description |\n|------------|-------|-------------|\n| DOC-CON-001 | Key-value consistency check | Same key, different values |\n| DOC-CON-002 | Implementation vs docs comparison | Hardcoded vs documented mismatch |\n\n**Impact**: Critical (priority/category conflicts), High (strategy mapping inconsistency), Medium (example mismatch)\n\n---\n\n## Severity Calculation\n\n```javascript\nfunction calculateSeverity(issue) {\n const weights = { execution: 40, data_integrity: 30, frequency: 20, complexity: 10 };\n let score = 0;\n\n if (issue.blocks_execution) score += weights.execution;\n if (issue.causes_data_loss) score += weights.data_integrity;\n if (issue.occurs_every_run) score += weights.frequency;\n if (issue.fix_complexity === 'low') score += weights.complexity;\n\n if (score >= 70) return 'critical';\n if (score >= 50) return 'high';\n if (score >= 30) return 'medium';\n return 'low';\n}\n```\n\n---\n\n## Fix Mapping\n\n| Problem | Strategies (priority order) |\n|---------|---------------------------|\n| Authoring Violation | eliminate_intermediate_files, minimize_state, context_passing |\n| Context Explosion | sliding_window, path_reference, context_summarization |\n| Long-tail Forgetting | constraint_injection, state_constraints_field, checkpoint |\n| Data Flow Disruption | state_centralization, schema_enforcement, field_normalization |\n| Agent Coordination | error_wrapping, result_validation, flatten_nesting |\n| Token Consumption | prompt_compression, lazy_loading, output_minimization, state_field_reduction |\n| Doc Redundancy | consolidate_to_ssot, centralize_mapping_config |\n| Doc Conflict | reconcile_conflicting_definitions |\n\n---\n\n## Cross-Category Dependencies\n\n```\nContext Explosion → Long-tail Forgetting\n (Large context pushes important info out)\n\nData Flow Disruption → Agent Coordination Failure\n (Inconsistent data causes agent failures)\n\nAgent Coordination Failure → Context Explosion\n (Failed retries add to context)\n```\n\n**Fix Order**: P1 Data Flow → P2 Agent → P3 Context → P4 Memory\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":7970,"content_sha256":"983d439a2ec2d365be938a2533dfab19f8e7d825a24c80d61136ddd32d637366"},{"filename":"specs/quality-gates.md","content":"# Quality Gates\n\nQuality thresholds and verification criteria for skill tuning.\n\n## When to Use\n\n| Phase | Usage | Section |\n|-------|-------|---------|\n| action-generate-report | Calculate quality score | Scoring |\n| action-verify | Check quality gates | Gate Definitions |\n| action-complete | Final assessment | Pass Criteria |\n\n---\n\n## Quality Dimensions\n\n### 1. Issue Severity Distribution (40%)\n\nMeasures the severity profile of identified issues.\n\n| Metric | Weight | Calculation |\n|--------|--------|-------------|\n| Critical Issues | -25 each | High penalty |\n| High Issues | -15 each | Significant penalty |\n| Medium Issues | -5 each | Moderate penalty |\n| Low Issues | -1 each | Minor penalty |\n\n**Score Calculation**:\n```javascript\nfunction calculateSeverityScore(issues) {\n const weights = { critical: 25, high: 15, medium: 5, low: 1 };\n const deductions = issues.reduce((sum, issue) =>\n sum + (weights[issue.severity] || 0), 0);\n return Math.max(0, 100 - deductions);\n}\n```\n\n### 2. Fix Effectiveness (30%)\n\nMeasures success rate of applied fixes.\n\n| Metric | Weight | Threshold |\n|--------|--------|-----------|\n| Fixes Verified Pass | +30 | > 80% pass rate |\n| Fixes Verified Fail | -20 | \u003c 50% triggers review |\n| Issues Resolved | +10 | Per resolved issue |\n\n**Score Calculation**:\n```javascript\nfunction calculateFixScore(appliedFixes) {\n const total = appliedFixes.length;\n if (total === 0) return 100; // No fixes needed = good\n\n const passed = appliedFixes.filter(f => f.verification_result === 'pass').length;\n return Math.round((passed / total) * 100);\n}\n```\n\n### 3. Coverage Completeness (20%)\n\nMeasures diagnosis coverage across all areas.\n\n| Metric | Weight | Threshold |\n|--------|--------|-----------|\n| All 4 diagnosis complete | +20 | Full coverage |\n| 3 diagnosis complete | +15 | Good coverage |\n| 2 diagnosis complete | +10 | Partial coverage |\n| \u003c 2 diagnosis complete | +0 | Insufficient |\n\n### 4. Iteration Efficiency (10%)\n\nMeasures how quickly issues are resolved.\n\n| Metric | Weight | Threshold |\n|--------|--------|-----------|\n| Resolved in 1 iteration | +10 | Excellent |\n| Resolved in 2 iterations | +7 | Good |\n| Resolved in 3 iterations | +4 | Acceptable |\n| > 3 iterations | +0 | Needs improvement |\n\n---\n\n## Gate Definitions\n\n### Gate: PASS\n\n**Threshold**: Quality Score >= 80 AND Critical Issues = 0 AND High Issues \u003c= 2\n\n**Meaning**: Skill is production-ready with minor issues.\n\n**Actions**:\n- Complete tuning session\n- Generate summary report\n- No further fixes required\n\n### Gate: REVIEW\n\n**Threshold**: Quality Score 60-79 OR High Issues 3-5\n\n**Meaning**: Skill has issues requiring attention.\n\n**Actions**:\n- Review remaining issues\n- Apply additional fixes if possible\n- May require manual intervention\n\n### Gate: FAIL\n\n**Threshold**: Quality Score \u003c 60 OR Critical Issues > 0 OR High Issues > 5\n\n**Meaning**: Skill has serious issues blocking deployment.\n\n**Actions**:\n- Must fix critical issues\n- Re-run diagnosis after fixes\n- Consider architectural review\n\n---\n\n## Quality Score Calculation\n\n```javascript\nfunction calculateQualityScore(state) {\n // Dimension 1: Severity (40%)\n const severityScore = calculateSeverityScore(state.issues);\n\n // Dimension 2: Fix Effectiveness (30%)\n const fixScore = calculateFixScore(state.applied_fixes);\n\n // Dimension 3: Coverage (20%)\n const diagnosisCount = Object.values(state.diagnosis)\n .filter(d => d !== null).length;\n const coverageScore = [0, 0, 10, 15, 20][diagnosisCount] || 0;\n\n // Dimension 4: Efficiency (10%)\n const efficiencyScore = state.iteration_count \u003c= 1 ? 10 :\n state.iteration_count \u003c= 2 ? 7 :\n state.iteration_count \u003c= 3 ? 4 : 0;\n\n // Weighted total\n const total = (severityScore * 0.4) +\n (fixScore * 0.3) +\n (coverageScore * 1.0) + // Already scaled to 20\n (efficiencyScore * 1.0); // Already scaled to 10\n\n return Math.round(total);\n}\n\nfunction determineQualityGate(state) {\n const score = calculateQualityScore(state);\n const criticalCount = state.issues.filter(i => i.severity === 'critical').length;\n const highCount = state.issues.filter(i => i.severity === 'high').length;\n\n if (criticalCount > 0) return 'fail';\n if (highCount > 5) return 'fail';\n if (score \u003c 60) return 'fail';\n\n if (highCount > 2) return 'review';\n if (score \u003c 80) return 'review';\n\n return 'pass';\n}\n```\n\n---\n\n## Verification Criteria\n\n### For Each Issue Type\n\n#### Context Explosion Issues\n- [ ] Token count does not grow unbounded\n- [ ] History limited to reasonable size\n- [ ] No full content in prompts (paths used instead)\n- [ ] Agent returns are compact\n\n#### Long-tail Forgetting Issues\n- [ ] Constraints visible in all phase prompts\n- [ ] State schema includes requirements field\n- [ ] Checkpoints exist at key milestones\n- [ ] Output matches original constraints\n\n#### Data Flow Issues\n- [ ] Single state.json after execution\n- [ ] No orphan state files\n- [ ] Schema validation active\n- [ ] Consistent field naming\n\n#### Agent Coordination Issues\n- [ ] All Task calls have error handling\n- [ ] Agent results validated before use\n- [ ] No nested agent calls\n- [ ] Tool declarations match usage\n\n---\n\n## Iteration Control\n\n### Max Iterations\n\nDefault: 5 iterations\n\n**Rationale**:\n- Each iteration may introduce new issues\n- Diminishing returns after 3-4 iterations\n- Prevents infinite loops\n\n### Iteration Exit Criteria\n\n```javascript\nfunction shouldContinueIteration(state) {\n // Exit if quality gate passed\n if (state.quality_gate === 'pass') return false;\n\n // Exit if max iterations reached\n if (state.iteration_count >= state.max_iterations) return false;\n\n // Exit if no improvement in last 2 iterations\n if (state.iteration_count >= 2) {\n const recentHistory = state.action_history.slice(-10);\n const issuesResolvedRecently = recentHistory.filter(a =>\n a.action === 'action-verify' && a.result === 'success'\n ).length;\n\n if (issuesResolvedRecently === 0) {\n console.log('No progress in recent iterations, stopping.');\n return false;\n }\n }\n\n // Continue if critical/high issues remain\n const hasUrgentIssues = state.issues.some(i =>\n i.severity === 'critical' || i.severity === 'high'\n );\n\n return hasUrgentIssues;\n}\n```\n\n---\n\n## Reporting Format\n\n### Quality Summary Table\n\n| Dimension | Score | Weight | Weighted |\n|-----------|-------|--------|----------|\n| Severity Distribution | {score}/100 | 40% | {weighted} |\n| Fix Effectiveness | {score}/100 | 30% | {weighted} |\n| Coverage Completeness | {score}/20 | 20% | {score} |\n| Iteration Efficiency | {score}/10 | 10% | {score} |\n| **Total** | | | **{total}/100** |\n\n### Gate Status\n\n```\nQuality Gate: {PASS|REVIEW|FAIL}\n\nCriteria:\n- Quality Score: {score} (threshold: 60)\n- Critical Issues: {count} (threshold: 0)\n- High Issues: {count} (threshold: 5)\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":6896,"content_sha256":"981a1794523a6be3e6cf70ac6c8a9849b62627c6259f8d01255c88268e3e7880"},{"filename":"specs/skill-authoring-principles.md","content":"# Skill Authoring Principles\n\nSkill 撰写首要准则。所有诊断和优化以此为纲。\n\n---\n\n## 核心原则\n\n```\n简洁高效 → 去除无关存储 → 去除中间存储 → 上下文流转\n```\n\n---\n\n## 1. 简洁高效\n\n**原则**：最小化实现，只做必要的事\n\n| DO | DON'T |\n|----|-------|\n| 单一职责阶段 | 臃肿的多功能阶段 |\n| 直接的数据路径 | 迂回的处理流程 |\n| 必要的字段 | 冗余的 schema 定义 |\n| 精准的 prompt | 过度详细的指令 |\n\n**检测模式**：\n- Phase 文件 > 200 行 → 需拆分\n- State schema 字段 > 20 个 → 需精简\n- 同一数据多处定义 → 需去重\n\n---\n\n## 2. 去除无关存储\n\n**原则**：不存储不需要的数据\n\n| DO | DON'T |\n|----|-------|\n| 只存最终结果 | 存储调试信息 |\n| 存路径引用 | 存完整内容副本 |\n| 存必要索引 | 存全量历史 |\n\n**检测模式**：\n```javascript\n// BAD: 存储完整内容\nstate.full_analysis_result = longAnalysisOutput;\n\n// GOOD: 存路径 + 摘要\nstate.analysis = {\n path: `${workDir}/analysis.json`,\n summary: extractSummary(output),\n key_findings: extractFindings(output)\n};\n```\n\n**反模式清单**：\n- `state.debug_*` → 删除\n- `state.*_history` (无限增长) → 限制或删除\n- `state.*_cache` (会话内) → 改用内存变量\n- 重复字段 → 合并\n\n---\n\n## 3. 去除中间存储\n\n**原则**：避免临时文件和中间状态文件\n\n| DO | DON'T |\n|----|-------|\n| 直接传递结果 | 写文件再读文件 |\n| 函数返回值 | 中间 JSON 文件 |\n| 管道处理 | 阶段性存储 |\n\n**检测模式**：\n```javascript\n// BAD: 中间文件\nWrite(`${workDir}/temp-step1.json`, step1Result);\nconst step1 = Read(`${workDir}/temp-step1.json`);\nconst step2Result = process(step1);\nWrite(`${workDir}/temp-step2.json`, step2Result);\n\n// GOOD: 直接流转\nconst step1Result = await executeStep1();\nconst step2Result = process(step1Result);\nconst finalResult = finalize(step2Result);\nWrite(`${workDir}/final-output.json`, finalResult); // 只存最终结果\n```\n\n**允许的存储**：\n- 最终输出（用户需要的结果）\n- 检查点（长流程恢复用，可选）\n- 备份（修改前的原始文件）\n\n**禁止的存储**：\n- `temp-*.json`\n- `intermediate-*.json`\n- `step[N]-output.json`\n- `*-draft.md`\n\n---\n\n## 4. 上下文流转\n\n**原则**：通过上下文传递而非文件\n\n| DO | DON'T |\n|----|-------|\n| 函数参数传递 | 全局状态读写 |\n| 返回值链式处理 | 文件中转 |\n| prompt 内嵌数据 | 指向外部文件 |\n\n**模式**：\n```javascript\n// 上下文流转模式\nasync function executePhase(context) {\n const { previousResult, constraints, config } = context;\n\n const result = await Agent({\n subagent_type: 'universal-executor',\n description: 'Execute phase with context passing',\n run_in_background: false,\n prompt: `\n [CONTEXT]\n Previous: ${JSON.stringify(previousResult)}\n Constraints: ${constraints.join(', ')}\n\n [TASK]\n Process and return result directly.\n `\n });\n\n return {\n ...context,\n currentResult: result,\n completed: ['phase-name']\n };\n}\n\n// 链式执行\nlet ctx = initialContext;\nctx = await executePhase1(ctx);\nctx = await executePhase2(ctx);\nctx = await executePhase3(ctx);\n// ctx 包含完整上下文，无中间文件\n```\n\n**State 最小化**：\n```typescript\n// 只存必要状态\ninterface MinimalState {\n status: 'pending' | 'running' | 'completed';\n target: { name: string; path: string };\n result_path: string; // 最终结果路径\n error?: string;\n}\n```\n\n---\n\n## 应用场景\n\n### 诊断时检查\n\n| 检查项 | 违反时标记 |\n|--------|-----------|\n| Phase 内写入 temp 文件 | `unnecessary_storage` |\n| State 包含 *_history 无限数组 | `unbounded_state` |\n| 文件写入后立即读取 | `redundant_io` |\n| 多阶段传递完整内容 | `context_bloat` |\n\n### 优化策略\n\n| 问题 | 策略 |\n|------|------|\n| 中间文件过多 | `eliminate_intermediate_files` |\n| State 膨胀 | `minimize_state_schema` |\n| 重复存储 | `deduplicate_storage` |\n| 文件中转 | `context_passing` |\n\n---\n\n## 合规检查清单\n\n```\n□ 无 temp/intermediate 文件写入\n□ State schema \u003c 15 个字段\n□ 无重复数据存储\n□ Phase 间通过上下文/返回值传递\n□ 只存最终结果文件\n□ 无无限增长的数组\n□ 无调试字段残留\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4380,"content_sha256":"6d0aa9476d279fb032f0a2a2370323c3923062b13daf9c50b9e063140d735e96"},{"filename":"specs/tuning-strategies.md","content":"# Tuning Strategies\n\nFix strategies for each problem category. Implementation patterns + verification methods.\n\n## Usage Context\n\n| Phase | Usage |\n|-------|-------|\n| action-propose-fixes | Strategy selection + implementation guidance |\n| action-apply-fix | Apply implementation pattern |\n| action-verify | Run verification method |\n\n---\n\n## Selection Decision Tree\n\n```\nContext Explosion?\n├── history grows unbounded? → sliding_window\n├── full content in prompts? → path_reference\n├── no summarization? → context_summarization\n└── text-based context? → structured_state\n\nLong-tail Forgetting?\n├── constraints not in phases? → constraint_injection\n├── no requirements in state? → state_constraints_field\n├── no recovery points? → checkpoint_restore\n└── goal drift risk? → goal_embedding\n\nData Flow?\n├── multiple state files? → state_centralization\n├── no validation? → schema_enforcement\n└── inconsistent names? → field_normalization\n\nAgent Coordination?\n├── no error handling? → error_wrapping\n├── no result validation? → result_validation\n└── nested agent calls? → flatten_nesting\n\nAuthoring Violation?\n├── intermediate files? → eliminate_intermediate_files\n├── state bloat (>15 fields)? → minimize_state\n├── write→read relay? → context_passing\n└── duplicate storage? → deduplicate_storage\n\nToken Consumption?\n├── verbose prompts? → prompt_compression\n├── full content passing? → lazy_loading\n├── verbose output? → output_minimization\n├── bloated state? → state_field_reduction\n└── multiple output files? → in_memory_consolidation\n\nDocumentation?\n├── repeated definitions? → consolidate_to_ssot\n├── hardcoded configs? → centralize_mapping_config\n└── conflicting values? → reconcile_conflicting_definitions\n```\n\n---\n\n## Authoring Principles Strategies (P0)\n\n> **Core Principle**: Simplicity → Remove intermediate files → Context passing\n\n### eliminate_intermediate_files\n\n```javascript\n// Before: File relay between steps\nconst step1 = await analyze();\nWrite(`${workDir}/step1.json`, JSON.stringify(step1));\nconst step1Data = JSON.parse(Read(`${workDir}/step1.json`));\nconst step2 = await transform(step1Data);\n\n// After: Direct context passing\nconst step1 = await analyze();\nconst step2 = await transform(step1); // No file\nreturn finalize(step2); // Only final result persisted\n```\n\n**Verification**: `ls ${workDir}` — no temp/intermediate files\n\n### minimize_state\n\n**Rules**: ≤15 fields, delete `debug_*`, `*_cache`, `*_temp`, apply sliding window to `*_history`.\n\n```typescript\n// Before: Bloated\ninterface State { status; target; user_input; parsed_input; intermediate_result; debug_info; analysis_cache; full_history; step1_output; step2_output; final_result; ... }\n\n// After: Minimal\ninterface State {\n status: 'pending'|'running'|'completed'|'failed';\n target: { name: string; path: string };\n result_path: string;\n error?: string;\n}\n```\n\n### context_passing\n\n```javascript\nasync function executeWorkflow(initialContext) {\n let ctx = initialContext;\n ctx = await executePhase1(ctx); // Pass context directly\n ctx = await executePhase2(ctx); // Continue passing\n const result = await executePhase3(ctx);\n Write(`${ctx.workDir}/result.json`, JSON.stringify(result)); // Only final\n return result;\n}\n```\n\n### deduplicate_storage\n\n```javascript\n// Before: state.user_request = state.original_request = state.input_text = input\n// After: state.input = input; // Single source\n```\n\n---\n\n## Context Explosion Strategies\n\n### sliding_window\n\n```javascript\nconst MAX_HISTORY = 5;\nfunction updateHistory(state, newItem) {\n return { ...state, history: [...(state.history || []), newItem].slice(-MAX_HISTORY) };\n}\n```\n\n### path_reference\n\n```javascript\n// Before: const prompt = `Analyze: ${Read('data.json')}`;\n// After: const prompt = `Analyze file at: ${dataPath}. Read it first.`;\n```\n\n### context_summarization\n\n```javascript\n// Add summarization before passing to next phase\nconst summary = await Agent({\n subagent_type: 'universal-executor',\n description: 'Summarize content for context compression',\n run_in_background: false,\n prompt: `Summarize in \u003c100 words: ${fullContent}\\nReturn JSON: { summary, key_points[] }`\n});\nnextPhasePrompt = `Previous summary: ${summary.summary}`;\n```\n\n---\n\n## Long-tail Forgetting Strategies\n\n### constraint_injection\n\n```javascript\n// Add to EVERY phase prompt\nconst phasePrompt = `\n[CONSTRAINTS - FROM ORIGINAL REQUEST]\n${state.original_requirements.map(r => `- ${r}`).join('\\n')}\n\n[CURRENT TASK]\n${taskDescription}\n\n[REMINDER] Output MUST satisfy all constraints above.\n`;\n```\n\n### state_constraints_field\n\nAdd to state-schema + action-init:\n```javascript\nstate.original_requirements = extractRequirements(userInput);\nstate.goal_summary = summarizeGoal(userInput);\n```\n\n### checkpoint_restore\n\n```javascript\nfunction createCheckpoint(state, workDir, name) {\n Write(`${workDir}/checkpoints/${name}.json`, JSON.stringify({\n state, timestamp: new Date().toISOString(), name\n }));\n}\n// Use at key phase boundaries\n```\n\n---\n\n## Data Flow Strategies\n\n### state_centralization\n\n```javascript\n// Single state manager — replace all direct writes\nconst StateManager = {\n read: (dir) => JSON.parse(Read(`${dir}/state.json`)),\n update: (dir, updates) => {\n const next = { ...StateManager.read(dir), ...updates, updated_at: Date.now() };\n Write(`${dir}/state.json`, JSON.stringify(next, null, 2));\n return next;\n }\n};\n```\n\n### schema_enforcement\n\n```javascript\nfunction validateState(state) {\n const errors = [];\n if (!['pending','running','completed','failed'].includes(state.status))\n errors.push(`Invalid status: ${state.status}`);\n if (typeof state.target_skill?.name !== 'string')\n errors.push('target_skill.name must be string');\n if (errors.length) throw new Error(`Validation failed:\\n${errors.join('\\n')}`);\n}\n// Call before every state write\n```\n\n### field_normalization\n\n```javascript\nconst NORMALIZATIONS = { 'title': 'name', 'identifier': 'id', 'state': 'status' };\nfunction normalizeData(data) {\n if (typeof data !== 'object' || !data) return data;\n return Object.fromEntries(\n Object.entries(data).map(([k, v]) => [NORMALIZATIONS[k] || k, normalizeData(v)])\n );\n}\n```\n\n---\n\n## Agent Coordination Strategies\n\n### error_wrapping\n\n```javascript\nasync function safeTask(config, state, updateState) {\n for (let attempt = 1; attempt \u003c= 3; attempt++) {\n try {\n const result = await Task(config);\n if (!result) throw new Error('Empty result');\n return result;\n } catch (error) {\n if (attempt === 3) {\n updateState({ error_count: state.error_count + 1 });\n throw error;\n }\n await new Promise(r => setTimeout(r, 1000 * attempt));\n }\n }\n}\n```\n\n### result_validation\n\n```javascript\nfunction validateAgentResult(result, requiredFields) {\n const parsed = typeof result === 'string' ? JSON.parse(result) : result;\n for (const field of requiredFields) {\n if (!(field in parsed)) throw new Error(`Missing: ${field}`);\n }\n return parsed;\n}\n```\n\n### flatten_nesting\n\n```javascript\n// Before: Agent A's prompt tells it to call Agent({subagent_type: 'B'})\n// After: Agent A returns signal, orchestrator handles\n// Agent A: return { needs_agent_b: true, context: {...} }\n// Orchestrator:\nif (parsedA.needs_agent_b) {\n resultB = await Agent({\n subagent_type: 'B',\n description: 'Handle delegated task from Agent A',\n run_in_background: false,\n prompt: `Context: ${parsedA.context}`\n });\n}\n```\n\n---\n\n## Token Consumption Strategies\n\n### prompt_compression\n\n```javascript\n// Before: Long inline prompt with role, detailed instructions, full code\n// After: Key instructions only\nconst prompt = `Analyze ${codePath} for: patterns, security, performance.\nReturn JSON: { issues: [], severity: string }`;\n```\n\n### lazy_loading\n\n```javascript\n// Before: const prompt = `Analyze:\\n${Read(filePath)}`;\n// After: const prompt = `Analyze file at: ${filePath}\\n(Read if needed)\\nReturn: { summary, issues[] }`;\n```\n\n### output_minimization\n\n```javascript\nconst prompt = `\nAnalyze the code. Return ONLY this JSON:\n{ \"status\": \"pass|review|fail\", \"issues\": [{\"id\",\"severity\",\"file\",\"line\"}], \"summary\": \"one sentence\" }\nDo not include explanations.\n`;\n```\n\n### state_field_reduction\n\nAudit checklist:\n```javascript\nfunction auditStateFields(schema) {\n const candidates = Object.keys(schema).filter(k =>\n k.startsWith('debug_') || k.endsWith('_cache') ||\n k.endsWith('_temp') || k.includes('intermediate')\n );\n return { total: Object.keys(schema).length, removable: candidates };\n}\n```\n\n### in_memory_consolidation\n\n```javascript\n// Before: Multiple files — diagnosis-report.md, summary.json, tuning-report.md\n// After: Single state.json with final_report rendered on demand\nconst consolidated = { ...state, final_report: { summary, generated_at: Date.now() } };\nWrite(`${workDir}/state.json`, JSON.stringify(consolidated, null, 2));\n```\n\n---\n\n## Documentation Strategies\n\n### consolidate_to_ssot\n\n```javascript\n// 1. Identify canonical source (priority: specs/ > phases/ > SKILL.md)\n// 2. Ensure canonical has full definition\n// 3. Replace other locations with reference links\n// e.g., \"See [state-schema.md](phases/state-schema.md)\"\n```\n\n### centralize_mapping_config\n\n```javascript\n// 1. Extract hardcoded mappings → specs/category-mappings.json\n// 2. Runtime loads config: const map = JSON.parse(Read('specs/category-mappings.json'));\n// 3. Replace all inline definitions with config lookup\n```\n\n### reconcile_conflicting_definitions\n\n```javascript\n// 1. Present conflict to user via AskUserQuestion\n// 2. Apply chosen version across all files\n// 3. Verify no remaining conflicts\n```\n\n---\n\n## General Optimization Areas (via Gemini CLI)\n\nFor issues in these categories, use Gemini CLI for custom analysis:\n\n| Category | Issues | Gemini Analysis |\n|----------|--------|-----------------|\n| Prompt Engineering | Vague instructions, format drift | prompt optimization, structured output |\n| Architecture | Phase overlap, tight coupling | phase_decomposition, interface_contracts |\n| Performance | Slow execution, high tokens | token_budgeting, parallel_execution |\n| Error Handling | Silent failures, no degradation | graceful_degradation, error_propagation |\n| Output Quality | Inconsistent results | quality_gates, output_validation |\n| User Experience | No progress visibility | progress_tracking, interactive_checkpoints |\n\n**Gemini CLI Template**:\n```bash\nccw cli -p \"\nPURPOSE: [optimization goal for skill at ${skillPath}]\nTASK: • [specific analysis steps]\nMODE: analysis\nCONTEXT: @${skillPath}/**/*\nEXPECTED: [specific deliverable]\n\" --tool gemini --mode analysis\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":10869,"content_sha256":"e1e9e999bf2cd9034ac192a69936717863aefd5ebbc82b7f3c33d75ee8d89ca9"},{"filename":"templates/diagnosis-report.md","content":"# Diagnosis Report Template\n\nTemplate for individual diagnosis action reports.\n\n## Template\n\n```markdown\n# {{diagnosis_type}} Diagnosis Report\n\n**Target Skill**: {{skill_name}}\n**Diagnosis Type**: {{diagnosis_type}}\n**Executed At**: {{timestamp}}\n**Duration**: {{duration_ms}}ms\n\n---\n\n## Summary\n\n| Metric | Value |\n|--------|-------|\n| Issues Found | {{issues_found}} |\n| Severity | {{severity}} |\n| Patterns Checked | {{patterns_checked_count}} |\n| Patterns Matched | {{patterns_matched_count}} |\n\n---\n\n## Patterns Analyzed\n\n{{#each patterns_checked}}\n### {{pattern_name}}\n\n- **Status**: {{status}}\n- **Matches**: {{match_count}}\n- **Files Affected**: {{affected_files}}\n\n{{/each}}\n\n---\n\n## Issues Identified\n\n{{#if issues.length}}\n{{#each issues}}\n### {{id}}: {{description}}\n\n| Field | Value |\n|-------|-------|\n| Type | {{type}} |\n| Severity | {{severity}} |\n| Location | {{location}} |\n| Root Cause | {{root_cause}} |\n| Impact | {{impact}} |\n\n**Evidence**:\n{{#each evidence}}\n- `{{this}}`\n{{/each}}\n\n**Suggested Fix**: {{suggested_fix}}\n\n---\n{{/each}}\n{{else}}\n_No issues found in this diagnosis area._\n{{/if}}\n\n---\n\n## Recommendations\n\n{{#if recommendations.length}}\n{{#each recommendations}}\n{{@index}}. {{this}}\n{{/each}}\n{{else}}\nNo specific recommendations - area appears healthy.\n{{/if}}\n\n---\n\n## Raw Data\n\nFull diagnosis data available at:\n`{{output_file}}`\n```\n\n## Variable Reference\n\n| Variable | Type | Source |\n|----------|------|--------|\n| `diagnosis_type` | string | 'context' \\| 'memory' \\| 'dataflow' \\| 'agent' |\n| `skill_name` | string | state.target_skill.name |\n| `timestamp` | string | ISO timestamp |\n| `duration_ms` | number | Execution time |\n| `issues_found` | number | issues.length |\n| `severity` | string | Calculated severity |\n| `patterns_checked` | array | Patterns analyzed |\n| `patterns_matched` | array | Patterns with matches |\n| `issues` | array | Issue objects |\n| `recommendations` | array | String recommendations |\n| `output_file` | string | Path to JSON file |\n\n## Usage\n\n```javascript\nfunction renderDiagnosisReport(diagnosis, diagnosisType, skillName, outputFile) {\n return `# ${diagnosisType} Diagnosis Report\n\n**Target Skill**: ${skillName}\n**Diagnosis Type**: ${diagnosisType}\n**Executed At**: ${new Date().toISOString()}\n**Duration**: ${diagnosis.execution_time_ms}ms\n\n---\n\n## Summary\n\n| Metric | Value |\n|--------|-------|\n| Issues Found | ${diagnosis.issues_found} |\n| Severity | ${diagnosis.severity} |\n| Patterns Checked | ${diagnosis.details.patterns_checked.length} |\n| Patterns Matched | ${diagnosis.details.patterns_matched.length} |\n\n---\n\n## Issues Identified\n\n${diagnosis.details.evidence.map((e, i) => `\n### Issue ${i + 1}\n\n- **File**: ${e.file}\n- **Pattern**: ${e.pattern}\n- **Severity**: ${e.severity}\n- **Context**: \\`${e.context}\\`\n`).join('\\n')}\n\n---\n\n## Recommendations\n\n${diagnosis.details.recommendations.map((r, i) => `${i + 1}. ${r}`).join('\\n')}\n\n---\n\n## Raw Data\n\nFull diagnosis data available at:\n\\`${outputFile}\\`\n`;\n}\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":3002,"content_sha256":"0f1d0a062609a3d3e669e86bd7ae6d1d0bf404c664275dcbd191c764e55ef045"},{"filename":"templates/fix-proposal.md","content":"# Fix Proposal Template\n\nTemplate for fix proposal documentation.\n\n## Template\n\n```markdown\n# Fix Proposal: {{fix_id}}\n\n**Strategy**: {{strategy}}\n**Risk Level**: {{risk}}\n**Issues Addressed**: {{issue_ids}}\n\n---\n\n## Description\n\n{{description}}\n\n## Rationale\n\n{{rationale}}\n\n---\n\n## Affected Files\n\n{{#each changes}}\n### {{file}}\n\n**Action**: {{action}}\n\n```diff\n{{diff}}\n```\n\n{{/each}}\n\n---\n\n## Implementation Steps\n\n{{#each implementation_steps}}\n{{@index}}. {{this}}\n{{/each}}\n\n---\n\n## Risk Assessment\n\n| Factor | Assessment |\n|--------|------------|\n| Complexity | {{complexity}} |\n| Reversibility | {{reversible ? 'Yes' : 'No'}} |\n| Breaking Changes | {{breaking_changes}} |\n| Test Coverage | {{test_coverage}} |\n\n**Overall Risk**: {{risk}}\n\n---\n\n## Verification Steps\n\n{{#each verification_steps}}\n- [ ] {{this}}\n{{/each}}\n\n---\n\n## Rollback Plan\n\n{{#if rollback_available}}\nTo rollback this fix:\n\n```bash\n{{rollback_command}}\n```\n{{else}}\n_Rollback not available for this fix type._\n{{/if}}\n\n---\n\n## Estimated Impact\n\n{{estimated_impact}}\n```\n\n## Variable Reference\n\n| Variable | Type | Source |\n|----------|------|--------|\n| `fix_id` | string | Generated ID (FIX-001) |\n| `strategy` | string | Fix strategy name |\n| `risk` | string | 'low' \\| 'medium' \\| 'high' |\n| `issue_ids` | array | Related issue IDs |\n| `description` | string | Human-readable description |\n| `rationale` | string | Why this fix works |\n| `changes` | array | File change objects |\n| `implementation_steps` | array | Step-by-step guide |\n| `verification_steps` | array | How to verify fix worked |\n| `estimated_impact` | string | Expected improvement |\n\n## Usage\n\n```javascript\nfunction renderFixProposal(fix) {\n return `# Fix Proposal: ${fix.id}\n\n**Strategy**: ${fix.strategy}\n**Risk Level**: ${fix.risk}\n**Issues Addressed**: ${fix.issue_ids.join(', ')}\n\n---\n\n## Description\n\n${fix.description}\n\n## Rationale\n\n${fix.rationale}\n\n---\n\n## Affected Files\n\n${fix.changes.map(change => `\n### ${change.file}\n\n**Action**: ${change.action}\n\n\\`\\`\\`diff\n${change.diff || change.new_content?.slice(0, 200) || 'N/A'}\n\\`\\`\\`\n`).join('\\n')}\n\n---\n\n## Verification Steps\n\n${fix.verification_steps.map(step => `- [ ] ${step}`).join('\\n')}\n\n---\n\n## Estimated Impact\n\n${fix.estimated_impact}\n`;\n}\n```\n\n## Fix Strategy Templates\n\n### sliding_window\n\n```markdown\n## Description\nImplement sliding window for conversation history to prevent unbounded growth.\n\n## Changes\n- Add MAX_HISTORY constant\n- Modify history update logic to slice array\n- Update state schema documentation\n\n## Verification\n- [ ] Run skill for 10+ iterations\n- [ ] Verify history.length \u003c= MAX_HISTORY\n- [ ] Check no data loss for recent items\n```\n\n### constraint_injection\n\n```markdown\n## Description\nAdd explicit constraint section to each phase prompt.\n\n## Changes\n- Add [CONSTRAINTS] section template\n- Reference state.original_requirements\n- Add reminder before output section\n\n## Verification\n- [ ] Check constraints visible in all phases\n- [ ] Test with specific constraint\n- [ ] Verify output respects constraint\n```\n\n### error_wrapping\n\n```markdown\n## Description\nWrap all Task calls in try-catch with retry logic.\n\n## Changes\n- Create safeTask wrapper function\n- Replace direct Task calls\n- Add error logging to state\n\n## Verification\n- [ ] Simulate agent failure\n- [ ] Verify graceful error handling\n- [ ] Check retry logic\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":3371,"content_sha256":"6f5357310be0cf948b8a47a8eb5280637f5ac02105000d9b60817914fa5db246"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Skill Tuning","type":"text"}]},{"type":"paragraph","content":[{"text":"Autonomous diagnosis and optimization for skill execution issues.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Architecture","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"┌─────────────────────────────────────────────────────┐\n│ Phase 0: Read Specs (mandatory) │\n│ → problem-taxonomy.md, tuning-strategies.md │\n└─────────────────────────────────────────────────────┘\n ↓\n┌─────────────────────────────────────────────────────┐\n│ Orchestrator (state-driven) │\n│ Read state → Select action → Execute → Update → ✓ │\n└─────────────────────────────────────────────────────┘\n ↓ ↓\n┌──────────────────────┐ ┌──────────────────┐\n│ Diagnosis Phase │ │ Gemini CLI │\n│ • Context │ │ Deep analysis │\n│ • Memory │ │ (on-demand) │\n│ • DataFlow │ │ │\n│ • Agent │ │ Complex issues │\n│ • Docs │ │ Architecture │\n│ • Token Usage │ │ Performance │\n└──────────────────────┘ └──────────────────┘\n ↓\n ┌───────────────────┐\n │ Fix & Verify │\n │ Apply → Re-test │\n └───────────────────┘","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Core Issues Detected","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Priority","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Problem","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Root Cause","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Fix Strategy","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"P0","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Authoring Violation","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Intermediate files, state bloat, file relay","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"eliminate_intermediate, minimize_state","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"P1","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Data Flow Disruption","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Scattered state, inconsistent formats","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"state_centralization, schema_enforcement","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"P2","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Agent Coordination","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Fragile chains, no error handling","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"error_wrapping, result_validation","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"P3","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Context Explosion","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Unbounded history, full content passing","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"sliding_window, path_reference","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"P4","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Long-tail Forgetting","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Early constraint loss","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"constraint_injection, checkpoint_restore","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"P5","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Token Consumption","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Verbose prompts, state bloat","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"prompt_compression, lazy_loading","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Problem Categories (Detailed Specs)","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"specs/problem-taxonomy.md","type":"text","marks":[{"type":"link","attrs":{"href":"specs/problem-taxonomy.md","title":null}}]},{"text":" for:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Detection patterns (regex/checks)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Severity calculations","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Impact assessments","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Tuning Strategies (Detailed Specs)","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"specs/tuning-strategies.md","type":"text","marks":[{"type":"link","attrs":{"href":"specs/tuning-strategies.md","title":null}}]},{"text":" for:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"10+ strategies per category","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Implementation patterns","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verification methods","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Workflow","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Step","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Action","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Orchestrator Decision","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Output","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"1","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"action-init","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"status='pending'","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Backup, session created","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"2","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"action-analyze-requirements","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"After init","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Required dimensions + coverage","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"3","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Diagnosis (6 types)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Focus areas","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"state.diagnosis.{type}","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"4","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"action-gemini-analysis","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Critical issues OR user request","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Deep findings","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"5","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"action-generate-report","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"All diagnosis complete","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"state.final_report","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"6","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"action-propose-fixes","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Issues found","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"state.proposed_fixes[]","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"7","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"action-apply-fix","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Pending fixes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Applied + verified","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"8","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"action-complete","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Quality gates pass","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"session.status='completed'","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Action Reference","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Category","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Actions","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Purpose","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Setup","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"action-init","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Initialize backup, session state","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Analysis","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"action-analyze-requirements","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Decompose user request via Gemini CLI","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Diagnosis","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"action-diagnose-{context,memory,dataflow,agent,docs,token_consumption}","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Detect category-specific issues","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Deep Analysis","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"action-gemini-analysis","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Gemini CLI: complex/critical issues","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Reporting","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"action-generate-report","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Consolidate findings → final_report","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Fixing","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"action-propose-fixes, action-apply-fix","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Generate + apply fixes","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Verify","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"action-verify","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Re-run diagnosis, check gates","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Exit","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"action-complete, action-abort","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Finalize or rollback","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Full action details: ","type":"text"},{"text":"phases/actions/","type":"text","marks":[{"type":"link","attrs":{"href":"phases/actions/","title":null}}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"State Management","type":"text"}]},{"type":"paragraph","content":[{"text":"Single source of truth","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":".workflow/.scratchpad/skill-tuning-{ts}/state.json","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"status\": \"pending|running|completed|failed\",\n \"target_skill\": { \"name\": \"...\", \"path\": \"...\" },\n \"diagnosis\": {\n \"context\": {...},\n \"memory\": {...},\n \"dataflow\": {...},\n \"agent\": {...},\n \"docs\": {...},\n \"token_consumption\": {...}\n },\n \"issues\": [{\"id\":\"...\", \"severity\":\"...\", \"category\":\"...\", \"strategy\":\"...\"}],\n \"proposed_fixes\": [...],\n \"applied_fixes\": [...],\n \"quality_gate\": \"pass|fail\",\n \"final_report\": \"...\"\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"phases/state-schema.md","type":"text","marks":[{"type":"link","attrs":{"href":"phases/state-schema.md","title":null}}]},{"text":" for complete schema.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Orchestrator Logic","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"phases/orchestrator.md","type":"text","marks":[{"type":"link","attrs":{"href":"phases/orchestrator.md","title":null}}]},{"text":" for:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Decision logic (termination checks → action selection)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"State transitions","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Error recovery","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Key Principles","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Problem-First","type":"text","marks":[{"type":"strong"}]},{"text":": Diagnosis before any fix","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Data-Driven","type":"text","marks":[{"type":"strong"}]},{"text":": Record traces, token counts, snapshots","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Iterative","type":"text","marks":[{"type":"strong"}]},{"text":": Multiple rounds until quality gates pass","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reversible","type":"text","marks":[{"type":"strong"}]},{"text":": All changes with backup checkpoints","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Non-Invasive","type":"text","marks":[{"type":"strong"}]},{"text":": Minimal changes, maximum clarity","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Usage Examples","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Basic skill diagnosis\n/skill-tuning \"Fix memory leaks in my skill\"\n\n# Deep analysis with Gemini\n/skill-tuning \"Architecture issues in async workflow\"\n\n# Focus on specific areas\n/skill-tuning \"Optimize token consumption and fix agent coordination\"\n\n# Custom issue\n/skill-tuning \"My skill produces inconsistent outputs\"","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Output","type":"text"}]},{"type":"paragraph","content":[{"text":"After completion, review:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":".workflow/.scratchpad/skill-tuning-{ts}/state.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Full state with final_report","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"state.final_report","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Markdown summary (in state.json)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"state.applied_fixes","type":"text","marks":[{"type":"code_inline"}]},{"text":" - List of applied fixes with verification results","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Reference Documents","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Document","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Purpose","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"specs/problem-taxonomy.md","type":"text","marks":[{"type":"link","attrs":{"href":"specs/problem-taxonomy.md","title":null}}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Classification + detection patterns","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"specs/tuning-strategies.md","type":"text","marks":[{"type":"link","attrs":{"href":"specs/tuning-strategies.md","title":null}}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Fix implementation guide","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"specs/dimension-mapping.md","type":"text","marks":[{"type":"link","attrs":{"href":"specs/dimension-mapping.md","title":null}}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Dimension ↔ Spec mapping","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"specs/quality-gates.md","type":"text","marks":[{"type":"link","attrs":{"href":"specs/quality-gates.md","title":null}}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Quality verification criteria","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"phases/orchestrator.md","type":"text","marks":[{"type":"link","attrs":{"href":"phases/orchestrator.md","title":null}}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Workflow orchestration","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"phases/state-schema.md","type":"text","marks":[{"type":"link","attrs":{"href":"phases/state-schema.md","title":null}}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"State structure definition","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"phases/actions/","type":"text","marks":[{"type":"link","attrs":{"href":"phases/actions/","title":null}}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Individual action implementations","type":"text"}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"skill-tuning","author":"@skillopedia","source":{"stars":2066,"repo_name":"claude-code-workflow","origin_url":"https://github.com/catlog22/claude-code-workflow/blob/HEAD/.claude/skills/skill-tuning/SKILL.md","repo_owner":"catlog22","body_sha256":"5316dec5f908f1bf4372519296210903e5922bc36cda424b2c02ac9f85aad145","cluster_key":"c4b66490354e06db38dfb0c26e3d5e2b686956bd0d5736cd4f7680bf47e79b05","clean_bundle":{"format":"clean-skill-bundle-v1","source":"catlog22/claude-code-workflow/.claude/skills/skill-tuning/SKILL.md","attachments":[{"id":"3a2628d5-284a-58df-8663-401a4cc06777","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/3a2628d5-284a-58df-8663-401a4cc06777/attachment.md","path":"phases/actions/action-abort.md","size":4159,"sha256":"647ec233e57bfa9831d397402d625f9e11733a9f34f4e7225a0d16478f1ca065","contentType":"text/markdown; charset=utf-8"},{"id":"9d8be5ae-16bc-5403-a7fe-3e15123c3673","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/9d8be5ae-16bc-5403-a7fe-3e15123c3673/attachment.md","path":"phases/actions/action-analyze-requirements.md","size":11630,"sha256":"1086d46dfd1d9ec7f02849e7d484b73b0c21405455868455cec39510e719ca21","contentType":"text/markdown; charset=utf-8"},{"id":"9b427aad-7cc9-5212-b390-b8b55b52dbc7","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/9b427aad-7cc9-5212-b390-b8b55b52dbc7/attachment.md","path":"phases/actions/action-apply-fix.md","size":5756,"sha256":"727eb108db853ca9129f2fb057616b89486a4619e5ee3e673dabfa4d23a76450","contentType":"text/markdown; charset=utf-8"},{"id":"aefe317b-748a-5a27-98db-2ef795f13d84","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/aefe317b-748a-5a27-98db-2ef795f13d84/attachment.md","path":"phases/actions/action-complete.md","size":5438,"sha256":"dfb710b1fe7644154101f4940043771b31b7fd32b5a89c8c2d8d223bfc2ac8eb","contentType":"text/markdown; charset=utf-8"},{"id":"f637037d-a5f0-5c50-8c4d-2cbb3c6c032a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/f637037d-a5f0-5c50-8c4d-2cbb3c6c032a/attachment.md","path":"phases/actions/action-diagnose-agent.md","size":10278,"sha256":"438302396cce0b90c333b32654da584331a92b9fb677670365cd3ecbd8c2efca","contentType":"text/markdown; charset=utf-8"},{"id":"10eb78ff-72a3-59ab-ad38-7b6ff4e0db26","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/10eb78ff-72a3-59ab-ad38-7b6ff4e0db26/attachment.md","path":"phases/actions/action-diagnose-context.md","size":7543,"sha256":"6b3a03dd139445545aa87560554fbbb5650bc8372c834b80c227ff9b456ec775","contentType":"text/markdown; charset=utf-8"},{"id":"8792aa49-5dac-5a7e-a4b0-23f154bef4d3","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/8792aa49-5dac-5a7e-a4b0-23f154bef4d3/attachment.md","path":"phases/actions/action-diagnose-dataflow.md","size":10163,"sha256":"27e4548112f4493bf7acf0a9716fe8d52c3bd57a0f6ddfc1bb5cf46831241280","contentType":"text/markdown; charset=utf-8"},{"id":"0ae0de4d-3f6c-59fc-b25c-fc4783d9a354","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/0ae0de4d-3f6c-59fc-b25c-fc4783d9a354/attachment.md","path":"phases/actions/action-diagnose-docs.md","size":8615,"sha256":"94ab546ab66a05ba9ed82ef21ee6991816cd5e6d10aa9511eba4980481e21af6","contentType":"text/markdown; charset=utf-8"},{"id":"3376b92d-cff3-5d39-93e9-a7729c6bcc18","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/3376b92d-cff3-5d39-93e9-a7729c6bcc18/attachment.md","path":"phases/actions/action-diagnose-memory.md","size":9343,"sha256":"c6e21970435d29e0f647db5e4fcd5c7c5bfe45396897b8924b25868f2749175b","contentType":"text/markdown; charset=utf-8"},{"id":"d375cdae-ff68-5835-a1ae-99ed38e1cabd","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d375cdae-ff68-5835-a1ae-99ed38e1cabd/attachment.md","path":"phases/actions/action-diagnose-token-consumption.md","size":6227,"sha256":"9fc12d27ee7b2a6ca9ac7037e2d3109b5f2cfd2abb6a0949b385fd8c33e00264","contentType":"text/markdown; charset=utf-8"},{"id":"f991d360-5cd5-5f20-9d50-739f7c527dbe","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/f991d360-5cd5-5f20-9d50-739f7c527dbe/attachment.md","path":"phases/actions/action-gemini-analysis.md","size":9234,"sha256":"8135a9c9ecf5f4feaab5d304b409ff1d0aaa603ad1f6679d5798e6bd77bd9fd1","contentType":"text/markdown; charset=utf-8"},{"id":"9e7ef007-97c7-55e4-ab8a-cd242cc0e30d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/9e7ef007-97c7-55e4-ab8a-cd242cc0e30d/attachment.md","path":"phases/actions/action-generate-report.md","size":7211,"sha256":"de09ff8e55a8beb81fdfaa803dcd1b657acc294dfc22170892517a48647dd44e","contentType":"text/markdown; charset=utf-8"},{"id":"ce398537-2844-5fb5-82f3-6a4f2d17b954","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/ce398537-2844-5fb5-82f3-6a4f2d17b954/attachment.md","path":"phases/actions/action-init.md","size":4609,"sha256":"f0e1e07af6f6cc8be6b7160f57bb1d2484c2306c82387913b204ac139dbce6e2","contentType":"text/markdown; charset=utf-8"},{"id":"d45ced94-810b-5660-b468-b3ceb0079c59","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d45ced94-810b-5660-b468-b3ceb0079c59/attachment.md","path":"phases/actions/action-propose-fixes.md","size":11036,"sha256":"4de77c4ca2ea8927d240d1be35a6dbbaa677be2c46f791a02ba9a8242d30ab25","contentType":"text/markdown; charset=utf-8"},{"id":"fae3bcab-51ab-5bc7-83b4-1c714728f27f","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/fae3bcab-51ab-5bc7-83b4-1c714728f27f/attachment.md","path":"phases/actions/action-verify.md","size":6887,"sha256":"c47a6e3deb86bc61db5e296938ca32950c7791029cf41685b7e1fbbd29760eb9","contentType":"text/markdown; charset=utf-8"},{"id":"e47c1399-35f9-59db-b086-2d1ab6427925","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/e47c1399-35f9-59db-b086-2d1ab6427925/attachment.md","path":"phases/orchestrator.md","size":5793,"sha256":"b850da7a5129eb75044250660a642981ccf45f9726a33ec629dd619683de8209","contentType":"text/markdown; charset=utf-8"},{"id":"5bc593ee-e588-5d47-93e5-1ad80f69123c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/5bc593ee-e588-5d47-93e5-1ad80f69123c/attachment.md","path":"phases/state-schema.md","size":11278,"sha256":"13ebd2e10e28ee3bb4fbe812e242be85aba5d3612163db2498258b655afac345","contentType":"text/markdown; charset=utf-8"},{"id":"af436a4b-a2cd-5b2f-b622-6f54c3d4b1ed","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/af436a4b-a2cd-5b2f-b622-6f54c3d4b1ed/attachment.json","path":"specs/category-mappings.json","size":11487,"sha256":"b281db49137420a97400a483a8d8ae7366a433c2d59b7768eef4830d7c633f63","contentType":"application/json; charset=utf-8"},{"id":"4342f6b9-cc13-59e4-89eb-573711a259af","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/4342f6b9-cc13-59e4-89eb-573711a259af/attachment.md","path":"specs/dimension-mapping.md","size":7964,"sha256":"799f9d72fbe0400754c475012cb9a514ad0ae88e282e9a861d7f8591d7d5efed","contentType":"text/markdown; charset=utf-8"},{"id":"687e7f9a-089d-5e0c-ad12-62dddf3315d7","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/687e7f9a-089d-5e0c-ad12-62dddf3315d7/attachment.md","path":"specs/problem-taxonomy.md","size":7970,"sha256":"983d439a2ec2d365be938a2533dfab19f8e7d825a24c80d61136ddd32d637366","contentType":"text/markdown; charset=utf-8"},{"id":"f2e05e99-a236-5782-9e52-e7c5d4cae13f","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/f2e05e99-a236-5782-9e52-e7c5d4cae13f/attachment.md","path":"specs/quality-gates.md","size":6896,"sha256":"981a1794523a6be3e6cf70ac6c8a9849b62627c6259f8d01255c88268e3e7880","contentType":"text/markdown; charset=utf-8"},{"id":"4b4048f7-c666-5dc7-95c7-41c7e55cf4dd","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/4b4048f7-c666-5dc7-95c7-41c7e55cf4dd/attachment.md","path":"specs/skill-authoring-principles.md","size":4380,"sha256":"6d0aa9476d279fb032f0a2a2370323c3923062b13daf9c50b9e063140d735e96","contentType":"text/markdown; charset=utf-8"},{"id":"a2325bfe-6ff1-51df-8efe-caa0717bac88","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a2325bfe-6ff1-51df-8efe-caa0717bac88/attachment.md","path":"specs/tuning-strategies.md","size":10869,"sha256":"e1e9e999bf2cd9034ac192a69936717863aefd5ebbc82b7f3c33d75ee8d89ca9","contentType":"text/markdown; charset=utf-8"},{"id":"d6856bc4-398c-5878-b6cf-8ea9569c5749","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d6856bc4-398c-5878-b6cf-8ea9569c5749/attachment.md","path":"templates/diagnosis-report.md","size":3002,"sha256":"0f1d0a062609a3d3e669e86bd7ae6d1d0bf404c664275dcbd191c764e55ef045","contentType":"text/markdown; charset=utf-8"},{"id":"446f4a14-8301-52db-a19c-a78051015f14","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/446f4a14-8301-52db-a19c-a78051015f14/attachment.md","path":"templates/fix-proposal.md","size":3371,"sha256":"6f5357310be0cf948b8a47a8eb5280637f5ac02105000d9b60817914fa5db246","contentType":"text/markdown; charset=utf-8"}],"bundle_sha256":"fdb74ef6727467845f97c311154c127aebf51746e3b3fb32cff8016de91877ae","attachment_count":25,"text_attachments":25,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":".claude/skills/skill-tuning/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"data-analytics","category_label":"Data"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"data-analytics","import_tag":"clean-skills-v1","description":"Universal skill diagnosis and optimization tool. Detect and fix skill execution issues including context explosion, long-tail forgetting, data flow disruption, and agent coordination failures. Supports Gemini CLI for deep analysis. Triggers on \"skill tuning\", \"tune skill\", \"skill diagnosis\", \"optimize skill\", \"skill debug\".","allowed-tools":"Agent, AskUserQuestion, Read, Write, Bash, Glob, Grep, mcp__ace-tool__search_context"}},"renderedAt":1782987330458}

Skill Tuning Autonomous diagnosis and optimization for skill execution issues. Architecture Core Issues Detected | Priority | Problem | Root Cause | Fix Strategy | |----------|---------|-----------|--------------| | P0 | Authoring Violation | Intermediate files, state bloat, file relay | eliminate intermediate, minimize state | | P1 | Data Flow Disruption | Scattered state, inconsistent formats | state centralization, schema enforcement | | P2 | Agent Coordination | Fragile chains, no error handling | error wrapping, result validation | | P3 | Context Explosion | Unbounded history, full conte…