pi-maestro-flow 0.2.0

package/skills/skill-iter-tune/SKILL.md

@@ -0,0 +1,382 @@
+---
+name: skill-iter-tune
+description: "Iterative skill tuning via execute-evaluate-improve feedback loop. Uses maestro delegate Claude to execute skill, Agy to evaluate quality, and Agent to apply improvements. Iterates until quality threshold or max iterations. Triggers on \"skill iter tune\", \"iterative skill tuning\", \"tune skill\"."
+allowed-tools: Skill Agent AskUserQuestion TaskCreate TaskUpdate TaskList Read Write Edit Bash Glob Grep
+---
+
+# Skill Iter Tune
+
+Iterative skill refinement through execute-evaluate-improve feedback loops. Each iteration runs the skill via Claude, evaluates output via Agy, and applies improvements via Agent.
+
+## Architecture Overview
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│  Skill Iter Tune Orchestrator (SKILL.md)                                 │
+│  → Parse input → Setup workspace → Iteration Loop → Final Report         │
+└────────────────────────────┬─────────────────────────────────────────────┘
+                             │
+         ┌───────────────────┼───────────────────────────────────┐
+         ↓                   ↓                                   ↓
+    ┌──────────┐      ┌─────────────────────────────┐     ┌──────────┐
+    │ Phase 1  │      │  Iteration Loop (2→3→4)     │     │ Phase 5  │
+    │ Setup    │      │  ┌─────┐  ┌─────┐  ┌─────┐ │     │ Report   │
+    │          │─────→│  │ P2  │→ │ P3  │→ │ P4  │ │────→│          │
+    │ Backup + │      │  │Exec │  │Eval │  │Impr │ │     │ History  │
+    │ Init     │      │  └─────┘  └─────┘  └─────┘ │     │ Summary  │
+    └──────────┘      │       ↑               │     │     └──────────┘
+                      │       └───────────────┘     │
+                      │    (if score < threshold    │
+                      │     AND iter < max)         │
+                      └─────────────────────────────┘
+```
+
+### Chain Mode Extension
+
+```
+Chain Mode (execution_mode === "chain"):
+
+Phase 2 runs per-skill in chain_order:
+  Skill A → maestro delegate → artifacts/skill-A/
+       ↓ (artifacts as input)
+  Skill B → maestro delegate → artifacts/skill-B/
+       ↓ (artifacts as input)
+  Skill C → maestro delegate → artifacts/skill-C/
+
+Phase 3 evaluates entire chain output + per-skill scores
+Phase 4 improves weakest skill(s) in chain
+```
+
+## Key Design Principles
+
+1. **Iteration Loop**: Phases 2-3-4 repeat until quality threshold, max iterations, or convergence
+2. **Two-Tool Pipeline**: Claude (write/execute) + Agy (analyze/evaluate) = complementary perspectives
+3. **Pure Orchestrator**: SKILL.md coordinates only — execution detail lives in phase files
+4. **Progressive Phase Loading**: Phase docs read only when that phase executes
+5. **Skill Versioning**: Each iteration snapshots skill state before execution
+6. **Convergence Detection**: Stop early if score stalls (no improvement in 2 consecutive iterations)
+
+## Interactive Preference Collection
+
+```javascript
+// ★ Auto mode detection
+const autoYes = /\b(-y|--yes)\b/.test($ARGUMENTS)
+
+if (autoYes) {
+  workflowPreferences = {
+    autoYes: true,
+    maxIterations: 5,
+    qualityThreshold: 80,
+    executionMode: 'single'
+  }
+} else {
+  const prefResponse = AskUserQuestion({
+    questions: [
+      {
+        question: "选择迭代调优配置：",
+        header: "Tune Config",
+        multiSelect: false,
+        options: [
+          { label: "Quick (3 iter, 70)", description: "快速迭代，适合小幅改进" },
+          { label: "Standard (5 iter, 80) (Recommended)", description: "平衡方案，适合多数场景" },
+          { label: "Thorough (8 iter, 90)", description: "深度优化，适合生产级 skill" }
+        ]
+      }
+    ]
+  })
+
+  const configMap = {
+    "Quick": { maxIterations: 3, qualityThreshold: 70 },
+    "Standard": { maxIterations: 5, qualityThreshold: 80 },
+    "Thorough": { maxIterations: 8, qualityThreshold: 90 }
+  }
+  const selected = Object.keys(configMap).find(k =>
+    prefResponse["Tune Config"].startsWith(k)
+  ) || "Standard"
+  workflowPreferences = { autoYes: false, ...configMap[selected] }
+
+  // ★ Mode selection: chain vs single
+  const modeResponse = AskUserQuestion({
+    questions: [{
+      question: "选择调优模式：",
+      header: "Tune Mode",
+      multiSelect: false,
+      options: [
+        { label: "Single Skill (Recommended)", description: "独立调优每个 skill，适合单一 skill 优化" },
+        { label: "Skill Chain", description: "按链序执行，前一个 skill 的产出作为后一个的输入" }
+      ]
+    }]
+  });
+  workflowPreferences.executionMode = modeResponse["Tune Mode"].startsWith("Skill Chain")
+    ? "chain" : "single";
+}
+```
+
+## Input Processing
+
+```
+$ARGUMENTS → Parse:
+  ├─ Skill path(s): first arg, comma-separated for multiple
+  │   e.g., ".claude/skills/my-skill" or "my-skill" (auto-prefixed)
+  │   Chain mode: order preserved as chain_order
+  ├─ Test scenario: --scenario "description" or remaining text
+  └─ Flags: --max-iterations=N, --threshold=N, -y/--yes
+```
+
+## Execution Flow
+
+> **⚠️ COMPACT DIRECTIVE**: Context compression MUST check TodoWrite phase status.
+> The phase currently marked `in_progress` is the active execution phase — preserve its FULL content.
+> Only compress phases marked `completed` or `pending`.
+
+### Phase 1: Setup (one-time)
+
+Read and execute: `Ref: phases/01-setup.md`
+
+- Parse skill paths, validate existence
+- Create workspace at `.workflow/.scratchpad/skill-iter-tune-{ts}/`
+- Backup original skill files
+- Initialize iteration-state.json
+
+Output: `workDir`, `targetSkills[]`, `testScenario`, initialized state
+
+### Iteration Loop
+
+```javascript
+// Orchestrator iteration loop
+while (true) {
+  // Increment iteration
+  state.current_iteration++;
+  state.iterations.push({
+    round: state.current_iteration,
+    status: 'pending',
+    execution: null,
+    evaluation: null,
+    improvement: null
+  });
+
+  // Update TodoWrite
+  TaskUpdate(iterationTask, {
+    subject: `Iteration ${state.current_iteration}/${state.max_iterations}`,
+    status: 'in_progress',
+    activeForm: `Running iteration ${state.current_iteration}`
+  });
+
+  // === Phase 2: Execute ===
+  // Read: phases/02-execute.md
+  // Single mode: one maestro delegate call for all skills
+  // Chain mode: sequential maestro delegate per skill in chain_order, passing artifacts
+  // Snapshot skill → construct prompt → maestro delegate --to claude --mode write
+  // Collect artifacts
+
+  // === Phase 3: Evaluate ===
+  // Read: phases/03-evaluate.md
+  // Construct eval prompt → maestro delegate --to agy --mode analysis
+  // Parse score → write iteration-N-eval.md → check termination
+
+  // Check termination
+  if (shouldTerminate(state)) {
+    break;  // → Phase 5
+  }
+
+  // === Phase 4: Improve ===
+  // Read: phases/04-improve.md
+  // Agent applies suggestions → write iteration-N-changes.md
+
+  // Update TodoWrite with score
+  // Continue loop
+}
+```
+
+### Phase 2: Execute Skill (per iteration)
+
+Read and execute: `Ref: phases/02-execute.md`
+
+- Snapshot skill → `iteration-{N}/skill-snapshot/`
+- Build execution prompt from skill content + test scenario
+- Execute: `maestro delegate "..." --to claude --mode write --cd "${iterDir}/artifacts"`
+- Collect artifacts
+
+### Phase 3: Evaluate Quality (per iteration)
+
+Read and execute: `Ref: phases/03-evaluate.md`
+
+- Build evaluation prompt with skill + artifacts + criteria + history
+- Execute: `maestro delegate "..." --to agy --mode analysis`
+- Parse 5-dimension score (Clarity, Completeness, Correctness, Effectiveness, Efficiency)
+- Write `iteration-{N}-eval.md`
+- Check termination: score >= threshold | iter >= max | convergence | error limit
+
+### Phase 4: Apply Improvements (per iteration, skipped on termination)
+
+Read and execute: `Ref: phases/04-improve.md`
+
+- Read evaluation suggestions
+- Launch general-purpose Agent to apply changes
+- Write `iteration-{N}-changes.md`
+- Update state
+
+### Phase 5: Final Report (one-time)
+
+Read and execute: `Ref: phases/05-report.md`
+
+- Generate comprehensive report with score progression table
+- Write `final-report.md`
+- Display summary to user
+
+**Phase Reference Documents** (read on-demand when phase executes):
+
+| Phase | Document | Purpose | Compact |
+|-------|----------|---------|---------|
+| 1 | [phases/01-setup.md](phases/01-setup.md) | Initialize workspace and state | TodoWrite 驱动 |
+| 2 | [phases/02-execute.md](phases/02-execute.md) | Execute skill via maestro delegate Claude | TodoWrite 驱动 + 🔄 sentinel |
+| 3 | [phases/03-evaluate.md](phases/03-evaluate.md) | Evaluate via maestro delegate Agy | TodoWrite 驱动 + 🔄 sentinel |
+| 4 | [phases/04-improve.md](phases/04-improve.md) | Apply improvements via Agent | TodoWrite 驱动 + 🔄 sentinel |
+| 5 | [phases/05-report.md](phases/05-report.md) | Generate final report | TodoWrite 驱动 |
+
+**Compact Rules**:
+1. **TodoWrite `in_progress`** → 保留完整内容，禁止压缩
+2. **TodoWrite `completed`** → 可压缩为摘要
+3. **🔄 sentinel fallback** → 若 compact 后仅存 sentinel 而无完整 Step 协议，立即 `Read()` 恢复
+
+## Core Rules
+
+1. **Start Immediately**: First action is preference collection → Phase 1 setup
+2. **Progressive Loading**: Read phase doc ONLY when that phase is about to execute
+3. **Snapshot Before Execute**: Always snapshot skill state before each iteration
+4. **Background CLI**: maestro delegate runs in background, wait for hook callback before proceeding
+5. **Parse Every Output**: Extract structured JSON from CLI outputs for state updates
+6. **DO NOT STOP**: Continuous iteration until termination condition met
+7. **Single State Source**: `iteration-state.json` is the only source of truth
+
+## Data Flow
+
+```
+User Input (skill paths + test scenario)
+    ↓ (+ execution_mode + chain_order if chain mode)
+    ↓
+Phase 1: Setup
+    ↓ workDir, targetSkills[], testScenario, iteration-state.json
+    ↓
+┌─→ Phase 2: Execute (maestro delegate claude)
+│   ↓ artifacts/ (skill execution output)
+│   ↓
+│   Phase 3: Evaluate (maestro delegate agy)
+│   ↓ score, dimensions[], suggestions[], iteration-N-eval.md
+│   ↓
+│   [Terminate?]─── YES ──→ Phase 5: Report → final-report.md
+│   ↓ NO
+│   ↓
+│   Phase 4: Improve (Agent)
+│   ↓ modified skill files, iteration-N-changes.md
+│   ↓
+└───┘ next iteration
+```
+
+## TodoWrite Pattern
+
+```javascript
+// Initial state
+TaskCreate({ subject: "Phase 1: Setup workspace", activeForm: "Setting up workspace" })
+TaskCreate({ subject: "Iteration Loop", activeForm: "Running iterations" })
+TaskCreate({ subject: "Phase 5: Final Report", activeForm: "Generating report" })
+
+// Chain mode: create per-skill tracking tasks
+if (state.execution_mode === 'chain') {
+  for (const skillName of state.chain_order) {
+    TaskCreate({
+      subject: `Chain: ${skillName}`,
+      activeForm: `Tracking ${skillName}`,
+      description: `Skill chain member position ${state.chain_order.indexOf(skillName) + 1}`
+    })
+  }
+}
+
+// During iteration N
+// Single mode: one score per iteration (existing behavior)
+// Chain mode: per-skill status updates
+if (state.execution_mode === 'chain') {
+  // After each skill executes in Phase 2:
+  TaskUpdate(chainSkillTask, {
+    subject: `Chain: ${skillName} — Iter ${N} executed`,
+    activeForm: `${skillName} iteration ${N}`
+  })
+  // After Phase 3 evaluates:
+  TaskUpdate(chainSkillTask, {
+    subject: `Chain: ${skillName} — Score ${chainScores[skillName]}/100`,
+    activeForm: `${skillName} scored`
+  })
+} else {
+  // Single mode (existing)
+  TaskCreate({
+    subject: `Iteration ${N}: Score ${score}/100`,
+    activeForm: `Iteration ${N} complete`,
+    description: `Strengths: ... | Weaknesses: ... | Suggestions: ${count}`
+  })
+}
+
+// Completed — collapse
+TaskUpdate(iterLoop, {
+  subject: `Iteration Loop (${totalIters} iters, final: ${finalScore})`,
+  status: 'completed'
+})
+```
+
+## Termination Logic
+
+```javascript
+function shouldTerminate(state) {
+  // 1. Quality threshold met
+  if (state.latest_score >= state.quality_threshold) {
+    return { terminate: true, reason: 'quality_threshold_met' };
+  }
+  // 2. Max iterations reached
+  if (state.current_iteration >= state.max_iterations) {
+    return { terminate: true, reason: 'max_iterations_reached' };
+  }
+  // 3. Convergence: ≤2 points improvement over last 2 iterations
+  if (state.score_trend.length >= 3) {
+    const last3 = state.score_trend.slice(-3);
+    if (last3[2] - last3[0] <= 2) {
+      state.converged = true;
+      return { terminate: true, reason: 'convergence_detected' };
+    }
+  }
+  // 4. Error limit
+  if (state.error_count >= state.max_errors) {
+    return { terminate: true, reason: 'error_limit_reached' };
+  }
+  return { terminate: false };
+}
+```
+
+## Error Handling
+
+| Phase | Error | Recovery |
+|-------|-------|----------|
+| 2: Execute | CLI timeout/crash | Retry once with simplified prompt, then skip |
+| 3: Evaluate | CLI fails | Retry once, then use score 50 with warning |
+| 3: Evaluate | JSON parse fails | Extract score heuristically, save raw output |
+| 4: Improve | Agent fails | Rollback from `iteration-{N}/skill-snapshot/` |
+| Any | 3+ consecutive errors | Terminate with error report |
+
+**Error Budget**: Each phase gets 1 retry. 3 consecutive failed iterations triggers termination.
+
+## Coordinator Checklist
+
+### Pre-Phase Actions
+- [ ] Read iteration-state.json for current state
+- [ ] Verify workspace directory exists
+- [ ] Check error count hasn't exceeded limit
+
+### Per-Iteration Actions
+- [ ] Increment current_iteration in state
+- [ ] Create iteration-{N} subdirectory
+- [ ] Update TodoWrite with iteration status
+- [ ] After Phase 3: check termination before Phase 4
+- [ ] After Phase 4: write state, proceed to next iteration
+
+### Post-Workflow Actions
+- [ ] Execute Phase 5 (Report)
+- [ ] Display final summary to user
+- [ ] Update all TodoWrite tasks to completed

package/skills/skill-simplify/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: skill-simplify
+description: "SKILL.md simplification with functional integrity verification. Analyze redundancy, optimize content, check no functionality lost. Triggers on \"simplify skill\", \"optimize skill\", \"skill-simplify\"."
+allowed-tools: AskUserQuestion Read Write Edit Bash Glob Grep
+---
+
+# Skill Simplify
+
+Three-phase pipeline: analyze functional inventory, apply optimization rules, verify integrity.
+
+**Phase Reference Documents** (read on-demand):
+
+| Phase | Document | Purpose |
+|-------|----------|---------|
+| 1 | [phases/01-analysis.md](phases/01-analysis.md) | Extract functional inventory, identify redundancy, validate pseudo-code format |
+| 2 | [phases/02-optimize.md](phases/02-optimize.md) | Apply simplification rules, fix format issues |
+| 3 | [phases/03-check.md](phases/03-check.md) | Verify functional integrity, validate format |
+
+## Pre-load (before execution)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for project context
+2. **Specs**: `maestro load --type spec --category coding` — load coding conventions
+3. **Wiki knowledge**: `maestro search "skill design optimization" --json` — top 5 entries as prior context
+4. All optional — proceed without if unavailable
+
+## Input Processing
+
+```javascript
+const targetPath = input.trim()
+const targetFile = targetPath.endsWith('.md') ? targetPath : `${targetPath}/SKILL.md`
+const originalContent = Read(targetFile)
+const originalLineCount = originalContent.split('\n').length
+```
+
+## TodoWrite Pattern
+
+```javascript
+TodoWrite({ todos: [
+  { content: `Phase 1: Analyzing ${targetFile}`, status: "in_progress", activeForm: "Extracting functional inventory" },
+  { content: "Phase 2: Optimize", status: "pending" },
+  { content: "Phase 3: Integrity Check", status: "pending" }
+]})
+```
+
+## Core Rules
+
+1. **Preserve ALL functional elements**: Code blocks with logic, agent calls, data structures, routing, error handling, input/output specs
+2. **Only reduce descriptive content**: Flowcharts, verbose comments, duplicate sections, examples that repeat logic
+3. **Never summarize algorithm logic**: If-else branches, function bodies, schemas must remain verbatim
+4. **Classify code blocks**: Distinguish `functional` (logic, routing, schemas) from `descriptive` (ASCII art, examples, display templates) — only descriptive blocks may be deleted
+5. **Merge equivalent variants**: Single/multi-perspective templates differing only by a parameter → one template with variant comment
+6. **Fix format issues**: Nested backtick template literals in code fences → convert to prose; hardcoded option lists → flag for dynamic generation; workflow handoff references → ensure execution steps present
+7. **Validate pseudo-code**: Check bracket matching, variable consistency, structural completeness
+8. **Quantitative verification**: Phase 3 counts must match Phase 1 counts for functional categories; descriptive block decreases are expected
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Target file not found | Report error, stop |
+| Check FAIL (missing functional elements) | Show delta, revert to original, report which elements lost |
+| Check WARN (descriptive decrease or merge) | Show delta with justification |
+| Format issues found | Report in check, fix in Phase 2 |

package/skills/skill-tuning/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: skill-tuning
+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 Agy 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
+---
+
+# Skill Tuning
+
+Autonomous diagnosis and optimization for skill execution issues.
+
+## Pre-load (before execution)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for project context
+2. **Specs**: `maestro load --type spec --category coding` — load coding conventions
+3. **Wiki knowledge**: `maestro search "skill design optimization" --json` — top 5 entries as prior context
+4. All optional — proceed without if unavailable
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Phase 0: Read Specs (mandatory)                    │
+│  → problem-taxonomy.md, tuning-strategies.md         │
+└─────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────┐
+│  Orchestrator (state-driven)                         │
+│  Read state → Select action → Execute → Update → ✓ │
+└─────────────────────────────────────────────────────┘
+        ↓                           ↓
+┌──────────────────────┐   ┌──────────────────┐
+│  Diagnosis Phase     │   │ Agy CLI       │
+│  • Context          │   │ Deep analysis    │
+│  • Memory           │   │ (on-demand)      │
+│  • DataFlow         │   │                  │
+│  • Agent            │   │ Complex issues   │
+│  • Docs             │   │ Architecture     │
+│  • Token Usage      │   │ Performance      │
+└──────────────────────┘   └──────────────────┘
+                ↓
+        ┌───────────────────┐
+        │  Fix & Verify     │
+        │  Apply → Re-test  │
+        └───────────────────┘
+```
+
+## 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 content passing | sliding_window, path_reference |
+| **P4** | Long-tail Forgetting | Early constraint loss | constraint_injection, checkpoint_restore |
+| **P5** | Token Consumption | Verbose prompts, state bloat | prompt_compression, lazy_loading |
+
+## Problem Categories (Detailed Specs)
+
+See [specs/problem-taxonomy.md](specs/problem-taxonomy.md) for:
+- Detection patterns (regex/checks)
+- Severity calculations
+- Impact assessments
+
+## Tuning Strategies (Detailed Specs)
+
+See [specs/tuning-strategies.md](specs/tuning-strategies.md) for:
+- 10+ strategies per category
+- Implementation patterns
+- Verification methods
+
+## Workflow
+
+| Step | Action | Orchestrator Decision | Output |
+|------|--------|----------------------|--------|
+| 1 | `action-init` | status='pending' | Backup, session created |
+| 2 | `action-analyze-requirements` | After init | Required dimensions + coverage |
+| 3 | Diagnosis (6 types) | Focus areas | state.diagnosis.{type} |
+| 4 | `action-agy-analysis` | Critical issues OR user request | Deep findings |
+| 5 | `action-generate-report` | All diagnosis complete | state.final_report |
+| 6 | `action-propose-fixes` | Issues found | state.proposed_fixes[] |
+| 7 | `action-apply-fix` | Pending fixes | Applied + verified |
+| 8 | `action-complete` | Quality gates pass | session.status='completed' |
+
+## Action Reference
+
+| Category | Actions | Purpose |
+|----------|---------|---------|
+| **Setup** | action-init | Initialize backup, session state |
+| **Analysis** | action-analyze-requirements | Decompose user request via Agy CLI |
+| **Diagnosis** | action-diagnose-{context,memory,dataflow,agent,docs,token_consumption} | Detect category-specific issues |
+| **Deep Analysis** | action-agy-analysis | Agy CLI: complex/critical issues |
+| **Reporting** | action-generate-report | Consolidate findings → final_report |
+| **Fixing** | action-propose-fixes, action-apply-fix | Generate + apply fixes |
+| **Verify** | action-verify | Re-run diagnosis, check gates |
+| **Exit** | action-complete, action-abort | Finalize or rollback |
+
+Full action details: [phases/actions/](phases/actions/)
+
+## State Management
+
+**Single source of truth**: `.workflow/.scratchpad/skill-tuning-{ts}/state.json`
+
+```json
+{
+  "status": "pending|running|completed|failed",
+  "target_skill": { "name": "...", "path": "..." },
+  "diagnosis": {
+    "context": {...},
+    "memory": {...},
+    "dataflow": {...},
+    "agent": {...},
+    "docs": {...},
+    "token_consumption": {...}
+  },
+  "issues": [{"id":"...", "severity":"...", "category":"...", "strategy":"..."}],
+  "proposed_fixes": [...],
+  "applied_fixes": [...],
+  "quality_gate": "pass|fail",
+  "final_report": "..."
+}
+```
+
+See [phases/state-schema.md](phases/state-schema.md) for complete schema.
+
+## Orchestrator Logic
+
+See [phases/orchestrator.md](phases/orchestrator.md) for:
+- Decision logic (termination checks → action selection)
+- State transitions
+- Error recovery
+
+## Key Principles
+
+1. **Problem-First**: Diagnosis before any fix
+2. **Data-Driven**: Record traces, token counts, snapshots
+3. **Iterative**: Multiple rounds until quality gates pass
+4. **Reversible**: All changes with backup checkpoints
+5. **Non-Invasive**: Minimal changes, maximum clarity
+
+## Usage Examples
+
+```bash
+# Basic skill diagnosis
+/skill-tuning "Fix memory leaks in my skill"
+
+# Deep analysis with Agy
+/skill-tuning "Architecture issues in async workflow"
+
+# Focus on specific areas
+/skill-tuning "Optimize token consumption and fix agent coordination"
+
+# Custom issue
+/skill-tuning "My skill produces inconsistent outputs"
+```
+
+## Output
+
+After completion, review:
+- `.workflow/.scratchpad/skill-tuning-{ts}/state.json` - Full state with final_report
+- `state.final_report` - Markdown summary (in state.json)
+- `state.applied_fixes` - List of applied fixes with verification results
+
+## Reference Documents
+
+| Document | Purpose |
+|----------|---------|
+| [specs/problem-taxonomy.md](specs/problem-taxonomy.md) | Classification + detection patterns |
+| [specs/tuning-strategies.md](specs/tuning-strategies.md) | Fix implementation guide |
+| [specs/dimension-mapping.md](specs/dimension-mapping.md) | Dimension ↔ Spec mapping |
+| [specs/quality-gates.md](specs/quality-gates.md) | Quality verification criteria |
+| [phases/orchestrator.md](phases/orchestrator.md) | Workflow orchestration |
+| [phases/state-schema.md](phases/state-schema.md) | State structure definition |
+| [phases/actions/](phases/actions/) | Individual action implementations |