workflow-improvement

ワークフローの改善

使用するタイミング

コマンドを実行した後、または短いセッションを終えた後に、実行が遅い、分かりにくい、反復的、あるいは不安定だと感じた場合に、このスキルを使用してください。

このスキルでは、機能そのものではなく、関与したワークフロー資産（スキル、エージェント、コマンド、フック）の改善に重点を置きます。

使用しないタイミング

• 機能を実装する場合 — まず機能の開発に集中してください

必須の進捗項目

1. fix-workflow:context-gathered
2. fix-workflow:slice-captured
3. fix-workflow:workflow-recreated
4. fix-workflow:improvements-generated
5. fix-workflow:plan-agreed
6. fix-workflow:changes-implemented
7. fix-workflow:validated
8. fix-workflow:lesson-stored

ステップ 0：改善のコンテキストを収集する（context-gathered）

現在のセッションを分析する前に、既存の改善データを収集します。

0.1：スキル実行履歴を確認する

最近のパフォーマンス上の問題について、memory-palace のログを照会します。

# Recent failures (last 7 days)
/skill-logs --failures-only --last 7d

# Performance metrics for involved plugins
pensive:skill-review --plugin sanctum --recommendations

記録する内容：

• stability_gap > 0.3 のスキル
• 最近の失敗パターンとエラーメッセージ
• パフォーマンス低下の傾向

0.2：ナレッジベースを照会する

以前に記録されたワークフローの教訓を検索します。

# If memory-palace review-chamber is available
/review-room search "workflow improvement" --room lessons
/review-room search "efficiency" --room patterns

確認する内容：

• 過去の PR における類似のワークフローの問題
• ワークフローの失敗における反復パターン
• ワークフローに影響するアーキテクチャ上の決定

0.3：Git 履歴を確認する

コミットのパターンから、繰り返し発生する問題を特定します。

git log --oneline --grep="improve\|fix\|optimize" --since="30 days ago" \
  -- plugins/sanctum/skills/ plugins/sanctum/commands/

# Look for unstable components (frequent fixes)
git log --oneline --since="30 days ago" --follow \
  -- plugins/sanctum/skills/workflow-improvement/

抽出する内容：

• バグ修正が頻繁なコンポーネント（不安定さの兆候）
• 改善に関するコミットメッセージのパターン
• 繰り返し発生する問題の傾向

出力形式：

## Improvement Context

### Skill Performance Issues
- sanctum:workflow-improvement: stability_gap 0.35 (5 failures in 7 days)
- Error pattern: "Missing validation in Step 2"

### Knowledge Base Lessons
- PR #42 lesson: "Workflow validation should happen at start, not end"
- Pattern: Early validation reduces iteration time by 30%

### Git History Insights
- workflow-improvement skill: 8 commits in 30 days (instability signal)
- Recurring theme: "Add missing prerequisite checks"

ステップ 1：セッションの一区切りを記録する（slice-captured）

現在のコンテキストウィンドウ内で最も直近のコマンドまたはセッションの一区切りを特定し、以下を記録します。

• きっかけ：それを開始したコマンド／リクエスト（該当する場合はリテラルの /command を含める）
• 目標：ユーザーにとって何をもって「完了」とするか
• 変更した成果物：スキル、エージェント、コマンド、フック（名称とファイルパス）
• 根拠：非効率さを示す重要なツール呼び出し／エラー／再試行
• ステップ 0 のコンテキスト：改善のコンテキストから関連するパターンを参照する

一区切りが曖昧な場合は、最も直近の完了した試行を選び、選択した正確な範囲を明記します。

ステップ 2：ワークフローを再構成する（workflow-recreated）

ワークフローを 5～20 個の手順からなる番号付きリストとして再構成し、入力、判断の分岐点、ファイルの変更や状態の更新などの出力を特定します。この再構成の際に、効率を低下させる具体的な摩擦点を特定します。こうした問題には、手順の繰り返しや冗長なツール呼び出しのほか、検証が遅すぎる、前提条件が不明確であるなど、ガードレールの不足がよく見られます。スクリプト化すべきタスクが自動化されていないことや、命名規則が分かりにくいことによる発見性の不足も、よくある問題です。

ステップ 0 のコンテキストと照合する：

• 摩擦点は既知の失敗パターンと一致していますか？
• 手順の繰り返しは Git 履歴の傾向と一致していますか？
• 不足しているガードレールについて、review-chamber の教訓で言及されていますか？

ステップ 3：改善案を作成する（improvements-generated）

異なる改善案を 3～5 個作成し、それぞれについて影響度、複雑さ、可逆性、既存の sanctum パターンとの一貫性を評価します。評価では、その変更によってステップ 0 で特定したパターンの再発を防げるかどうかを明確に取り上げます。stability gap が高い（0.3 超）コンポーネントや、Git 履歴で繰り返し見つかった問題に対処する改善案を優先します。また、review-chamber の教訓を取り入れ、スキルログで特定された失敗要因の削減を目指します。スキルの終了条件の厳格化、不足しているコマンドオプションの追加、可観測性を高めるフックのガードレール改善、過剰な機能を抱えたコマンドをより明確な段階に分割するなど、小規模で使用頻度の高い変更を優先してください。

ステップ 4：計画に合意する（plan-agreed）

アプローチを 1 つ選び、以下を定義します。

• 受け入れ基準（「実質的な違い」）
• 変更するファイル
• 実行する検証コマンド
• 対象外として先送りする項目

計画の範囲を限定します。ワークフローが実際にそれ以上のファイルにまたがる場合を除き、変更するファイルは 5 件以下を目指してください。

ステップ 5：実装する（changes-implemented）

sanctum の規約に従って変更を適用します。

• commands/、agents/、skills/、hooks/ 間で一貫した命名を保ちます
• 主な問題が曖昧さである場合は、ドキュメントを優先して改善します
• 動作を変更する場合は、plugins/sanctum/tests/ のテストを追加または調整します

ステップ 6：実質的な改善を検証する（validated）

検証には、以下のうち少なくとも 2 つを含めます。

• プラグインバリデーター／ユニットテストの合格（対象を絞ったもの）
• 最小限のワークフロー再現を再実行し、手順数または手作業を削減
• 障害モードの明確な削減（例：早期検証、選択肢の明確化）

変更前後の比較は、文章ではなくメトリクスとして記録します。

• 手順数の削減
• ツール呼び出し数の削減
• 回避できたエラー（変更前なら何が失敗していたか）
• 所要時間の改善（測定可能な場合）

メトリクス比較テンプレート

## Validation Results

### Before Improvement
- Step count: 15
- Tool calls: 23
- Failure points: 3
- Duration: ~8 minutes
- Manual interventions: 5

### After Improvement
- Step count: 11 (-4, -27%)
- Tool calls: 17 (-6, -26%)
- Failure points: 0 (-3, -100%)
- Duration: ~5 minutes (-37%)
- Manual interventions: 2 (-3, -60%)

### Verification
[E1] Command: `python3 plugins/sanctum/scripts/test_workflow.py`
Output: All tests passed (0.5s)

[E2] Command: `/validate-plugin sanctum`
Output: No issues found

ステップ 7：フィードバックを完了する（学びを保存する）

検証後、今後参照できるよう改善内容を記録します。

7.1：Git 履歴を更新する

今後の検索で見つけられる、説明的なメッセージを付けてコミットします。

git add <changed-files>
git commit -m "improve(sanctum): <component> - <specific fix>

Addresses recurring issue: <pattern from Step 0>
Reduces <metric> by <percentage>

Evidence: stability_gap reduced from 0.35 to 0.12"

AI 帰属を示すトレーラーは付けないでください。plugins/imbue/hooks/vow_no_ai_attribution.py は PreToolUse で、AI モデル名を含む共同執筆者および生成元のトレーラーを ブロックします。そのようなトレーラーを含むテンプレートを使うと、 エージェント自身のツールチェーンが拒否するコミットを作ることになります。

7.2：ツールに関する学びを Discussions に投稿する（推奨）

night-market のツールに関する所見（スキルの動作、エージェント間の 連携、フックのタイミング、コマンドの使いやすさ）は、ローカルメモリではなく https://github.com/athola/claude-night-market/discussions に記録してください。現在作業しているリポジトリにかかわらず、常に night-market リポジトリを対象にします。

plugins/sanctum/commands/fix-pr-modules/steps/6-complete.md のサブステップ 6.7 にある GraphQL パターンを使用してください。このパターンは night-market リポジトリと Learnings カテゴリを ID で解決し、 athola/claude-night-market を対象としてハードコードしているため、 どのリポジトリからでも使用できます。

ここでは plugins/abstract/scripts/post_learnings_to_discussions.py を使わないでください。引数は受け取らず、LEARNINGS.md を解析して 集約された日次ダイジェストを投稿します。これはワークフローの途中で 記録する所見とは別の成果物です。

リポジトリ固有の学びは現在のリポジトリに残します。ツールに関する 学びは常に https://github.com/athola/claude-night-market/discussions に投稿し、フレームワークの改善に役立てます。

7.3：Memory Palace に学びを記録する（任意、ローカルのみ）

改善がリポジトリ固有のパターン（ツールではない）に関するものであれば、ローカルに保存します。

# Store in review-chamber lessons
/review-room capture --room lessons --title "Workflow: <pattern name>"

7.4：改善メトリクスを更新する

改善の効果を追跡します。

# Check post-improvement stability
pensive:skill-review --skill sanctum:<component> --recommendations

これにより、今後の /fix-workflow と /update-plugins の実行で、この学びを参照するフィードバックループが作られます。

学んだ教訓を記録する（意思決定ジャーナル）

この作業で手戻り、失敗したアプローチ、または阻害要因があった場合は、 セッション終了後も知見が残るよう、docs/lessons-learned.md に記録します （草案を作成し、確認を得てから追記します）。

• leyline がインストールされている場合は、Skill(leyline:decision-journal) を呼び出し、 教訓のエントリー（what_happened、what_didnt_work、root_cause、action）を追記します。 phase は review に設定します。草案を提示し、確認を得てから追記します。
• 代替手段（leyline がない場合）：ファイル内の ENTRY TEMPLATE を使用して docs/lessons-learned.md に追記し、次の LL-NNN ID を割り当てます。

補助モジュール

• Issue の自動作成 - 先送りした項目から GitHub issue を自動作成するパターン

終了基準

• セッションの範囲が、明示された境界、トリガー、目標、および変更対象の成果物とともに記録されている
• 3 つ以上の異なる改善アプローチを立案し、評価している
• 受け入れ基準と対象ファイルを限定したリスト（正当な理由がない限り 5 ファイル以下）を設けて、1 つのアプローチを選択している
• 検証では、文章ではなく、変更前後のメトリクス（ステップ数、ツール呼び出し回数、または失敗箇所）を記録している
• 対象範囲に手戻り、失敗したアプローチ、またはブロッカーが含まれていた場合、その教訓を意思決定ジャーナルを通じて docs/lessons-learned.md に記録している

トラブルシューティング

よくある問題

コマンドが見つからない場合は、すべての依存関係がインストールされ、PATH からアクセスできることを確認してください。権限エラーが発生した場合は、ファイルシステムの権限を確認し、適切な権限でコマンドを実行してください。予期しない動作が発生した場合は、--verbose フラグを使用して詳細な実行データを取得できるよう、詳細ログを有効にしてください。