skill-tuning

スキルのチューニング

スキル実行時の問題を自律的に診断し、最適化します。

アーキテクチャ

┌─────────────────────────────────────────────────────┐
│  Phase 0: Read Specs (mandatory)                    │
│  → problem-taxonomy.md, tuning-strategies.md         │
└─────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────┐
│  Orchestrator (state-driven)                         │
│  Read state → Select action → Execute → Update → ✓ │
└─────────────────────────────────────────────────────┘
        ↓                           ↓
┌──────────────────────┐   ┌──────────────────┐
│  Diagnosis Phase     │   │ Gemini CLI       │
│  • Context          │   │ Deep analysis    │
│  • Memory           │   │ (on-demand)      │
│  • DataFlow         │   │                  │
│  • Agent            │   │ Complex issues   │
│  • Docs             │   │ Architecture     │
│  • Token Usage      │   │ Performance      │
└──────────────────────┘   └──────────────────┘
                ↓
        ┌───────────────────┐
        │  Fix & Verify     │
        │  Apply → Re-test  │
        └───────────────────┘

検出された主な問題

優先度	問題	根本原因	修正方針
P0	作成時の違反	中間ファイル、状態の肥大化、ファイルの受け渡し	eliminate_intermediate、minimize_state
P1	データフローの中断	状態の分散、一貫性のない形式	state_centralization、schema_enforcement
P2	エージェントの連携	脆弱なチェーン、エラー処理の欠如	error_wrapping、result_validation
P3	コンテキストの爆発	上限のない履歴、コンテンツ全体の受け渡し	sliding_window、path_reference
P4	長期的な忘却	初期制約の喪失	constraint_injection、checkpoint_restore
P5	トークン消費	冗長なプロンプト、状態の肥大化	prompt_compression、lazy_loading

問題カテゴリ（詳細仕様）

specs/problem-taxonomy.md を参照してください。

• 検出パターン（正規表現／チェック）
• 重大度の計算
• 影響の評価

チューニング戦略（詳細仕様）

specs/tuning-strategies.md を参照してください。

• カテゴリごとに10以上の戦略
• 実装パターン
• 検証方法

ワークフロー

ステップ	アクション	オーケストレーターの判断	出力
1	action-init	status='pending'	バックアップ、セッションの作成
2	action-analyze-requirements	初期化後	必須の観点とカバレッジ
3	診断（6種類）	注力領域	state.diagnosis.{type}
4	action-gemini-analysis	重大な問題、またはユーザーのリクエスト	詳細な検出結果
5	action-generate-report	すべての診断が完了	state.final_report
6	action-propose-fixes	問題が見つかった場合	state.proposed_fixes[]
7	action-apply-fix	保留中の修正	適用・検証済み
8	action-complete	品質ゲートを通過	session.status='completed'

アクションリファレンス

カテゴリ	アクション	目的
セットアップ	action-init	バックアップとセッション状態を初期化
分析	action-analyze-requirements	Gemini CLI を使ってユーザーリクエストを分解
診断	action-diagnose-{context,memory,dataflow,agent,docs,token_consumption}	カテゴリ固有の問題を検出
詳細分析	action-gemini-analysis	Gemini CLI：複雑な問題や重大な問題を分析
レポート	action-generate-report	検出結果を統合 → final_report
修正	action-propose-fixes, action-apply-fix	修正を生成・適用
検証	action-verify	診断を再実行し、ゲートを確認
終了	action-complete, action-abort	完了またはロールバック

アクションの詳細：phases/actions/

状態管理

信頼できる唯一の情報源：.workflow/.scratchpad/skill-tuning-{ts}/state.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": "..."
}

完全なスキーマはphases/state-schema.mdを参照してください。

オーケストレーターのロジック

以下についてはphases/orchestrator.mdを参照してください。

• 判断ロジック（終了チェック → アクション選択）
• 状態遷移
• エラー復旧

主な原則

1. 問題優先：修正の前に診断します
2. データ駆動：トレース、トークン数、スナップショットを記録します
3. 反復的：品質ゲートを通過するまで複数回実行します
4. 可逆的：すべての変更にバックアップチェックポイントを設けます
5. 非侵襲的：変更を最小限に抑え、明確さを最大限に高めます

使用例

# Basic skill diagnosis
/skill-tuning "Fix memory leaks in my skill"

# Deep analysis with Gemini
/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"

出力

完了後、以下を確認してください。

• .workflow/.scratchpad/skill-tuning-{ts}/state.json - final_report を含む完全な状態
• state.final_report - Markdown の概要（state.json 内）
• state.applied_fixes - 検証結果付きの適用済み修正一覧

Reference Documents

Document	Purpose
specs/problem-taxonomy.md	Classification + detection patterns
specs/tuning-strategies.md	Fix implementation guide
specs/dimension-mapping.md	Dimension ↔ Spec mapping
specs/quality-gates.md	Quality verification criteria
phases/orchestrator.md	Workflow orchestration
phases/state-schema.md	State structure definition
phases/actions/	Individual action implementations