claude-code-workflow 6.3.26 → 6.3.28

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

@@ -0,0 +1,222 @@
+# Action: Verify Applied Fixes
+
+Verify that applied fixes resolved the targeted issues.
+
+## Purpose
+
+- Re-run relevant diagnostics
+- Compare before/after issue counts
+- Update verification status
+- Determine if more iterations needed
+
+## Preconditions
+
+- [ ] state.status === 'running'
+- [ ] state.applied_fixes.length > 0
+- [ ] Some applied_fixes have verification_result === 'pending'
+
+## Execution
+
+```javascript
+async function execute(state, workDir) {
+  console.log('Verifying applied fixes...');
+
+  const appliedFixes = state.applied_fixes.filter(f => f.verification_result === 'pending');
+
+  if (appliedFixes.length === 0) {
+    return {
+      stateUpdates: {},
+      outputFiles: [],
+      summary: 'No fixes pending verification'
+    };
+  }
+
+  const verificationResults = [];
+
+  for (const fix of appliedFixes) {
+    const proposedFix = state.proposed_fixes.find(f => f.id === fix.fix_id);
+
+    if (!proposedFix) {
+      verificationResults.push({
+        fix_id: fix.fix_id,
+        result: 'fail',
+        reason: 'Fix definition not found'
+      });
+      continue;
+    }
+
+    // Determine which diagnosis to re-run based on fix strategy
+    const strategyToDiagnosis = {
+      'context_summarization': 'context',
+      'sliding_window': 'context',
+      'structured_state': 'context',
+      'path_reference': 'context',
+      'constraint_injection': 'memory',
+      'checkpoint_restore': 'memory',
+      'goal_embedding': 'memory',
+      'state_constraints_field': 'memory',
+      'state_centralization': 'dataflow',
+      'schema_enforcement': 'dataflow',
+      'field_normalization': 'dataflow',
+      'transactional_updates': 'dataflow',
+      'error_wrapping': 'agent',
+      'result_validation': 'agent',
+      'orchestrator_refactor': 'agent',
+      'flatten_nesting': 'agent'
+    };
+
+    const diagnosisType = strategyToDiagnosis[proposedFix.strategy];
+
+    // For now, do a lightweight verification
+    // Full implementation would re-run the specific diagnosis
+
+    // Check if the fix was actually applied (look for markers)
+    const targetPath = state.target_skill.path;
+    const fixMarker = `Applied fix ${fix.fix_id}`;
+
+    let fixFound = false;
+    const allFiles = Glob(`${targetPath}/**/*.md`);
+
+    for (const file of allFiles) {
+      const content = Read(file);
+      if (content.includes(fixMarker)) {
+        fixFound = true;
+        break;
+      }
+    }
+
+    if (fixFound) {
+      // Verify by checking if original issues still exist
+      const relatedIssues = proposedFix.issue_ids;
+      const originalIssueCount = relatedIssues.length;
+
+      // Simplified verification: assume fix worked if marker present
+      // Real implementation would re-run diagnosis patterns
+
+      verificationResults.push({
+        fix_id: fix.fix_id,
+        result: 'pass',
+        reason: `Fix applied successfully, addressing ${originalIssueCount} issues`,
+        issues_resolved: relatedIssues
+      });
+    } else {
+      verificationResults.push({
+        fix_id: fix.fix_id,
+        result: 'fail',
+        reason: 'Fix marker not found in target files'
+      });
+    }
+  }
+
+  // Update applied fixes with verification results
+  const updatedAppliedFixes = state.applied_fixes.map(fix => {
+    const result = verificationResults.find(v => v.fix_id === fix.fix_id);
+    if (result) {
+      return {
+        ...fix,
+        verification_result: result.result
+      };
+    }
+    return fix;
+  });
+
+  // Calculate new quality score
+  const passedFixes = verificationResults.filter(v => v.result === 'pass').length;
+  const totalFixes = verificationResults.length;
+  const verificationRate = totalFixes > 0 ? (passedFixes / totalFixes) * 100 : 100;
+
+  // Recalculate issues (remove resolved ones)
+  const resolvedIssueIds = verificationResults
+    .filter(v => v.result === 'pass')
+    .flatMap(v => v.issues_resolved || []);
+
+  const remainingIssues = state.issues.filter(i => !resolvedIssueIds.includes(i.id));
+
+  // Recalculate quality score
+  const weights = { critical: 25, high: 15, medium: 5, low: 1 };
+  const deductions = remainingIssues.reduce((sum, issue) =>
+    sum + (weights[issue.severity] || 0), 0);
+  const newHealthScore = Math.max(0, 100 - deductions);
+
+  // Determine new quality gate
+  const remainingCritical = remainingIssues.filter(i => i.severity === 'critical').length;
+  const remainingHigh = remainingIssues.filter(i => i.severity === 'high').length;
+  const newQualityGate = remainingCritical === 0 && remainingHigh <= 2 && newHealthScore >= 60
+    ? 'pass'
+    : newHealthScore >= 40 ? 'review' : 'fail';
+
+  // Increment iteration count
+  const newIterationCount = state.iteration_count + 1;
+
+  // Ask user if they want to continue
+  let continueIteration = false;
+  if (newQualityGate !== 'pass' && newIterationCount < state.max_iterations) {
+    const continueResponse = await AskUserQuestion({
+      questions: [{
+        question: `Verification complete. Quality gate: ${newQualityGate}. Continue with another iteration?`,
+        header: 'Continue',
+        multiSelect: false,
+        options: [
+          { label: 'Yes', description: `Run iteration ${newIterationCount + 1}` },
+          { label: 'No', description: 'Finish with current state' }
+        ]
+      }]
+    });
+    continueIteration = continueResponse['Continue'] === 'Yes';
+  }
+
+  // If continuing, reset diagnosis for re-evaluation
+  const diagnosisReset = continueIteration ? {
+    'diagnosis.context': null,
+    'diagnosis.memory': null,
+    'diagnosis.dataflow': null,
+    'diagnosis.agent': null
+  } : {};
+
+  return {
+    stateUpdates: {
+      applied_fixes: updatedAppliedFixes,
+      issues: remainingIssues,
+      quality_score: newHealthScore,
+      quality_gate: newQualityGate,
+      iteration_count: newIterationCount,
+      ...diagnosisReset,
+      issues_by_severity: {
+        critical: remainingIssues.filter(i => i.severity === 'critical').length,
+        high: remainingIssues.filter(i => i.severity === 'high').length,
+        medium: remainingIssues.filter(i => i.severity === 'medium').length,
+        low: remainingIssues.filter(i => i.severity === 'low').length
+      }
+    },
+    outputFiles: [],
+    summary: `Verified ${totalFixes} fixes: ${passedFixes} passed. Score: ${newHealthScore}, Gate: ${newQualityGate}, Iteration: ${newIterationCount}`
+  };
+}
+```
+
+## State Updates
+
+```javascript
+return {
+  stateUpdates: {
+    applied_fixes: [...updatedWithVerificationResults],
+    issues: [...remainingIssues],
+    quality_score: newScore,
+    quality_gate: newGate,
+    iteration_count: iteration + 1
+  }
+};
+```
+
+## Error Handling
+
+| Error Type | Recovery |
+|------------|----------|
+| Re-diagnosis fails | Mark as 'inconclusive' |
+| File access error | Skip file verification |
+
+## Next Actions
+
+- If quality_gate === 'pass': action-complete
+- If user chose to continue: restart diagnosis cycle
+- If max_iterations reached: action-complete

package/.claude/skills/skill-tuning/phases/orchestrator.md

@@ -0,0 +1,377 @@
+# Orchestrator
+
+Autonomous orchestrator for skill-tuning workflow. Reads current state and selects the next action based on diagnosis progress and quality gates.
+
+## Role
+
+Drive the tuning workflow by:
+1. Reading current session state
+2. Selecting the appropriate next action
+3. Executing the action via sub-agent
+4. Updating state with results
+5. Repeating until termination conditions met
+
+## State Management
+
+### Read State
+
+```javascript
+const state = JSON.parse(Read(`${workDir}/state.json`));
+```
+
+### Update State
+
+```javascript
+function updateState(updates) {
+  const state = JSON.parse(Read(`${workDir}/state.json`));
+  const newState = {
+    ...state,
+    ...updates,
+    updated_at: new Date().toISOString()
+  };
+  Write(`${workDir}/state.json`, JSON.stringify(newState, null, 2));
+  return newState;
+}
+```
+
+## Decision Logic
+
+```javascript
+function selectNextAction(state) {
+  // === Termination Checks ===
+
+  // User exit
+  if (state.status === 'user_exit') return null;
+
+  // Completed
+  if (state.status === 'completed') return null;
+
+  // Error limit exceeded
+  if (state.error_count >= state.max_errors) {
+    return 'action-abort';
+  }
+
+  // Max iterations exceeded
+  if (state.iteration_count >= state.max_iterations) {
+    return 'action-complete';
+  }
+
+  // === Action Selection ===
+
+  // 1. Not initialized yet
+  if (state.status === 'pending') {
+    return 'action-init';
+  }
+
+  // 1.5. Requirement analysis (在 init 后，diagnosis 前)
+  if (state.status === 'running' &&
+      state.completed_actions.includes('action-init') &&
+      !state.completed_actions.includes('action-analyze-requirements')) {
+    return 'action-analyze-requirements';
+  }
+
+  // 1.6. 如果需求分析发现歧义需要澄清，暂停等待用户
+  if (state.requirement_analysis?.status === 'needs_clarification') {
+    return null;  // 等待用户澄清后继续
+  }
+
+  // 1.7. 如果需求分析覆盖度不足，优先触发 Gemini 深度分析
+  if (state.requirement_analysis?.coverage?.status === 'unsatisfied' &&
+      !state.completed_actions.includes('action-gemini-analysis')) {
+    return 'action-gemini-analysis';
+  }
+
+  // 2. Check if Gemini analysis is requested or needed
+  if (shouldTriggerGeminiAnalysis(state)) {
+    return 'action-gemini-analysis';
+  }
+
+  // 3. Check if Gemini analysis is running
+  if (state.gemini_analysis?.status === 'running') {
+    // Wait for Gemini analysis to complete
+    return null;  // Orchestrator will be re-triggered when CLI completes
+  }
+
+  // 4. Run diagnosis in order (only if not completed)
+  const diagnosisOrder = ['context', 'memory', 'dataflow', 'agent', 'docs', 'token_consumption'];
+
+  for (const diagType of diagnosisOrder) {
+    if (state.diagnosis[diagType] === null) {
+      // Check if user wants to skip this diagnosis
+      if (!state.focus_areas.length || state.focus_areas.includes(diagType)) {
+        return `action-diagnose-${diagType}`;
+      }
+      // For docs diagnosis, also check 'all' focus_area
+      if (diagType === 'docs' && state.focus_areas.includes('all')) {
+        return 'action-diagnose-docs';
+      }
+    }
+  }
+
+  // 5. All diagnosis complete, generate report if not done
+  const allDiagnosisComplete = diagnosisOrder.every(
+    d => state.diagnosis[d] !== null || !state.focus_areas.includes(d)
+  );
+
+  if (allDiagnosisComplete && !state.completed_actions.includes('action-generate-report')) {
+    return 'action-generate-report';
+  }
+
+  // 6. Report generated, propose fixes if not done
+  if (state.completed_actions.includes('action-generate-report') &&
+      state.proposed_fixes.length === 0 &&
+      state.issues.length > 0) {
+    return 'action-propose-fixes';
+  }
+
+  // 7. Fixes proposed, check if user wants to apply
+  if (state.proposed_fixes.length > 0 && state.pending_fixes.length > 0) {
+    return 'action-apply-fix';
+  }
+
+  // 8. Fixes applied, verify
+  if (state.applied_fixes.length > 0 &&
+      state.applied_fixes.some(f => f.verification_result === 'pending')) {
+    return 'action-verify';
+  }
+
+  // 9. Quality gate check
+  if (state.quality_gate === 'pass') {
+    return 'action-complete';
+  }
+
+  // 10. More iterations needed
+  if (state.iteration_count < state.max_iterations &&
+      state.quality_gate !== 'pass' &&
+      state.issues.some(i => i.severity === 'critical' || i.severity === 'high')) {
+    // Reset diagnosis for re-evaluation
+    return 'action-diagnose-context';  // Start new iteration
+  }
+
+  // 11. Default: complete
+  return 'action-complete';
+}
+
+/**
+ * 判断是否需要触发 Gemini CLI 分析
+ */
+function shouldTriggerGeminiAnalysis(state) {
+  // 已完成 Gemini 分析，不再触发
+  if (state.gemini_analysis?.status === 'completed') {
+    return false;
+  }
+
+  // 用户显式请求
+  if (state.gemini_analysis_requested === true) {
+    return true;
+  }
+
+  // 发现 critical 问题且未进行深度分析
+  if (state.issues.some(i => i.severity === 'critical') &&
+      !state.completed_actions.includes('action-gemini-analysis')) {
+    return true;
+  }
+
+  // 用户指定了需要 Gemini 分析的 focus_areas
+  const geminiAreas = ['architecture', 'prompt', 'performance', 'custom'];
+  if (state.focus_areas.some(area => geminiAreas.includes(area))) {
+    return true;
+  }
+
+  // 标准诊断完成但问题未得到解决，需要深度分析
+  const diagnosisComplete = ['context', 'memory', 'dataflow', 'agent', 'docs'].every(
+    d => state.diagnosis[d] !== null
+  );
+  if (diagnosisComplete &&
+      state.issues.length > 0 &&
+      state.iteration_count > 0 &&
+      !state.completed_actions.includes('action-gemini-analysis')) {
+    // 第二轮迭代如果问题仍存在，触发 Gemini 分析
+    return true;
+  }
+
+  return false;
+}
+```
+
+## Execution Loop
+
+```javascript
+async function runOrchestrator(workDir) {
+  console.log('=== Skill Tuning Orchestrator Started ===');
+
+  let iteration = 0;
+  const MAX_LOOP_ITERATIONS = 50;  // Safety limit
+
+  while (iteration < MAX_LOOP_ITERATIONS) {
+    iteration++;
+
+    // 1. Read current state
+    const state = JSON.parse(Read(`${workDir}/state.json`));
+    console.log(`[Loop ${iteration}] Status: ${state.status}, Action: ${state.current_action}`);
+
+    // 2. Select next action
+    const actionId = selectNextAction(state);
+
+    if (!actionId) {
+      console.log('No action selected, terminating orchestrator.');
+      break;
+    }
+
+    console.log(`[Loop ${iteration}] Executing: ${actionId}`);
+
+    // 3. Update state: current action
+    // FIX CTX-001: sliding window for action_history (keep last 10)
+    updateState({
+      current_action: actionId,
+      action_history: [...state.action_history, {
+        action: actionId,
+        started_at: new Date().toISOString(),
+        completed_at: null,
+        result: null,
+        output_files: []
+      }].slice(-10)  // Sliding window: prevent unbounded growth
+    });
+
+    // 4. Execute action
+    try {
+      const actionPrompt = Read(`phases/actions/${actionId}.md`);
+      // FIX CTX-003: Pass state path + key fields only instead of full state
+      const stateKeyInfo = {
+        status: state.status,
+        iteration_count: state.iteration_count,
+        issues_by_severity: state.issues_by_severity,
+        quality_gate: state.quality_gate,
+        current_action: state.current_action,
+        completed_actions: state.completed_actions,
+        user_issue_description: state.user_issue_description,
+        target_skill: { name: state.target_skill.name, path: state.target_skill.path }
+      };
+      const stateKeyJson = JSON.stringify(stateKeyInfo, null, 2);
+
+      const result = await Task({
+        subagent_type: 'universal-executor',
+        run_in_background: false,
+        prompt: `
+[CONTEXT]
+You are executing action "${actionId}" for skill-tuning workflow.
+Work directory: ${workDir}
+
+[STATE KEY INFO]
+${stateKeyJson}
+
+[FULL STATE PATH]
+${workDir}/state.json
+(Read full state from this file if you need additional fields)
+
+[ACTION INSTRUCTIONS]
+${actionPrompt}
+
+[OUTPUT REQUIREMENT]
+After completing the action:
+1. Write any output files to the work directory
+2. Return a JSON object with:
+   - stateUpdates: object with state fields to update
+   - outputFiles: array of files created
+   - summary: brief description of what was done
+`
+      });
+
+      // 5. Parse result and update state
+      let actionResult;
+      try {
+        actionResult = JSON.parse(result);
+      } catch (e) {
+        actionResult = {
+          stateUpdates: {},
+          outputFiles: [],
+          summary: result
+        };
+      }
+
+      // 6. Update state: action complete
+      const updatedHistory = [...state.action_history];
+      updatedHistory[updatedHistory.length - 1] = {
+        ...updatedHistory[updatedHistory.length - 1],
+        completed_at: new Date().toISOString(),
+        result: 'success',
+        output_files: actionResult.outputFiles || []
+      };
+
+      updateState({
+        current_action: null,
+        completed_actions: [...state.completed_actions, actionId],
+        action_history: updatedHistory,
+        ...actionResult.stateUpdates
+      });
+
+      console.log(`[Loop ${iteration}] Completed: ${actionId}`);
+
+    } catch (error) {
+      console.log(`[Loop ${iteration}] Error in ${actionId}: ${error.message}`);
+
+      // Error handling
+      // FIX CTX-002: sliding window for errors (keep last 5)
+      updateState({
+        current_action: null,
+        errors: [...state.errors, {
+          action: actionId,
+          message: error.message,
+          timestamp: new Date().toISOString(),
+          recoverable: true
+        }].slice(-5),  // Sliding window: prevent unbounded growth
+        error_count: state.error_count + 1
+      });
+    }
+  }
+
+  console.log('=== Skill Tuning Orchestrator Finished ===');
+}
+```
+
+## Action Catalog
+
+| Action | Purpose | Preconditions | Effects |
+|--------|---------|---------------|---------|
+| [action-init](actions/action-init.md) | Initialize tuning session | status === 'pending' | Creates work dirs, backup, sets status='running' |
+| [action-analyze-requirements](actions/action-analyze-requirements.md) | Analyze user requirements | init completed | Sets requirement_analysis, optimizes focus_areas |
+| [action-diagnose-context](actions/action-diagnose-context.md) | Analyze context explosion | status === 'running' | Sets diagnosis.context |
+| [action-diagnose-memory](actions/action-diagnose-memory.md) | Analyze long-tail forgetting | status === 'running' | Sets diagnosis.memory |
+| [action-diagnose-dataflow](actions/action-diagnose-dataflow.md) | Analyze data flow issues | status === 'running' | Sets diagnosis.dataflow |
+| [action-diagnose-agent](actions/action-diagnose-agent.md) | Analyze agent coordination | status === 'running' | Sets diagnosis.agent |
+| [action-diagnose-docs](actions/action-diagnose-docs.md) | Analyze documentation structure | status === 'running', focus includes 'docs' | Sets diagnosis.docs |
+| [action-gemini-analysis](actions/action-gemini-analysis.md) | Deep analysis via Gemini CLI | User request OR critical issues | Sets gemini_analysis, adds issues |
+| [action-generate-report](actions/action-generate-report.md) | Generate consolidated report | All diagnoses complete | Creates tuning-report.md |
+| [action-propose-fixes](actions/action-propose-fixes.md) | Generate fix proposals | Report generated, issues > 0 | Sets proposed_fixes |
+| [action-apply-fix](actions/action-apply-fix.md) | Apply selected fix | pending_fixes > 0 | Updates applied_fixes |
+| [action-verify](actions/action-verify.md) | Verify applied fixes | applied_fixes with pending verification | Updates verification_result |
+| [action-complete](actions/action-complete.md) | Finalize session | quality_gate='pass' OR max_iterations | Sets status='completed' |
+| [action-abort](actions/action-abort.md) | Abort on errors | error_count >= max_errors | Sets status='failed' |
+
+## Termination Conditions
+
+- `status === 'completed'`: Normal completion
+- `status === 'user_exit'`: User requested exit
+- `status === 'failed'`: Unrecoverable error
+- `requirement_analysis.status === 'needs_clarification'`: Waiting for user clarification (暂停，非终止)
+- `error_count >= max_errors`: Too many errors (default: 3)
+- `iteration_count >= max_iterations`: Max iterations reached (default: 5)
+- `quality_gate === 'pass'`: All quality criteria met
+
+## Error Recovery
+
+| Error Type | Recovery Strategy |
+|------------|-------------------|
+| Action execution failed | Retry up to 3 times, then skip |
+| State parse error | Restore from backup |
+| File write error | Retry with alternative path |
+| User abort | Save state and exit gracefully |
+
+## User Interaction Points
+
+The orchestrator pauses for user input at these points:
+
+1. **action-init**: Confirm target skill and describe issue
+2. **action-propose-fixes**: Select which fixes to apply
+3. **action-verify**: Review verification results, decide to continue or stop
+4. **action-complete**: Review final summary