claude-code-workflow 6.3.48 → 6.3.49

package/.claude/skills/skill-tuning/specs/tuning-strategies.md

@@ -1,295 +1,160 @@
 # Tuning Strategies
 
-Detailed fix strategies for each problem category with implementation guidance.
+Fix strategies for each problem category. Implementation patterns + verification methods.
 
-## When to Use
+## Usage Context
 
-| Phase | Usage | Section |
-|-------|-------|---------|
-| action-propose-fixes | Strategy selection | Strategy Details |
-| action-apply-fix | Implementation guidance | Implementation |
-| action-verify | Verification steps | Verification |
+| Phase | Usage |
+|-------|-------|
+| action-propose-fixes | Strategy selection + implementation guidance |
+| action-apply-fix | Apply implementation pattern |
+| action-verify | Run verification method |
 
 ---
 
-## Authoring Principles Strategies (P0 - 首要准则)
+## Selection Decision Tree
 
-> **核心原则**：简洁高效 → 去除无关存储 → 去除中间存储 → 上下文流转
+```
+Context Explosion?
+├── history grows unbounded? → sliding_window
+├── full content in prompts? → path_reference
+├── no summarization? → context_summarization
+└── text-based context? → structured_state
 
-### Strategy: eliminate_intermediate_files
+Long-tail Forgetting?
+├── constraints not in phases? → constraint_injection
+├── no requirements in state? → state_constraints_field
+├── no recovery points? → checkpoint_restore
+└── goal drift risk? → goal_embedding
 
-**Purpose**: 删除所有中间文件，改用上下文流转。
+Data Flow?
+├── multiple state files? → state_centralization
+├── no validation? → schema_enforcement
+└── inconsistent names? → field_normalization
 
-**Implementation**:
-```javascript
-// Before: 中间文件
-async function process() {
-  const step1 = await analyze();
-  Write(`${workDir}/step1.json`, JSON.stringify(step1));
+Agent Coordination?
+├── no error handling? → error_wrapping
+├── no result validation? → result_validation
+└── nested agent calls? → flatten_nesting
 
-  const step1Data = JSON.parse(Read(`${workDir}/step1.json`));
-  const step2 = await transform(step1Data);
-  Write(`${workDir}/step2.json`, JSON.stringify(step2));
+Authoring Violation?
+├── intermediate files? → eliminate_intermediate_files
+├── state bloat (>15 fields)? → minimize_state
+├── write→read relay? → context_passing
+└── duplicate storage? → deduplicate_storage
 
-  const step2Data = JSON.parse(Read(`${workDir}/step2.json`));
-  return finalize(step2Data);
-}
+Token Consumption?
+├── verbose prompts? → prompt_compression
+├── full content passing? → lazy_loading
+├── verbose output? → output_minimization
+├── bloated state? → state_field_reduction
+└── multiple output files? → in_memory_consolidation
 
-// After: 上下文流转
-async function process() {
-  const step1 = await analyze();
-  const step2 = await transform(step1);  // 直接传递
-  return finalize(step2);  // 只返回最终结果
-}
+Documentation?
+├── repeated definitions? → consolidate_to_ssot
+├── hardcoded configs? → centralize_mapping_config
+└── conflicting values? → reconcile_conflicting_definitions
 ```
 
-**Risk**: Low
-**Verification**: `ls ${workDir}` 无 temp/intermediate 文件
-
 ---
 
-### Strategy: minimize_state
+## Authoring Principles Strategies (P0)
 
-**Purpose**: 精简 State schema 至必要字段。
+> **Core Principle**: Simplicity → Remove intermediate files → Context passing
 
-**Implementation**:
-```typescript
-// Before: 膨胀的 State
-interface State {
-  status: string;
-  target: TargetInfo;
-  user_input: string;
-  parsed_input: ParsedInput;      // 删除 - 只在处理时用
-  intermediate_result: any;       // 删除 - 中间结果
-  debug_info: DebugInfo;          // 删除 - 调试信息
-  analysis_cache: any;            // 删除 - 缓存
-  full_history: HistoryEntry[];   // 删除 - 无限增长
-  step1_output: any;              // 删除 - 中间输出
-  step2_output: any;              // 删除 - 中间输出
-  final_result: FinalResult;
-}
+### eliminate_intermediate_files
 
-// After: 精简的 State
-interface State {
-  status: 'pending' | 'running' | 'completed' | 'failed';
-  target: { name: string; path: string };
-  result_path: string;            // 最终结果路径
-  error?: string;                 // 仅失败时有
-}
+```javascript
+// Before: File relay between steps
+const step1 = await analyze();
+Write(`${workDir}/step1.json`, JSON.stringify(step1));
+const step1Data = JSON.parse(Read(`${workDir}/step1.json`));
+const step2 = await transform(step1Data);
+
+// After: Direct context passing
+const step1 = await analyze();
+const step2 = await transform(step1);  // No file
+return finalize(step2);                // Only final result persisted
 ```
 
-**Rules**:
-- State 字段 ≤ 15 个
-- 删除所有 `debug_*`, `*_cache`, `*_temp` 字段
-- `*_history` 数组设置上限或改用滚动窗口
+**Verification**: `ls ${workDir}` — no temp/intermediate files
 
-**Risk**: Medium (需确保不丢失必要数据)
-**Verification**: Count state fields ≤ 15
+### minimize_state
 
----
+**Rules**: ≤15 fields, delete `debug_*`, `*_cache`, `*_temp`, apply sliding window to `*_history`.
 
-### Strategy: context_passing
+```typescript
+// Before: Bloated
+interface State { status; target; user_input; parsed_input; intermediate_result; debug_info; analysis_cache; full_history; step1_output; step2_output; final_result; ... }
 
-**Purpose**: 用函数参数/返回值代替文件中转。
+// After: Minimal
+interface State {
+  status: 'pending'|'running'|'completed'|'failed';
+  target: { name: string; path: string };
+  result_path: string;
+  error?: string;
+}
+```
+
+### context_passing
 
-**Implementation**:
 ```javascript
-// 上下文流转模式
 async function executeWorkflow(initialContext) {
   let ctx = initialContext;
-
-  // Phase 1: 直接传递上下文
-  ctx = await executePhase1(ctx);
-
-  // Phase 2: 继续传递
-  ctx = await executePhase2(ctx);
-
-  // Phase 3: 最终处理
+  ctx = await executePhase1(ctx);   // Pass context directly
+  ctx = await executePhase2(ctx);   // Continue passing
   const result = await executePhase3(ctx);
-
-  // 只存最终结果
-  Write(`${ctx.workDir}/result.json`, JSON.stringify(result));
-
+  Write(`${ctx.workDir}/result.json`, JSON.stringify(result));  // Only final
   return result;
 }
-
-// Phase 函数模板
-async function executePhaseN(ctx) {
-  const { previousResult, constraints } = ctx;
-
-  const result = await Task({
-    prompt: `
-      [CONTEXT]
-      ${JSON.stringify(previousResult)}
-
-      [TASK]
-      Process and return result.
-    `
-  });
-
-  // 返回更新后的上下文，不写文件
-  return {
-    ...ctx,
-    previousResult: result,
-    completed: [...ctx.completed, 'phase-n']
-  };
-}
 ```
 
-**Risk**: Low
-**Verification**: 无 Write→Read 紧邻模式
+### deduplicate_storage
 
----
-
-### Strategy: deduplicate_storage
-
-**Purpose**: 消除重复数据存储。
-
-**Implementation**:
 ```javascript
-// Before: 重复存储
-state.user_request = userInput;
-state.original_request = userInput;
-state.input_text = userInput;
-
-// After: 单一来源
-state.input = userInput;  // 唯一存储点
+// Before: state.user_request = state.original_request = state.input_text = input
+// After:  state.input = input;  // Single source
 ```
 
-**Risk**: Low
-**Verification**: 无相同数据多字段存储
-
 ---
 
 ## Context Explosion Strategies
 
-### Strategy: sliding_window
-
-**Purpose**: Limit context history to most recent N items.
+### sliding_window
 
-**Implementation**:
 ```javascript
-// In orchestrator.md or phase files
-const MAX_HISTORY_ITEMS = 5;
-
+const MAX_HISTORY = 5;
 function updateHistory(state, newItem) {
-  const history = state.history || [];
-  const updated = [...history, newItem].slice(-MAX_HISTORY_ITEMS);
-  return { ...state, history: updated };
+  return { ...state, history: [...(state.history || []), newItem].slice(-MAX_HISTORY) };
 }
 ```
 
-**Files to Modify**:
-- `phases/orchestrator.md` - Add history management
-- `phases/state-schema.md` - Document history limit
+### path_reference
 
-**Risk**: Low
-**Verification**:
-- Run skill for 10+ iterations
-- Verify history.length never exceeds MAX_HISTORY_ITEMS
-
----
-
-### Strategy: path_reference
-
-**Purpose**: Pass file paths instead of full content.
-
-**Implementation**:
 ```javascript
-// Before
-const content = Read('data.json');
-const prompt = `Analyze: ${content}`;
-
-// After
-const dataPath = `${workDir}/data.json`;
-const prompt = `Analyze file at: ${dataPath}. Read it first.`;
+// Before: const prompt = `Analyze: ${Read('data.json')}`;
+// After:  const prompt = `Analyze file at: ${dataPath}. Read it first.`;
 ```
 
-**Files to Modify**:
-- All phase files with `${content}` in prompts
+### context_summarization
 
-**Risk**: Low
-**Verification**:
-- Verify agents can still access required data
-- Check token count reduced
-
----
-
-### Strategy: context_summarization
-
-**Purpose**: Add summarization step before passing to next phase.
-
-**Implementation**:
 ```javascript
-// Add summarization agent
-const summarizeResult = await Task({
+// Add summarization before passing to next phase
+const summary = await Task({
   subagent_type: 'universal-executor',
-  prompt: `
-    Summarize the following in <100 words, preserving key facts:
-    ${fullContent}
-
-    Return JSON: { summary: "...", key_points: [...] }
-  `
+  prompt: `Summarize in <100 words: ${fullContent}\nReturn JSON: { summary, key_points[] }`
 });
-
-// Pass summary instead of full content
-nextPhasePrompt = `Previous phase summary: ${summarizeResult.summary}`;
-```
-
-**Files to Modify**:
-- Phase transition points
-- Orchestrator (if autonomous)
-
-**Risk**: Low
-**Verification**:
-- Compare output quality with/without summarization
-- Verify key information preserved
-
----
-
-### Strategy: structured_state
-
-**Purpose**: Replace text-based context with structured JSON state.
-
-**Implementation**:
-```javascript
-// Before: Text-based context passing
-const context = `
-  User requested: ${userRequest}
-  Previous output: ${previousOutput}
-  Current status: ${status}
-`;
-
-// After: Structured state
-const state = {
-  original_request: userRequest,
-  previous_output_path: `${workDir}/output.md`,
-  previous_output_summary: "...",
-  status: status,
-  key_decisions: [...]
-};
+nextPhasePrompt = `Previous summary: ${summary.summary}`;
 ```
 
-**Files to Modify**:
-- `phases/state-schema.md` - Define structure
-- All phases - Use structured fields
-
-**Risk**: Medium (requires refactoring)
-**Verification**:
-- Verify all phases can access required state fields
-- Check backward compatibility
-
 ---
 
 ## Long-tail Forgetting Strategies
 
-### Strategy: constraint_injection
+### constraint_injection
 
-**Purpose**: Inject original constraints into every phase prompt.
-
-**Implementation**:
 ```javascript
-// Add to every phase prompt template
+// Add to EVERY phase prompt
 const phasePrompt = `
 [CONSTRAINTS - FROM ORIGINAL REQUEST]
 ${state.original_requirements.map(r => `- ${r}`).join('\n')}
@@ -297,1241 +162,224 @@ ${state.original_requirements.map(r => `- ${r}`).join('\n')}
 [CURRENT TASK]
 ${taskDescription}
 
-[REMINDER]
-Output MUST satisfy all constraints listed above.
+[REMINDER] Output MUST satisfy all constraints above.
 `;
 ```
 
-**Files to Modify**:
-- All `phases/*.md` files
-- `templates/agent-base.md` (if exists)
-
-**Risk**: Low
-**Verification**:
-- Verify constraints visible in each phase
-- Test with specific constraint, verify output respects it
-
----
+### state_constraints_field
 
-### Strategy: state_constraints_field
-
-**Purpose**: Add dedicated field in state schema for requirements.
-
-**Implementation**:
-```typescript
-// In state-schema.md
-interface State {
-  // Add these fields
-  original_requirements: string[];    // User's original constraints
-  goal_summary: string;               // One-line goal statement
-  constraint_violations: string[];    // Track any violations
-}
-
-// In action-init.md
-function initState(userInput) {
-  return {
-    original_requirements: extractRequirements(userInput),
-    goal_summary: summarizeGoal(userInput),
-    constraint_violations: []
-  };
-}
-```
-
-**Files to Modify**:
-- `phases/state-schema.md`
-- `phases/actions/action-init.md`
-
-**Risk**: Low
-**Verification**:
-- Verify state.json contains requirements after init
-- Check requirements persist through all phases
-
----
-
-### Strategy: checkpoint_restore
-
-**Purpose**: Save state at key milestones for recovery and verification.
-
-**Implementation**:
+Add to state-schema + action-init:
 ```javascript
-// Add checkpoint function
-function createCheckpoint(state, workDir, checkpointName) {
-  const checkpointPath = `${workDir}/checkpoints/${checkpointName}.json`;
-  Write(checkpointPath, JSON.stringify({
-    state: state,
-    timestamp: new Date().toISOString(),
-    name: checkpointName
-  }, null, 2));
-  return checkpointPath;
-}
-
-// Use at key points
-await executePhase2();
-createCheckpoint(state, workDir, 'after-phase-2');
+state.original_requirements = extractRequirements(userInput);
+state.goal_summary = summarizeGoal(userInput);
 ```
 
-**Files to Modify**:
-- `phases/orchestrator.md`
-- Key phase files
+### checkpoint_restore
 
-**Risk**: Low
-**Verification**:
-- Verify checkpoints created at expected points
-- Test restore from checkpoint
-
----
-
-### Strategy: goal_embedding
-
-**Purpose**: Track semantic similarity to original goal throughout execution.
-
-**Implementation**:
 ```javascript
-// Store goal embedding at init
-state.goal_embedding = await embed(state.goal_summary);
-
-// At each major phase, check alignment
-const currentPlanEmbedding = await embed(currentPlan);
-const similarity = cosineSimilarity(state.goal_embedding, currentPlanEmbedding);
-
-if (similarity < 0.7) {
-  console.warn('Goal drift detected! Similarity:', similarity);
-  // Trigger re-alignment
+function createCheckpoint(state, workDir, name) {
+  Write(`${workDir}/checkpoints/${name}.json`, JSON.stringify({
+    state, timestamp: new Date().toISOString(), name
+  }));
 }
+// Use at key phase boundaries
 ```
 
-**Files to Modify**:
-- State schema (add embedding field)
-- Orchestrator (add similarity check)
-
-**Risk**: Medium (requires embedding infrastructure)
-**Verification**:
-- Test with intentional drift, verify detection
-- Verify false positive rate acceptable
-
 ---
 
 ## Data Flow Strategies
 
-### Strategy: state_centralization
-
-**Purpose**: Use single state.json for all persistent data.
+### state_centralization
 
-**Implementation**:
 ```javascript
-// Create state manager
+// Single state manager — replace all direct writes
 const StateManager = {
-  read: (workDir) => JSON.parse(Read(`${workDir}/state.json`)),
-
-  update: (workDir, updates) => {
-    const current = StateManager.read(workDir);
-    const next = { ...current, ...updates, updated_at: new Date().toISOString() };
-    Write(`${workDir}/state.json`, JSON.stringify(next, null, 2));
+  read: (dir) => JSON.parse(Read(`${dir}/state.json`)),
+  update: (dir, updates) => {
+    const next = { ...StateManager.read(dir), ...updates, updated_at: Date.now() };
+    Write(`${dir}/state.json`, JSON.stringify(next, null, 2));
     return next;
-  },
-
-  get: (workDir, path) => {
-    const state = StateManager.read(workDir);
-    return path.split('.').reduce((obj, key) => obj?.[key], state);
   }
 };
-
-// Replace direct writes
-// Before: Write(`${workDir}/config.json`, config);
-// After:  StateManager.update(workDir, { config });
 ```
 
-**Files to Modify**:
-- All phases that write state
-- Create shared state manager
+### schema_enforcement
 
-**Risk**: Medium (significant refactoring)
-**Verification**:
-- Verify single state.json after full run
-- Check no orphan state files
-
----
-
-### Strategy: schema_enforcement
-
-**Purpose**: Add runtime validation using Zod or similar.
-
-**Implementation**:
 ```javascript
-// Define schema (in state-schema.md)
-const StateSchema = {
-  status: ['pending', 'running', 'completed', 'failed'],
-  target_skill: {
-    name: 'string',
-    path: 'string'
-  },
-  // ... full schema
-};
-
 function validateState(state) {
   const errors = [];
-
-  if (!StateSchema.status.includes(state.status)) {
+  if (!['pending','running','completed','failed'].includes(state.status))
     errors.push(`Invalid status: ${state.status}`);
-  }
-
-  if (typeof state.target_skill?.name !== 'string') {
+  if (typeof state.target_skill?.name !== 'string')
     errors.push('target_skill.name must be string');
-  }
-
-  if (errors.length > 0) {
-    throw new Error(`State validation failed:\n${errors.join('\n')}`);
-  }
-
-  return true;
-}
-
-// Use before state write
-function updateState(workDir, updates) {
-  const newState = { ...currentState, ...updates };
-  validateState(newState);  // Throws if invalid
-  Write(`${workDir}/state.json`, JSON.stringify(newState, null, 2));
+  if (errors.length) throw new Error(`Validation failed:\n${errors.join('\n')}`);
 }
+// Call before every state write
 ```
 
-**Files to Modify**:
-- `phases/state-schema.md` - Add validation function
-- All state write locations
-
-**Risk**: Low
-**Verification**:
-- Test with invalid state, verify rejection
-- Verify valid state accepted
-
----
-
-### Strategy: field_normalization
-
-**Purpose**: Normalize field names across all phases.
+### field_normalization
 
-**Implementation**:
 ```javascript
-// Create normalization mapping
-const FIELD_NORMALIZATIONS = {
-  'title': 'name',
-  'identifier': 'id',
-  'state': 'status',
-  'error': 'errors'
-};
-
+const NORMALIZATIONS = { 'title': 'name', 'identifier': 'id', 'state': 'status' };
 function normalizeData(data) {
-  if (typeof data !== 'object' || data === null) return data;
-
-  const normalized = {};
-  for (const [key, value] of Object.entries(data)) {
-    const normalizedKey = FIELD_NORMALIZATIONS[key] || key;
-    normalized[normalizedKey] = normalizeData(value);
-  }
-  return normalized;
+  if (typeof data !== 'object' || !data) return data;
+  return Object.fromEntries(
+    Object.entries(data).map(([k, v]) => [NORMALIZATIONS[k] || k, normalizeData(v)])
+  );
 }
-
-// Apply when reading external data
-const rawData = JSON.parse(Read(filePath));
-const normalizedData = normalizeData(rawData);
 ```
 
-**Files to Modify**:
-- Data ingestion points
-- State update functions
-
-**Risk**: Low
-**Verification**:
-- Verify consistent field names in state
-- Check no data loss during normalization
-
 ---
 
 ## Agent Coordination Strategies
 
-### Strategy: error_wrapping
+### error_wrapping
 
-**Purpose**: Add try-catch to all Task calls.
-
-**Implementation**:
 ```javascript
-// Wrapper function
 async function safeTask(config, state, updateState) {
-  const maxRetries = 3;
-
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+  for (let attempt = 1; attempt <= 3; attempt++) {
     try {
       const result = await Task(config);
-
-      // Validate result
-      if (!result) throw new Error('Empty result from agent');
-
+      if (!result) throw new Error('Empty result');
       return result;
     } catch (error) {
-      console.log(`Task attempt ${attempt} failed: ${error.message}`);
-
-      if (attempt === maxRetries) {
-        updateState({
-          errors: [...state.errors, {
-            action: config.subagent_type,
-            message: error.message,
-            timestamp: new Date().toISOString()
-          }],
-          error_count: state.error_count + 1
-        });
+      if (attempt === 3) {
+        updateState({ error_count: state.error_count + 1 });
         throw error;
       }
-
-      // Wait before retry
       await new Promise(r => setTimeout(r, 1000 * attempt));
     }
   }
 }
 ```
 
-**Files to Modify**:
-- All files with Task calls
-
-**Risk**: Low
-**Verification**:
-- Simulate agent failure, verify graceful handling
-- Verify retry logic works
-
----
-
-### Strategy: result_validation
+### result_validation
 
-**Purpose**: Validate agent returns before use.
-
-**Implementation**:
 ```javascript
-function validateAgentResult(result, expectedSchema) {
-  // Try JSON parse
-  let parsed;
-  try {
-    parsed = typeof result === 'string' ? JSON.parse(result) : result;
-  } catch (e) {
-    throw new Error(`Agent result is not valid JSON: ${result.slice(0, 100)}`);
+function validateAgentResult(result, requiredFields) {
+  const parsed = typeof result === 'string' ? JSON.parse(result) : result;
+  for (const field of requiredFields) {
+    if (!(field in parsed)) throw new Error(`Missing: ${field}`);
   }
-
-  // Check required fields
-  for (const field of expectedSchema.required || []) {
-    if (!(field in parsed)) {
-      throw new Error(`Missing required field: ${field}`);
-    }
-  }
-
   return parsed;
 }
-
-// Usage
-const rawResult = await Task({...});
-const validResult = validateAgentResult(rawResult, {
-  required: ['status', 'output_file']
-});
 ```
 
-**Files to Modify**:
-- All locations where agent results are used
-
-**Risk**: Low
-**Verification**:
-- Test with invalid agent output
-- Verify proper error messages
-
----
-
-### Strategy: flatten_nesting
-
-**Purpose**: Remove nested agent calls, use orchestrator coordination.
+### flatten_nesting
 
-**Implementation**:
 ```javascript
-// Before: Agent A calls Agent B in its prompt
-// Agent A prompt: "... then call Task({subagent_type: 'B', ...}) ..."
-
+// Before: Agent A's prompt tells it to call Task({subagent_type: 'B'})
 // After: Agent A returns signal, orchestrator handles
-// Agent A prompt: "If you need further analysis, return: { needs_agent_b: true, context: ... }"
-
-// Orchestrator handles:
-const resultA = await Task({ subagent_type: 'A', ... });
-const parsedA = JSON.parse(resultA);
-
+// Agent A: return { needs_agent_b: true, context: {...} }
+// Orchestrator:
 if (parsedA.needs_agent_b) {
-  const resultB = await Task({
-    subagent_type: 'B',
-    prompt: `Continue analysis with context: ${JSON.stringify(parsedA.context)}`
-  });
-}
-```
-
-**Files to Modify**:
-- Phase files with nested Task calls
-- Orchestrator decision logic
-
-**Risk**: Medium (may change agent behavior)
-**Verification**:
-- Verify no nested Task patterns
-- Test agent chain via orchestrator
-
----
-
-## Documentation Strategies
-
-文档去重和冲突解决策略。
-
----
-
-### Strategy: consolidate_to_ssot
-
-**Purpose**: 将重复定义合并到单一真相来源 (Single Source of Truth)。
-
-**Implementation**:
-```javascript
-// 合并流程
-async function consolidateToSSOT(state, duplicates) {
-  // 1. 识别最完整的定义位置
-  const canonical = selectCanonicalSource(duplicates);
-
-  // 2. 确保规范位置包含完整定义
-  const fullDefinition = mergeDefinitions(duplicates);
-  Write(canonical.file, fullDefinition);
-
-  // 3. 替换其他位置为引用
-  for (const dup of duplicates.filter(d => d.file !== canonical.file)) {
-    const reference = generateReference(canonical.file, dup.type);
-    // 例如: "详见 [state-schema.md](phases/state-schema.md)"
-    replaceWithReference(dup.file, dup.location, reference);
-  }
-
-  return { canonical: canonical.file, removed: duplicates.length - 1 };
-}
-
-function selectCanonicalSource(duplicates) {
-  // 优先级: specs/ > phases/ > SKILL.md
-  const priority = ['specs/', 'phases/', 'SKILL.md'];
-  return duplicates.sort((a, b) => {
-    const aIdx = priority.findIndex(p => a.file.includes(p));
-    const bIdx = priority.findIndex(p => b.file.includes(p));
-    return aIdx - bIdx;
-  })[0];
-}
-```
-
-**Risk**: Low
-**Verification**:
-- 确认只有一处包含完整定义
-- 其他位置包含有效引用链接
-
----
-
-### Strategy: centralize_mapping_config
-
-**Purpose**: 将硬编码配置提取到集中的 JSON 文件，代码改为加载配置。
-
-**Implementation**:
-```javascript
-// 1. 创建集中配置文件
-const config = {
-  version: "1.0.0",
-  categories: {
-    context_explosion: {
-      pattern_ids: ["CTX-001", "CTX-002"],
-      strategies: ["sliding_window", "path_reference"]
-    }
-    // ... 从硬编码中提取
-  }
-};
-Write('specs/category-mappings.json', JSON.stringify(config, null, 2));
-
-// 2. 重构代码加载配置
-// Before:
-function findTaxonomyMatch(category) {
-  const patternMapping = {
-    'context_explosion': { category: 'context_explosion', pattern_ids: [...] }
-    // 硬编码
-  };
-  return patternMapping[category];
+  resultB = await Task({ subagent_type: 'B', prompt: `Context: ${parsedA.context}` });
 }
-
-// After:
-function findTaxonomyMatch(category) {
-  const mappings = JSON.parse(Read('specs/category-mappings.json'));
-  const config = mappings.categories[category];
-  if (!config) return null;
-  return { category, pattern_ids: config.pattern_ids, severity_hint: config.severity_hint };
-}
-```
-
-**Risk**: Medium (需要测试配置加载逻辑)
-**Verification**:
-- JSON 文件语法正确
-- 所有原硬编码的值都已迁移
-- 功能行为不变
-
----
-
-### Strategy: reconcile_conflicting_definitions
-
-**Purpose**: 调和冲突的定义，由用户选择正确版本后统一更新。
-
-**Implementation**:
-```javascript
-async function reconcileConflicts(conflicts) {
-  for (const conflict of conflicts) {
-    // 1. 展示冲突给用户
-    const options = conflict.definitions.map(def => ({
-      label: `${def.file}: ${def.value}`,
-      description: `来自 ${def.file}`
-    }));
-
-    const choice = await AskUserQuestion({
-      questions: [{
-        question: `发现冲突定义: "${conflict.key}"，请选择正确版本`,
-        header: '冲突解决',
-        options: options,
-        multiSelect: false
-      }]
-    });
-
-    // 2. 更新所有文件为选中的版本
-    const selected = conflict.definitions[choice.index];
-    for (const def of conflict.definitions) {
-      if (def.file !== selected.file) {
-        updateDefinition(def.file, conflict.key, selected.value);
-      }
-    }
-  }
-
-  return { resolved: conflicts.length };
-}
-```
-
-**Risk**: Low (用户确认后执行)
-**Verification**:
-- 所有位置的定义一致
-- 无新冲突产生
-
----
-
-## Strategy Selection Guide
-
-```
-Issue Type: Context Explosion
-├── history grows unbounded? → sliding_window
-├── full content in prompts? → path_reference
-├── no summarization? → context_summarization
-└── text-based context? → structured_state
-
-Issue Type: Long-tail Forgetting
-├── constraints not in phases? → constraint_injection
-├── no requirements in state? → state_constraints_field
-├── no recovery points? → checkpoint_restore
-└── goal drift risk? → goal_embedding
-
-Issue Type: Data Flow
-├── multiple state files? → state_centralization
-├── no validation? → schema_enforcement
-└── inconsistent names? → field_normalization
-
-Issue Type: Agent Coordination
-├── no error handling? → error_wrapping
-├── no result validation? → result_validation
-└── nested agent calls? → flatten_nesting
-
-Issue Type: Prompt Engineering
-├── vague instructions? → structured_prompt
-├── inconsistent output? → output_schema
-├── hallucination risk? → grounding_context
-└── format drift? → format_enforcement
-
-Issue Type: Architecture
-├── unclear responsibilities? → phase_decomposition
-├── tight coupling? → interface_contracts
-├── poor extensibility? → plugin_architecture
-└── complex flow? → state_machine
-
-Issue Type: Performance
-├── high token usage? → token_budgeting
-├── slow execution? → parallel_execution
-├── redundant computation? → result_caching
-└── large files? → lazy_loading
-
-Issue Type: Error Handling
-├── no recovery? → graceful_degradation
-├── silent failures? → error_propagation
-├── no logging? → structured_logging
-└── unclear errors? → error_context
-
-Issue Type: Output Quality
-├── inconsistent quality? → quality_gates
-├── no verification? → output_validation
-├── format issues? → template_enforcement
-└── incomplete output? → completeness_check
-
-Issue Type: User Experience
-├── no progress? → progress_tracking
-├── unclear status? → status_communication
-├── no feedback? → interactive_checkpoints
-└── confusing flow? → guided_workflow
-
-Issue Type: Documentation Redundancy
-├── 核心定义重复? → consolidate_to_ssot
-└── 硬编码配置重复? → centralize_mapping_config
-
-Issue Type: Documentation Conflict
-└── 定义不一致? → reconcile_conflicting_definitions
 ```
 
 ---
 
-## General Tuning Strategies (按需 via Gemini CLI)
-
-以下策略针对更通用的优化场景，通常需要 Gemini CLI 进行深度分析后生成具体实现。
-
----
-
-### Prompt Engineering Strategies
-
-#### Strategy: structured_prompt
+## Token Consumption Strategies
 
-**Purpose**: 将模糊指令转换为结构化提示词。
+### prompt_compression
 
-**Implementation**:
 ```javascript
-// Before: Vague prompt
-const prompt = "Please analyze the code and give suggestions";
-
-// After: Structured prompt
-const prompt = `
-[ROLE]
-You are a code analysis expert specializing in ${domain}.
-
-[TASK]
-Analyze the provided code for:
-1. Code quality issues
-2. Performance bottlenecks
-3. Security vulnerabilities
-
-[INPUT]
-File: ${filePath}
-Context: ${context}
-
-[OUTPUT FORMAT]
-Return JSON:
-{
-  "issues": [{ "type": "...", "severity": "...", "location": "...", "suggestion": "..." }],
-  "summary": "..."
-}
-
-[CONSTRAINTS]
-- Focus on actionable issues only
-- Limit to top 10 findings
-`;
+// Before: Long inline prompt with role, detailed instructions, full code
+// After: Key instructions only
+const prompt = `Analyze ${codePath} for: patterns, security, performance.
+Return JSON: { issues: [], severity: string }`;
 ```
 
-**Risk**: Low
-**Verification**: Check output consistency across multiple runs
-
----
-
-#### Strategy: output_schema
-
-**Purpose**: 强制 LLM 输出符合特定 schema。
+### lazy_loading
 
-**Implementation**:
 ```javascript
-// Define expected schema
-const outputSchema = {
-  type: 'object',
-  required: ['status', 'result'],
-  properties: {
-    status: { enum: ['success', 'error', 'partial'] },
-    result: { type: 'object' },
-    errors: { type: 'array' }
-  }
-};
-
-// Include in prompt
-const prompt = `
-...task description...
-
-[OUTPUT SCHEMA]
-Your response MUST be valid JSON matching this schema:
-${JSON.stringify(outputSchema, null, 2)}
-
-[VALIDATION]
-Before returning, verify your output:
-1. Is it valid JSON?
-2. Does it have all required fields?
-3. Are field types correct?
-`;
+// Before: const prompt = `Analyze:\n${Read(filePath)}`;
+// After:  const prompt = `Analyze file at: ${filePath}\n(Read if needed)\nReturn: { summary, issues[] }`;
 ```
 
-**Risk**: Low
-**Verification**: JSON.parse + schema validation
+### output_minimization
 
----
-
-#### Strategy: grounding_context
-
-**Purpose**: 提供足够上下文减少幻觉。
-
-**Implementation**:
 ```javascript
-// Gather grounding context
-const groundingContext = {
-  codebase_patterns: await analyzePatterns(skillPath),
-  existing_examples: await findSimilarImplementations(taskType),
-  constraints: state.original_requirements
-};
-
 const prompt = `
-[GROUNDING CONTEXT]
-This skill follows these patterns:
-${JSON.stringify(groundingContext.codebase_patterns)}
-
-Similar implementations exist at:
-${groundingContext.existing_examples.map(e => `- ${e.path}`).join('\n')}
-
-[TASK]
-${taskDescription}
-
-[IMPORTANT]
-- Only suggest patterns that exist in the codebase
-- Reference specific files when making suggestions
-- If unsure, indicate uncertainty level
+Analyze the code. Return ONLY this JSON:
+{ "status": "pass|review|fail", "issues": [{"id","severity","file","line"}], "summary": "one sentence" }
+Do not include explanations.
 `;
 ```
 
-**Risk**: Medium (requires context gathering)
-**Verification**: Check suggestions match existing patterns
-
----
-
-### Architecture Strategies
-
-#### Strategy: phase_decomposition
-
-**Purpose**: 重新划分阶段以清晰化职责。
-
-**Analysis via Gemini**:
-```bash
-ccw cli -p "
-PURPOSE: Analyze phase decomposition for skill at ${skillPath}
-TASK: • Map current phase responsibilities • Identify overlapping concerns • Suggest cleaner boundaries
-MODE: analysis
-CONTEXT: @phases/**/*.md
-EXPECTED: { current_phases: [], overlaps: [], recommended_structure: [] }
-" --tool gemini --mode analysis
-```
-
-**Implementation Pattern**:
-```
-Before: Monolithic phases
-Phase1: Collect + Analyze + Transform + Output
-
-After: Single-responsibility phases
-Phase1: Collect (input gathering)
-Phase2: Analyze (processing)
-Phase3: Transform (conversion)
-Phase4: Output (delivery)
-```
-
----
-
-#### Strategy: interface_contracts
-
-**Purpose**: 定义阶段间的数据契约。
-
-**Implementation**:
-```typescript
-// Define contracts in state-schema.md
-interface PhaseContract {
-  input: {
-    required: string[];
-    optional: string[];
-    schema: object;
-  };
-  output: {
-    guarantees: string[];
-    schema: object;
-  };
-}
-
-// Phase 1 output contract
-const phase1Contract: PhaseContract = {
-  input: {
-    required: ['user_request'],
-    optional: ['preferences'],
-    schema: { /* ... */ }
-  },
-  output: {
-    guarantees: ['parsed_requirements', 'validation_status'],
-    schema: { /* ... */ }
-  }
-};
-```
-
----
-
-### Performance Strategies
-
-#### Strategy: token_budgeting
-
-**Purpose**: 为每个阶段设置 Token 预算。
-
-**Implementation**:
-```javascript
-const TOKEN_BUDGETS = {
-  'phase-collect': 2000,
-  'phase-analyze': 5000,
-  'phase-generate': 8000,
-  total: 15000
-};
-
-function checkBudget(phase, estimatedTokens) {
-  if (estimatedTokens > TOKEN_BUDGETS[phase]) {
-    console.warn(`Phase ${phase} exceeds budget: ${estimatedTokens} > ${TOKEN_BUDGETS[phase]}`);
-    // Trigger summarization or truncation
-    return false;
-  }
-  return true;
-}
-```
-
----
-
-#### Strategy: parallel_execution
-
-**Purpose**: 并行执行独立任务。
-
-**Implementation**:
-```javascript
-// Before: Sequential
-const result1 = await Task({ subagent_type: 'analyzer', prompt: prompt1 });
-const result2 = await Task({ subagent_type: 'analyzer', prompt: prompt2 });
-const result3 = await Task({ subagent_type: 'analyzer', prompt: prompt3 });
-
-// After: Parallel (when independent)
-const [result1, result2, result3] = await Promise.all([
-  Task({ subagent_type: 'analyzer', prompt: prompt1, run_in_background: true }),
-  Task({ subagent_type: 'analyzer', prompt: prompt2, run_in_background: true }),
-  Task({ subagent_type: 'analyzer', prompt: prompt3, run_in_background: true })
-]);
-```
-
----
-
-#### Strategy: result_caching
-
-**Purpose**: 缓存中间结果避免重复计算。
-
-**Implementation**:
-```javascript
-const cache = {};
-
-async function cachedAnalysis(key, analysisFunc) {
-  if (cache[key]) {
-    console.log(`Cache hit: ${key}`);
-    return cache[key];
-  }
-
-  const result = await analysisFunc();
-  cache[key] = result;
-
-  // Persist to disk for cross-session caching
-  Write(`${workDir}/cache/${key}.json`, JSON.stringify(result));
-
-  return result;
-}
-```
-
----
-
-### Error Handling Strategies
-
-#### Strategy: graceful_degradation
-
-**Purpose**: 失败时降级而非崩溃。
-
-**Implementation**:
-```javascript
-async function executeWithDegradation(primaryTask, fallbackTask) {
-  try {
-    return await primaryTask();
-  } catch (error) {
-    console.warn(`Primary task failed: ${error.message}, using fallback`);
-
-    try {
-      return await fallbackTask();
-    } catch (fallbackError) {
-      console.error(`Fallback also failed: ${fallbackError.message}`);
-      return {
-        status: 'degraded',
-        partial_result: null,
-        error: fallbackError.message
-      };
-    }
-  }
-}
-```
-
----
-
-#### Strategy: structured_logging
-
-**Purpose**: 添加结构化日志便于调试。
+### state_field_reduction
 
-**Implementation**:
+Audit checklist:
 ```javascript
-function log(level, action, data) {
-  const entry = {
-    timestamp: new Date().toISOString(),
-    level,
-    action,
-    ...data
-  };
-
-  // Append to log file
-  const logPath = `${workDir}/execution.log`;
-  const existing = Read(logPath) || '';
-  Write(logPath, existing + JSON.stringify(entry) + '\n');
-
-  // Console output
-  console.log(`[${level}] ${action}:`, JSON.stringify(data));
+function auditStateFields(schema) {
+  const candidates = Object.keys(schema).filter(k =>
+    k.startsWith('debug_') || k.endsWith('_cache') ||
+    k.endsWith('_temp') || k.includes('intermediate')
+  );
+  return { total: Object.keys(schema).length, removable: candidates };
 }
-
-// Usage
-log('INFO', 'phase_start', { phase: 'analyze', input_size: 1000 });
-log('ERROR', 'agent_failure', { agent: 'universal-executor', error: err.message });
 ```
 
----
-
-### Output Quality Strategies
+### in_memory_consolidation
 
-#### Strategy: quality_gates
-
-**Purpose**: 输出前进行质量检查。
-
-**Implementation**:
 ```javascript
-const qualityGates = [
-  {
-    name: 'completeness',
-    check: (output) => output.sections?.length >= 3,
-    message: 'Output must have at least 3 sections'
-  },
-  {
-    name: 'format',
-    check: (output) => /^#\s/.test(output.content),
-    message: 'Output must start with markdown heading'
-  },
-  {
-    name: 'length',
-    check: (output) => output.content?.length >= 500,
-    message: 'Output must be at least 500 characters'
-  }
-];
-
-function validateOutput(output) {
-  const failures = qualityGates
-    .filter(gate => !gate.check(output))
-    .map(gate => gate.message);
-
-  if (failures.length > 0) {
-    throw new Error(`Quality gate failures:\n${failures.join('\n')}`);
-  }
-
-  return true;
-}
+// Before: Multiple files — diagnosis-report.md, summary.json, tuning-report.md
+// After: Single state.json with final_report rendered on demand
+const consolidated = { ...state, final_report: { summary, generated_at: Date.now() } };
+Write(`${workDir}/state.json`, JSON.stringify(consolidated, null, 2));
 ```
 
 ---
 
-### User Experience Strategies
-
-#### Strategy: progress_tracking
-
-**Purpose**: 显示执行进度。
-
-**Implementation**:
-```javascript
-function updateProgress(current, total, description) {
-  const percentage = Math.round((current / total) * 100);
-  const progressBar = '█'.repeat(percentage / 5) + '░'.repeat(20 - percentage / 5);
-
-  console.log(`[${progressBar}] ${percentage}% - ${description}`);
-
-  // Update state for UI
-  updateState({
-    progress: {
-      current,
-      total,
-      percentage,
-      description
-    }
-  });
-}
-
-// Usage
-updateProgress(1, 5, 'Initializing tuning session...');
-updateProgress(2, 5, 'Running context diagnosis...');
-```
-
----
-
-#### Strategy: interactive_checkpoints
-
-**Purpose**: 在关键点暂停获取用户确认。
-
-**Implementation**:
-```javascript
-async function checkpoint(name, summary, options) {
-  console.log(`\n=== Checkpoint: ${name} ===`);
-  console.log(summary);
-
-  const response = await AskUserQuestion({
-    questions: [{
-      question: `Review ${name} results. How to proceed?`,
-      header: 'Checkpoint',
-      options: options || [
-        { label: 'Continue', description: 'Proceed with next step' },
-        { label: 'Modify', description: 'Adjust parameters and retry' },
-        { label: 'Skip', description: 'Skip this step' },
-        { label: 'Abort', description: 'Stop the workflow' }
-      ],
-      multiSelect: false
-    }]
-  });
-
-  return response;
-}
-```
-
----
-
-## Token Consumption Strategies
-
-Strategies for reducing token usage and simplifying skill outputs.
-
----
-
-### Strategy: prompt_compression
+## Documentation Strategies
 
-**Purpose**: Reduce verbose prompts by extracting static text and using templates.
+### consolidate_to_ssot
 
-**Implementation**:
 ```javascript
-// Before: Long inline prompt
-const prompt = `
-You are an expert code analyzer specializing in identifying patterns.
-Your role is to examine the provided code and identify any issues.
-Please follow these detailed instructions carefully:
-1. Read the code thoroughly
-2. Identify any anti-patterns
-3. Check for security vulnerabilities
-... (continues for many lines)
-
-Code to analyze:
-${fullCodeContent}
-`;
-
-// After: Compressed with template reference
-const PROMPT_TEMPLATE_PATH = 'templates/analyzer-prompt.md';
-
-const prompt = `
-[TEMPLATE: ${PROMPT_TEMPLATE_PATH}]
-[CODE_PATH: ${codePath}]
-[FOCUS: patterns, security]
-`;
-
-// Or use key instructions only
-const prompt = `
-Analyze ${codePath} for: patterns, security, performance.
-Return JSON: { issues: [], severity: string }
-`;
+// 1. Identify canonical source (priority: specs/ > phases/ > SKILL.md)
+// 2. Ensure canonical has full definition
+// 3. Replace other locations with reference links
+//    e.g., "See [state-schema.md](phases/state-schema.md)"
 ```
 
-**Risk**: Low
-**Verification**: Compare token count before/after compression
-
----
-
-### Strategy: lazy_loading
+### centralize_mapping_config
 
-**Purpose**: Pass file paths instead of full content, let consumers load if needed.
-
-**Implementation**:
 ```javascript
-// Before: Full content in prompt
-const content = Read(filePath);
-const prompt = `Analyze this content:\n${content}`;
-
-// After: Path reference with lazy loading instruction
-const prompt = `
-Analyze file at: ${filePath}
-(Read the file content if you need to examine it)
-Return: { summary: string, issues: [] }
-`;
-
-// For agent calls
-const result = await Task({
-  subagent_type: 'universal-executor',
-  prompt: `
-    [FILE_PATH]: ${dataPath}
-    [TASK]: Analyze the file and extract key metrics.
-    [NOTE]: Read the file only if needed for your analysis.
-  `
-});
+// 1. Extract hardcoded mappings → specs/category-mappings.json
+// 2. Runtime loads config: const map = JSON.parse(Read('specs/category-mappings.json'));
+// 3. Replace all inline definitions with config lookup
 ```
 
-**Risk**: Low
-**Verification**: Verify agents can still access required data
-
----
-
-### Strategy: output_minimization
+### reconcile_conflicting_definitions
 
-**Purpose**: Configure agents to return minimal, structured output instead of verbose text.
-
-**Implementation**:
 ```javascript
-// Before: Verbose output expectation
-const prompt = `
-Analyze the code and provide a detailed report including:
-- Executive summary
-- Detailed findings with explanations
-- Code examples for each issue
-- Recommendations with rationale
-...
-`;
-
-// After: Minimal structured output
-const prompt = `
-Analyze the code. Return ONLY this JSON:
-{
-  "status": "pass|review|fail",
-  "issues": [{ "id": string, "severity": string, "file": string, "line": number }],
-  "summary": "one sentence"
-}
-Do not include explanations or code examples.
-`;
-
-// Validation
-const result = JSON.parse(agentOutput);
-if (!result.status || !Array.isArray(result.issues)) {
-  throw new Error('Invalid output format');
-}
+// 1. Present conflict to user via AskUserQuestion
+// 2. Apply chosen version across all files
+// 3. Verify no remaining conflicts
 ```
 
-**Risk**: Low
-**Verification**: JSON.parse succeeds, output size reduced
-
 ---
 
-### Strategy: state_field_reduction
+## General Optimization Areas (via Gemini CLI)
 
-**Purpose**: Audit and consolidate state fields to minimize serialization overhead.
+For issues in these categories, use Gemini CLI for custom analysis:
 
-**Implementation**:
-```typescript
-// Before: Bloated state
-interface State {
-  status: string;
-  target: TargetInfo;
-  user_input: string;
-  parsed_input: ParsedInput;      // Remove - temporary
-  intermediate_result: any;       // Remove - not persisted
-  debug_info: DebugInfo;          // Remove - debugging only
-  analysis_cache: any;            // Remove - session cache
-  full_history: HistoryEntry[];   // Remove - unbounded
-  step1_output: any;              // Remove - intermediate
-  step2_output: any;              // Remove - intermediate
-  step3_output: any;              // Remove - intermediate
-  final_result: FinalResult;
-  error_log: string[];            // Remove - debugging
-  metrics: Metrics;               // Remove - optional
-}
+| Category | Issues | Gemini Analysis |
+|----------|--------|-----------------|
+| Prompt Engineering | Vague instructions, format drift | prompt optimization, structured output |
+| Architecture | Phase overlap, tight coupling | phase_decomposition, interface_contracts |
+| Performance | Slow execution, high tokens | token_budgeting, parallel_execution |
+| Error Handling | Silent failures, no degradation | graceful_degradation, error_propagation |
+| Output Quality | Inconsistent results | quality_gates, output_validation |
+| User Experience | No progress visibility | progress_tracking, interactive_checkpoints |
 
-// After: Minimal state (≤15 fields)
-interface State {
-  status: 'pending' | 'running' | 'completed' | 'failed';
-  target: { name: string; path: string };
-  input_summary: string;          // Summarized user input
-  result_path: string;            // Path to final result
-  quality_gate: 'pass' | 'fail';
-  error?: string;                 // Only if failed
-}
-```
-
-**Audit Checklist**:
-```javascript
-function auditStateFields(stateSchema) {
-  const removeCandidates = [];
-
-  for (const [key, type] of Object.entries(stateSchema)) {
-    // Identify removal candidates
-    if (key.startsWith('debug_')) removeCandidates.push(key);
-    if (key.endsWith('_cache')) removeCandidates.push(key);
-    if (key.endsWith('_temp')) removeCandidates.push(key);
-    if (key.includes('intermediate')) removeCandidates.push(key);
-    if (key.includes('step') && key.includes('output')) removeCandidates.push(key);
-  }
-
-  return {
-    total_fields: Object.keys(stateSchema).length,
-    remove_candidates: removeCandidates,
-    estimated_reduction: removeCandidates.length
-  };
-}
-```
-
-**Risk**: Medium (ensure no essential data removed)
-**Verification**: State field count ≤ 15, all essential data preserved
-
----
-
-### Strategy: in_memory_consolidation
-
-**Purpose**: Consolidate outputs into single file, eliminate redundant report files.
-
-**Implementation**:
-```javascript
-// Before: Multiple output files
-Write(`${workDir}/diagnosis-report.md`, reportMarkdown);
-Write(`${workDir}/diagnosis-summary.json`, summaryJson);
-Write(`${workDir}/state.json`, JSON.stringify(state));
-Write(`${workDir}/tuning-report.md`, tuningReport);
-Write(`${workDir}/tuning-summary.md`, finalSummary);
-
-// After: Single source of truth
-const consolidatedState = {
-  ...state,
-  final_report: {
-    summary: summaryJson,
-    details_available_in_state: true,
-    generated_at: new Date().toISOString()
-  }
-};
-Write(`${workDir}/state.json`, JSON.stringify(consolidatedState, null, 2));
-
-// Report can be rendered from state on-demand
-function renderReport(state) {
-  return `
-# Tuning Report: ${state.target_skill.name}
-Status: ${state.status}
-Quality: ${state.quality_gate}
-Issues: ${state.issues.length}
-...
-`;
-}
+**Gemini CLI Template**:
+```bash
+ccw cli -p "
+PURPOSE: [optimization goal for skill at ${skillPath}]
+TASK: • [specific analysis steps]
+MODE: analysis
+CONTEXT: @${skillPath}/**/*
+EXPECTED: [specific deliverable]
+" --tool gemini --mode analysis
 ```
-
-**Benefits**:
-- Single file to read/write
-- No data duplication
-- On-demand rendering
-
-**Risk**: Low
-**Verification**: Only state.json exists as output, rendering works correctly