quality-gates

品質ゲート

このスキルでは、タスクの複雑さを評価し、品質ゲートを適用して、未完了または定義が不十分なタスクに労力を無駄に費やさない方法をエージェントに教えます。

重要な原則： 情報が不完全な場合は、作業を進める前にいったん止めて確認してください。誤った解決策に時間を費やすより、質問するほうが適切です。

---

概要

自動で有効化される条件

• 新しいタスクの割り当てを受けたとき
• 複雑な機能の実装を始めるとき
• Squad モードで作業を割り当てる前
• 要件が不明確または不完全に思われるとき
• 同じタスクで 3 回失敗した後
• 依存関係が原因で行き詰まったとき

手動で有効化する条件

• ユーザーから複雑さの評価を求められたとき
• 複数ステップからなるプロジェクトを計画するとき
• スケジュールを確定する前

---

基本概念

複雑さのスコアリング（1～5 の尺度）

レベル	ファイル数	行数	所要時間	特徴
1 - ごく簡単	1	< 50	< 30 分	依存関係なし、不明点なし
2 - 簡単	1-3	50-200	30 分 - 2 時間	依存関係 0-1 個、不明点は最小限
3 - 中程度	3-10	200-500	2-8 時間	依存関係 2-3 個、いくつかの不明点
4 - 複雑	10-25	500-1500	8-24 時間	依存関係 4-6 個、重大な不明点
5 - 非常に複雑	25+	1500+	24+ 時間	依存関係 7+ 個、多数の不明点

上記の表が正式な評価基準です。平均ではなく、max(file_count, LOC, dependency_count, unknowns) でスコアを付けてください。1 つでもレベル 5 の軸があれば、タスクはレベル 5 です。入力値を測定するには、scripts/assess-complexity.md または scripts/analyze-codebase.sh <target> を実行してください。

ブロックのしきい値

条件	しきい値	アクション
YAGNI ゲート	正当化比率 > 2.0	よりシンプルな代替案を提示してブロック
YAGNI 警告	正当化比率 1.5-2.0	よりシンプルな代替案を提示して警告
重要な質問	未回答が > 3 件	ブロック
依存関係の欠落	ブロックするものが 1 つでもある	ブロック
失敗した試行	>= 3	ブロックしてエスカレーション
エビデンスの失敗	修正の試行が 2 回	ブロック
複雑さの超過	レベル 4-5 で計画がない	ブロック

警告条件（慎重に進めてください）：

• 複雑さがレベル 3
• 未回答の質問が 1-2 件
• 失敗した試行が 1-2 回

エスカレーションの手順とゲートの判定ロジックは、どちらも以下の「クイックリファレンス」にあります。YAGNI 比率、各ティアの LOC 予算、よりシンプルな代替案の提示については、rules/yagni-gate.md を参照してください。

---

参考資料

必要に応じて Read("references/<file>") で読み込んでください：

ファイル	内容
ork-delta.md	OrchestKit 固有の注意点と独自の決定事項：行数カウントの正確性、フェイルオープンポリシー、ゲートの自己監視、バイパスできないカテゴリ
unified-scoring-framework.md	正式な 0～10 の評価軸、重み、評点のしきい値、改善の優先順位付け。ork:assess と ork:verify からも読み込まれます

---

上流のカバレッジ（再掲しないでください）

このスキルでは、汎用的な品質ゲートの実践を扱い、OrchestKit 固有の差分のみを残します。以下のトピックが出てきた場合は、ここで改めて説明するのではなく、参照先を確認してください。

トピック	参照先
複雑度 1〜5 の基準、レベルごとの例、評価式	上記の「複雑度スコアリング」テーブル（正規の情報源）
BLOCKING と WARNING の条件、エスカレーション手順、試行回数の追跡	上記の「ブロッキングのしきい値」と「クイックリファレンス」（正規の情報源）
YAGNI 比率、プロジェクト階層ごとの LOC 予算、よりシンプルな代替案	rules/yagni-gate.md + ork:scope-appropriate-architecture
スコアの評価軸、重み、グレードのしきい値	references/unified-scoring-framework.md
LLM-as-judge、G-Eval、観点別スコアリング、メトリクス API	ork:testing-llm
要件の網羅性、受け入れ基準のテンプレート	ork:write-prd
ゲートの一部として適用されるテスト基準	ork:architecture-patterns
ゲート入力用のリポジトリメトリクス（ファイル数、LOC、テスト、変更頻度）	このスキルの scripts/analyze-codebase.sh
ゲートノードの LangGraph 条件付きルーティング	https://langchain-ai.github.io/langgraph/
ゲート失敗時の FastAPI エラーレスポンス	https://fastapi.tiangolo.com/tutorial/handling-errors/
ゲート出力スキーマ用の Pydantic バリデーター	https://docs.pydantic.dev/latest/concepts/validators/
指数バックオフによる再試行、ゲートに対する SLO ベースのアラート	https://sre.google/workbook/alerting-on-slos/

---

クイックリファレンス

ゲート判定フロー

0. YAGNI check (runs FIRST — before any implementation planning)
   → Read project tier from scope-appropriate-architecture
   → Calculate justified_complexity = planned_LOC / tier_appropriate_LOC
   → If ratio > 2.0: BLOCK (must simplify)
   → If ratio 1.5-2.0: WARN (present simpler alternative)
   → Security patterns exempt from YAGNI gate

1. Assess complexity (1-5)
2. Count critical questions unanswered
3. Check dependencies blocked
4. Check attempt count

if (yagni_ratio > 2.0) -> BLOCK with simpler alternatives
else if (questions > 3 || deps blocked || attempts >= 3) -> BLOCK
else if (complexity >= 4 && no plan) -> BLOCK
else if (yagni_ratio > 1.5 || complexity == 3 || questions 1-2) -> WARNING
else -> PASS

ゲートチェックのテンプレート

## Quality Gate: [Task Name]

**Complexity:** Level [1-5]
**Unanswered Critical Questions:** [Count]
**Blocked Dependencies:** [List or None]
**Failed Attempts:** [Count]

**Status:** PASS / WARNING / BLOCKED
**Can Proceed:** Yes / No

エスカレーションのテンプレート

## Escalation: Task Blocked

**Task:** [Description]
**Block Type:** [Critical Questions / Dependencies / Stuck / Evidence]
**Attempts:** [Count]

### What Was Tried
1. [Approach 1] - Failed: [Reason]
2. [Approach 2] - Failed: [Reason]

### Need Guidance On
- [Specific question]

**Recommendation:** [Suggested action]

---

コンテキストシステムとの統合

// Add gate check to context
context.quality_gates = context.quality_gates || [];
context.quality_gates.push({
  task_id: taskId,
  timestamp: new Date().toISOString(),
  complexity_score: 3,
  gate_status: 'pass', // pass, warning, blocked
  critical_questions_count: 1,
  unanswered_questions: 1,
  dependencies_blocked: 0,
  attempt_count: 0,
  can_proceed: true
});

エビデンスシステムとの統合

// Before marking task complete
const evidence = context.quality_evidence;
const hasPassingEvidence = (
  evidence?.tests?.exit_code === 0 ||
  evidence?.build?.exit_code === 0
);

if (!hasPassingEvidence) {
  return { gate_status: 'blocked', reason: 'no_passing_evidence' };
}

---

ベストプラクティスのパターンライブラリ

プロジェクト間で成功・失敗のパターンを追跡し、同じ間違いを繰り返さないようにするとともに、コードレビュー中に先回りして警告します。

ルール	ファイル	主なパターン
YAGNI ゲート	rules/yagni-gate.md	実装前のスコープ確認、妥当性が示された複雑度比、よりシンプルな代替案
パターンライブラリ	rules/practices-code-standards.md	成功・失敗の追跡、信頼度のスコアリング、メモリとの統合
レビューチェックリスト	rules/practices-review-checklist.md	カテゴリ別レビュー、アンチパターンの先行検出

パターンの信頼度レベル

レベル	意味	アクション
強い成功パターン	3 件以上のプロジェクトで、成功率 100%	常に推奨
結果が混在	成功と失敗の両方がある	コンテキストに応じて判断
強いアンチパターン	3 件以上のプロジェクトで、すべて失敗	説明を添えてブロック

---

よくある落とし穴

落とし穴	問題	解決策
「単純な」タスクではゲートを省略する	後で行き詰まる	必ずゲートチェックを実行する
WARNING の状態を無視する	文書化されていない前提が問題を引き起こす	すべての前提を文書化する
試行回数を追跡しない	同じアプローチにサイクルを浪費する	すべての試行を追跡し、3 回でエスカレーションする
BLOCKED の状態で先に進む	誤った解決策を構築する	BLOCKED のゲートを絶対に回避しない

---

---

関連スキル

• ork:scope-appropriate-architecture - YAGNI ゲートに渡すプロジェクト階層の検出
• ork:architecture-patterns - 品質ゲートの一部としてテスト基準を適用
• ork:testing-llm - 品質検証のための LLM-as-judge パターン（DeepEval、RAGAS）
• ork:golden-dataset - データセットが品質しきい値を満たしているか検証

主な判断

判断	選択	理由
複雑度の尺度	1〜5 レベル	見積もりに十分な細かさがあり、迅速な評価にも十分シンプル
ブロックのしきい値	重要な質問 3 件	未解決事項が多すぎる状態で先に進むことを防ぐ
エスカレーションのトリガー	3 回の失敗	粘り強さと、無駄なサイクルの回避のバランスを取る
レベル 4〜5 の要件	計画が必須	複雑なタスクには事前の分解が必要

機能の詳細

complexity-scoring

キーワード: 複雑さ、スコア、難易度、見積もり、規模、1～5の尺度 解決する課題: このタスクはどのくらい複雑ですか？タスクの複雑さを1～5の尺度で評価し、実装の難易度を判定します。

blocking-thresholds

キーワード: ブロック、しきい値、ゲート、停止、エスカレーション、続行できない 解決する課題: どのような場合に進行をブロックすべきですか？重要な質問が3件を超える場合はブロックし、依存関係が不足している場合はブロックします。

critical-questions

キーワード: 重要な質問、未回答、不明点、明確化 解決する課題: 重要な質問とは何ですか？未回答の質問を数え、3件を超える場合はブロックします。

stuck-detection

キーワード: 行き詰まり、失敗した試行、再試行、3回の試行、エスカレーション 解決する課題: 行き詰まったことをどのように検出しますか？3回失敗した後にエスカレーションします。

gate-validation

キーワード: 検証、ゲートチェック、合格、不合格、ゲートのステータス 解決する課題: 品質ゲートをどのように検証しますか？タスク開始前にゲート検証を実行します。

pre-task-gate-check

キーワード: タスク開始前、開始前、続行可能 解決する課題: 開始前にゲートをどのように確認しますか？複雑さを評価し、ブロッカーを特定します。

complexity-breakdown

キーワード: 分解、細分化、サブタスク、タスクの分割 解決する課題: 複雑なタスクをどのように分解しますか？レベル4～5のタスクをレベル1～3のサブタスクに分割します。

requirements-completeness

キーワード: 要件、不完全、受け入れ基準 解決する課題: ゲートチェックのみ：開始するのに十分な要件一式がそろっていますか？要件自体の作成は ork:write-prd の範囲です（「上流の対象範囲」を参照）。

escalation-protocol

キーワード: エスカレーション、ユーザーへの確認、助けが必要、人によるガイダンス 解決する課題: いつ、どのようにエスカレーションしますか？3回失敗した後にエスカレーションします。

llm-as-judge

キーワード: LLM による評価、g-eval、観点別スコアリング、品質検証 解決する課題: ゲートのしきい値のみ：合格するには、評価者がどのスコアを返す必要がありますか？評価者の構築と実行は ork:testing-llm の範囲です（「上流の対象範囲」を参照）。

yagni-gate

キーワード: yagni、過剰設計、正当化される複雑さ、スコープチェック、複雑すぎる、簡素化 解決する課題: この複雑さは正当化されますか？プロジェクトのティアに照らして justified_complexity 比率を計算し、2.0を超える場合はブロックし、よりシンプルな代替案を提示します。