claude-code-workflow 6.3.26 → 6.3.28

package/.claude/skills/skill-tuning/specs/quality-gates.md

@@ -0,0 +1,263 @@
+# Quality Gates
+
+Quality thresholds and verification criteria for skill tuning.
+
+## When to Use
+
+| Phase | Usage | Section |
+|-------|-------|---------|
+| action-generate-report | Calculate quality score | Scoring |
+| action-verify | Check quality gates | Gate Definitions |
+| action-complete | Final assessment | Pass Criteria |
+
+---
+
+## Quality Dimensions
+
+### 1. Issue Severity Distribution (40%)
+
+Measures the severity profile of identified issues.
+
+| Metric | Weight | Calculation |
+|--------|--------|-------------|
+| Critical Issues | -25 each | High penalty |
+| High Issues | -15 each | Significant penalty |
+| Medium Issues | -5 each | Moderate penalty |
+| Low Issues | -1 each | Minor penalty |
+
+**Score Calculation**:
+```javascript
+function calculateSeverityScore(issues) {
+  const weights = { critical: 25, high: 15, medium: 5, low: 1 };
+  const deductions = issues.reduce((sum, issue) =>
+    sum + (weights[issue.severity] || 0), 0);
+  return Math.max(0, 100 - deductions);
+}
+```
+
+### 2. Fix Effectiveness (30%)
+
+Measures success rate of applied fixes.
+
+| Metric | Weight | Threshold |
+|--------|--------|-----------|
+| Fixes Verified Pass | +30 | > 80% pass rate |
+| Fixes Verified Fail | -20 | < 50% triggers review |
+| Issues Resolved | +10 | Per resolved issue |
+
+**Score Calculation**:
+```javascript
+function calculateFixScore(appliedFixes) {
+  const total = appliedFixes.length;
+  if (total === 0) return 100;  // No fixes needed = good
+
+  const passed = appliedFixes.filter(f => f.verification_result === 'pass').length;
+  return Math.round((passed / total) * 100);
+}
+```
+
+### 3. Coverage Completeness (20%)
+
+Measures diagnosis coverage across all areas.
+
+| Metric | Weight | Threshold |
+|--------|--------|-----------|
+| All 4 diagnosis complete | +20 | Full coverage |
+| 3 diagnosis complete | +15 | Good coverage |
+| 2 diagnosis complete | +10 | Partial coverage |
+| < 2 diagnosis complete | +0 | Insufficient |
+
+### 4. Iteration Efficiency (10%)
+
+Measures how quickly issues are resolved.
+
+| Metric | Weight | Threshold |
+|--------|--------|-----------|
+| Resolved in 1 iteration | +10 | Excellent |
+| Resolved in 2 iterations | +7 | Good |
+| Resolved in 3 iterations | +4 | Acceptable |
+| > 3 iterations | +0 | Needs improvement |
+
+---
+
+## Gate Definitions
+
+### Gate: PASS
+
+**Threshold**: Quality Score >= 80 AND Critical Issues = 0 AND High Issues <= 2
+
+**Meaning**: Skill is production-ready with minor issues.
+
+**Actions**:
+- Complete tuning session
+- Generate summary report
+- No further fixes required
+
+### Gate: REVIEW
+
+**Threshold**: Quality Score 60-79 OR High Issues 3-5
+
+**Meaning**: Skill has issues requiring attention.
+
+**Actions**:
+- Review remaining issues
+- Apply additional fixes if possible
+- May require manual intervention
+
+### Gate: FAIL
+
+**Threshold**: Quality Score < 60 OR Critical Issues > 0 OR High Issues > 5
+
+**Meaning**: Skill has serious issues blocking deployment.
+
+**Actions**:
+- Must fix critical issues
+- Re-run diagnosis after fixes
+- Consider architectural review
+
+---
+
+## Quality Score Calculation
+
+```javascript
+function calculateQualityScore(state) {
+  // Dimension 1: Severity (40%)
+  const severityScore = calculateSeverityScore(state.issues);
+
+  // Dimension 2: Fix Effectiveness (30%)
+  const fixScore = calculateFixScore(state.applied_fixes);
+
+  // Dimension 3: Coverage (20%)
+  const diagnosisCount = Object.values(state.diagnosis)
+    .filter(d => d !== null).length;
+  const coverageScore = [0, 0, 10, 15, 20][diagnosisCount] || 0;
+
+  // Dimension 4: Efficiency (10%)
+  const efficiencyScore = state.iteration_count <= 1 ? 10 :
+                          state.iteration_count <= 2 ? 7 :
+                          state.iteration_count <= 3 ? 4 : 0;
+
+  // Weighted total
+  const total = (severityScore * 0.4) +
+                (fixScore * 0.3) +
+                (coverageScore * 1.0) +  // Already scaled to 20
+                (efficiencyScore * 1.0);  // Already scaled to 10
+
+  return Math.round(total);
+}
+
+function determineQualityGate(state) {
+  const score = calculateQualityScore(state);
+  const criticalCount = state.issues.filter(i => i.severity === 'critical').length;
+  const highCount = state.issues.filter(i => i.severity === 'high').length;
+
+  if (criticalCount > 0) return 'fail';
+  if (highCount > 5) return 'fail';
+  if (score < 60) return 'fail';
+
+  if (highCount > 2) return 'review';
+  if (score < 80) return 'review';
+
+  return 'pass';
+}
+```
+
+---
+
+## Verification Criteria
+
+### For Each Issue Type
+
+#### Context Explosion Issues
+- [ ] Token count does not grow unbounded
+- [ ] History limited to reasonable size
+- [ ] No full content in prompts (paths used instead)
+- [ ] Agent returns are compact
+
+#### Long-tail Forgetting Issues
+- [ ] Constraints visible in all phase prompts
+- [ ] State schema includes requirements field
+- [ ] Checkpoints exist at key milestones
+- [ ] Output matches original constraints
+
+#### Data Flow Issues
+- [ ] Single state.json after execution
+- [ ] No orphan state files
+- [ ] Schema validation active
+- [ ] Consistent field naming
+
+#### Agent Coordination Issues
+- [ ] All Task calls have error handling
+- [ ] Agent results validated before use
+- [ ] No nested agent calls
+- [ ] Tool declarations match usage
+
+---
+
+## Iteration Control
+
+### Max Iterations
+
+Default: 5 iterations
+
+**Rationale**:
+- Each iteration may introduce new issues
+- Diminishing returns after 3-4 iterations
+- Prevents infinite loops
+
+### Iteration Exit Criteria
+
+```javascript
+function shouldContinueIteration(state) {
+  // Exit if quality gate passed
+  if (state.quality_gate === 'pass') return false;
+
+  // Exit if max iterations reached
+  if (state.iteration_count >= state.max_iterations) return false;
+
+  // Exit if no improvement in last 2 iterations
+  if (state.iteration_count >= 2) {
+    const recentHistory = state.action_history.slice(-10);
+    const issuesResolvedRecently = recentHistory.filter(a =>
+      a.action === 'action-verify' && a.result === 'success'
+    ).length;
+
+    if (issuesResolvedRecently === 0) {
+      console.log('No progress in recent iterations, stopping.');
+      return false;
+    }
+  }
+
+  // Continue if critical/high issues remain
+  const hasUrgentIssues = state.issues.some(i =>
+    i.severity === 'critical' || i.severity === 'high'
+  );
+
+  return hasUrgentIssues;
+}
+```
+
+---
+
+## Reporting Format
+
+### Quality Summary Table
+
+| Dimension | Score | Weight | Weighted |
+|-----------|-------|--------|----------|
+| Severity Distribution | {score}/100 | 40% | {weighted} |
+| Fix Effectiveness | {score}/100 | 30% | {weighted} |
+| Coverage Completeness | {score}/20 | 20% | {score} |
+| Iteration Efficiency | {score}/10 | 10% | {score} |
+| **Total** | | | **{total}/100** |
+
+### Gate Status
+
+```
+Quality Gate: {PASS|REVIEW|FAIL}
+
+Criteria:
+- Quality Score: {score} (threshold: 60)
+- Critical Issues: {count} (threshold: 0)
+- High Issues: {count} (threshold: 5)
+```

package/.claude/skills/skill-tuning/specs/skill-authoring-principles.md

@@ -0,0 +1,189 @@
+# Skill Authoring Principles
+
+Skill 撰写首要准则。所有诊断和优化以此为纲。
+
+---
+
+## 核心原则
+
+```
+简洁高效 → 去除无关存储 → 去除中间存储 → 上下文流转
+```
+
+---
+
+## 1. 简洁高效
+
+**原则**：最小化实现，只做必要的事
+
+| DO | DON'T |
+|----|-------|
+| 单一职责阶段 | 臃肿的多功能阶段 |
+| 直接的数据路径 | 迂回的处理流程 |
+| 必要的字段 | 冗余的 schema 定义 |
+| 精准的 prompt | 过度详细的指令 |
+
+**检测模式**：
+- Phase 文件 > 200 行 → 需拆分
+- State schema 字段 > 20 个 → 需精简
+- 同一数据多处定义 → 需去重
+
+---
+
+## 2. 去除无关存储
+
+**原则**：不存储不需要的数据
+
+| DO | DON'T |
+|----|-------|
+| 只存最终结果 | 存储调试信息 |
+| 存路径引用 | 存完整内容副本 |
+| 存必要索引 | 存全量历史 |
+
+**检测模式**：
+```javascript
+// BAD: 存储完整内容
+state.full_analysis_result = longAnalysisOutput;
+
+// GOOD: 存路径 + 摘要
+state.analysis = {
+  path: `${workDir}/analysis.json`,
+  summary: extractSummary(output),
+  key_findings: extractFindings(output)
+};
+```
+
+**反模式清单**：
+- `state.debug_*` → 删除
+- `state.*_history` (无限增长) → 限制或删除
+- `state.*_cache` (会话内) → 改用内存变量
+- 重复字段 → 合并
+
+---
+
+## 3. 去除中间存储
+
+**原则**：避免临时文件和中间状态文件
+
+| DO | DON'T |
+|----|-------|
+| 直接传递结果 | 写文件再读文件 |
+| 函数返回值 | 中间 JSON 文件 |
+| 管道处理 | 阶段性存储 |
+
+**检测模式**：
+```javascript
+// BAD: 中间文件
+Write(`${workDir}/temp-step1.json`, step1Result);
+const step1 = Read(`${workDir}/temp-step1.json`);
+const step2Result = process(step1);
+Write(`${workDir}/temp-step2.json`, step2Result);
+
+// GOOD: 直接流转
+const step1Result = await executeStep1();
+const step2Result = process(step1Result);
+const finalResult = finalize(step2Result);
+Write(`${workDir}/final-output.json`, finalResult);  // 只存最终结果
+```
+
+**允许的存储**：
+- 最终输出（用户需要的结果）
+- 检查点（长流程恢复用，可选）
+- 备份（修改前的原始文件）
+
+**禁止的存储**：
+- `temp-*.json`
+- `intermediate-*.json`
+- `step[N]-output.json`
+- `*-draft.md`
+
+---
+
+## 4. 上下文流转
+
+**原则**：通过上下文传递而非文件
+
+| DO | DON'T |
+|----|-------|
+| 函数参数传递 | 全局状态读写 |
+| 返回值链式处理 | 文件中转 |
+| prompt 内嵌数据 | 指向外部文件 |
+
+**模式**：
+```javascript
+// 上下文流转模式
+async function executePhase(context) {
+  const { previousResult, constraints, config } = context;
+  
+  const result = await Task({
+    prompt: `
+      [CONTEXT]
+      Previous: ${JSON.stringify(previousResult)}
+      Constraints: ${constraints.join(', ')}
+      
+      [TASK]
+      Process and return result directly.
+    `
+  });
+  
+  return {
+    ...context,
+    currentResult: result,
+    completed: ['phase-name']
+  };
+}
+
+// 链式执行
+let ctx = initialContext;
+ctx = await executePhase1(ctx);
+ctx = await executePhase2(ctx);
+ctx = await executePhase3(ctx);
+// ctx 包含完整上下文，无中间文件
+```
+
+**State 最小化**：
+```typescript
+// 只存必要状态
+interface MinimalState {
+  status: 'pending' | 'running' | 'completed';
+  target: { name: string; path: string };
+  result_path: string;  // 最终结果路径
+  error?: string;
+}
+```
+
+---
+
+## 应用场景
+
+### 诊断时检查
+
+| 检查项 | 违反时标记 |
+|--------|-----------|
+| Phase 内写入 temp 文件 | `unnecessary_storage` |
+| State 包含 *_history 无限数组 | `unbounded_state` |
+| 文件写入后立即读取 | `redundant_io` |
+| 多阶段传递完整内容 | `context_bloat` |
+
+### 优化策略
+
+| 问题 | 策略 |
+|------|------|
+| 中间文件过多 | `eliminate_intermediate_files` |
+| State 膨胀 | `minimize_state_schema` |
+| 重复存储 | `deduplicate_storage` |
+| 文件中转 | `context_passing` |
+
+---
+
+## 合规检查清单
+
+```
+□ 无 temp/intermediate 文件写入
+□ State schema < 15 个字段
+□ 无重复数据存储
+□ Phase 间通过上下文/返回值传递
+□ 只存最终结果文件
+□ 无无限增长的数组
+□ 无调试字段残留
+```