cascade-workflow

段階的縮退ワークフロースキル

目的

段階的なフォールバック戦略を通じて、適切に縮退する仕組みを実装します。最適なアプローチが失敗またはタイムアウトした場合、許容可能な機能を維持しながら、システムは自動的によりシンプルで信頼性の高い代替手段に切り替わります。

このスキルを使用するタイミング

次の場合に使用します：

• 外部サービスへの依存関係がある場合（API、データベース）
• 許容可能な縮退モードがある、時間制約のある操作
• 結果が一部でも得られないよりは、部分的な結果が望ましい操作
• 高可用性が求められる場合（システムが常に応答する必要がある）
• 完璧な解決策を待つより、十分に良い解決策のほうが望ましい状況

次の場合は使用しないでください：

• 厳密な正確性が必要な操作（許容できる縮退がない）
• セキュリティ上重要な操作（認証、認可）
• 金融取引（「おおよその」処理が許されない）
• 失敗をユーザーに通知する必要がある場合（診断操作）
• 意味のあるフォールバックがない単純な操作

設定

コアパラメーター

タイムアウト戦略：

• aggressive - すばやく失敗させ、迅速に縮退します（5s / 2s / 1s）
• balanced - 妥当な時間をかけて試行します（30s / 10s / 5s） - デフォルト
• patient - フォールバック前に十分な時間をかけて試行します（120s / 30s / 10s）
• custom - 独自のタイムアウトを定義します

フォールバックの種類：

• service - 外部 API → キャッシュデータ → 静的な既定値
• quality - 包括的 → 標準 → 最小限の分析
• freshness - リアルタイム → 最近のデータ → 履歴データ
• completeness - 完全なデータセット → サンプル → 要約
• accuracy - 正確な値 → 概算 → 推定

縮退の通知：

• silent - ログに記録するのみで、ユーザーには通知しません
• warning - 縮退したことをユーザーに通知します
• explicit - 何が、なぜ縮退したのかを詳しく説明します

カスケードレベルの要件

PRIMARY（最適）：

• 可能な限り最良の結果
• 外部サービスに依存する場合があります
• 処理に時間がかかる、または多くのリソースを必要とする場合があります
• 失敗またはタイムアウトする可能性があります

SECONDARY（許容可能）：

• 品質は低下しますが、機能します
• PRIMARY より信頼性が高い
• より高速、または依存関係が少ない
• ユーザーにとって許容可能

TERTIARY（保証）：

• 必ず成功し、失敗しません
• 外部依存関係がありません
• 高速で信頼性があります
• 最小限ですが、機能します
• 重要：必ず失敗しないように設計する必要があります

実行プロセス

ステップ 1：カスケードレベルを定義する

• アーキテクトエージェントを使用してカスケードレベルを特定します
• PRIMARY のアプローチ（最適な解決策）を定義します
• SECONDARY のアプローチ（許容可能な縮退）を定義します
• TERTIARY のアプローチ（完了を保証する方法）を定義します
• 各レベルのタイムアウトを設定します
• 各レベルで何が縮退するかを記録します
• 重要：TERTIARY が必ず成功することを確認します

カスケード定義の例：

AI によるコード分析：

• PRIMARY：GPT-4 による包括的な分析（タイムアウト：30s）
• SECONDARY：GPT-3.5 による標準的な分析（タイムアウト：10s）
• TERTIARY：正規表現による静的分析（タイムアウト：5s）

外部 API からのデータ取得：

• PRIMARY：ライブ API 呼び出し（タイムアウト：10s）
• SECONDARY：キャッシュデータ（タイムアウト：2s）
• TERTIARY：既定値（タイムアウト：0s）

テスト実行：

• PRIMARY：テストスイート全体（タイムアウト：120s）
• SECONDARY：重要なテストのみ（タイムアウト：30s）
• TERTIARY：スモークテスト（タイムアウト：10s）

ステップ 2：PRIMARY のアプローチを試行する

• 最適な解決策を実行します
• 戦略設定に基づいてタイムアウトを設定します
• 実行の進行状況を監視します
• 正常に完了した場合：完了（最良の結果）
• 失敗またはタイムアウトした場合：ステップ 3 に進みます
• 試行と失敗の理由を記録します

# Pseudocode for primary attempt
try:
    result = execute_primary_approach(timeout=PRIMARY_TIMEOUT)
    log_success(level="PRIMARY", result=result)
    return result  # DONE - best outcome achieved
except TimeoutError:
    log_failure(level="PRIMARY", reason="timeout")
    # Continue to Step 3
except ExternalServiceError as e:
    log_failure(level="PRIMARY", reason=f"service_error: {e}")
    # Continue to Step 3

ステップ 3：SECONDARY のアプローチを試行する

• SECONDARY レベルへの縮退を記録します
• 許容可能なフォールバックの解決策を実行します
• より短いタイムアウトを設定します（通常は PRIMARY の 1/3）
• 実行の進行状況を監視します
• 正常に完了した場合：完了（許容可能な結果）
• 失敗またはタイムアウトした場合：ステップ 4 に進みます
• 試行と失敗の理由を記録します

# Pseudocode for secondary attempt
log_degradation(from_level="PRIMARY", to_level="SECONDARY")
try:
    result = execute_secondary_approach(timeout=SECONDARY_TIMEOUT)
    log_success(level="SECONDARY", result=result, degraded=True)
    return result  # DONE - acceptable outcome
except TimeoutError:
    log_failure(level="SECONDARY", reason="timeout")
    # Continue to Step 4

ステップ 4：第 3 のアプローチを試す

• 第 3 レベルへの劣化を記録します
• 確実に完了するアプローチを実行します
• 最短のタイムアウトを設定します（通常 1s）
• 必ず成功させる必要があります。失敗は許されません
• 最小限ながら機能する結果を返します
• 成功を記録します（品質は低下していますが、機能しています）
• 完了（確実に完了）

# Pseudocode for tertiary attempt
log_degradation(from_level="SECONDARY", to_level="TERTIARY")
try:
    result = execute_tertiary_approach(timeout=TERTIARY_TIMEOUT)
    log_success(level="TERTIARY", result=result, heavily_degraded=True)
    return result  # DONE - minimal but functional
except Exception as e:
    # THIS SHOULD NEVER HAPPEN
    log_critical_failure("TERTIARY approach failed - this is a bug!")
    raise SystemError("Cascade safety violation: tertiary failed")

ステップ 5：劣化を報告する

• 設定から通知レベルを判断します
• サイレント： 記録のみで、ユーザーへのメッセージはありません
• 警告： ユーザーに簡潔な通知を行います
• 明示的： 劣化について詳しく説明します
• どのレベルで成功したかを記録します
• 劣化による影響を説明します
• 分析用に、たどったカスケード経路を記録します

劣化報告のテンプレート：

サイレントモード：

[LOG] CASCADE: PRIMARY timeout (30s) → SECONDARY success (6s)
Result: standard_analysis (degraded from comprehensive)

警告モード：

⚠️  Using cached data (less than 1 hour old)
Current real-time data unavailable.

明示モード：

ℹ️  Analysis Quality Notice

We attempted to provide comprehensive code analysis using GPT-4,
but encountered slow response times (>30s timeout).

Fallback Applied:
- Used: GPT-3.5 standard analysis (completed in 6s)
- Quality: Standard (vs. Comprehensive)
- Impact: Advanced semantic insights not included

What You're Getting:
✓ Basic pattern detection
✓ Standard recommendations
✓ Code quality assessment

What's Missing:
✗ Complex architectural insights
✗ Deep semantic analysis
✗ Advanced refactoring suggestions

ステップ 6：カスケードのメトリクスを記録する

• たどったカスケード経路を記録します
• 到達したレベル（第 1／第 2／第 3）を記録します
• 試行した各レベルの所要時間を記録します
• 劣化の発生頻度を追跡します
• 失敗のパターンを特定します
• 必要に応じてカスケード戦略を更新します

追跡するメトリクス：

• レベルごとの成功率
• 平均応答時間
• 劣化の発生頻度
• ユーザーへの影響評価

ステップ 7：継続的な最適化

• 分析エージェントを使用してカスケードのメトリクスを確認します
• 最適化の機会を特定します
• 成功率に基づいてタイムアウトを調整します
• 第 2 のアプローチが頻繁に使われる場合は改善します
• 第 3 のアプローチが不十分な場合は更新します
• amplihack.memory.discoveries の store_discovery() を使って、得られた知見をメモリに保存します

最適化の基準：

• 第 1 のアプローチの成功率が 50% 未満の場合： タイムアウトが厳しすぎます → タイムアウトを延長します
• 第 2 のアプローチの使用率が 40% を超える場合： 第 2 のアプローチが実質的な「通常の」ケースです → 第 1 と第 2 のアプローチを入れ替えます
• 第 3 のアプローチの使用率が 10% を超える場合： 第 2 のアプローチの信頼性が不十分です → 第 2 のアプローチを改善します

トレードオフ

利点： システムは常に処理を完了し、完全に失敗することはありません コスト： ユーザーに品質が低下した応答が返される場合があります 最適な用途： 応答性が重要な、ユーザー向けの機能

例

例 1：Weather API の統合

設定：

• 戦略：バランス型（30s / 10s / 5s）
• 種類：サービスのフォールバック
• 通知：警告

実装：

async def get_weather(location: str) -> WeatherData:
    """Get weather data with cascade fallback"""

    # PRIMARY: Live weather API
    try:
        return await fetch_weather_api(location, timeout=30)
    except (TimeoutError, APIError):
        log.warning("PRIMARY weather API failed, trying cache")

    # SECONDARY: Cached weather data
    try:
        cached = await get_cached_weather(location, max_age=3600)
        if cached:
            notify_user("Using weather data from cache (< 1 hour old)")
            return cached
    except CacheError:
        log.warning("SECONDARY cache failed, using defaults")

    # TERTIARY: Default weather data
    return get_default_weather(location)  # Never fails

結果： システムは常に天気データを返し、品質は段階的に低下します

例 2：AI によるコードレビュー

設定：

• 戦略：時間重視（120s / 30s / 10s）
• 種類：品質のフォールバック
• 通知：明示的

カスケード経路：

1. 第 1：GPT-4 による包括的なレビュー - 120s 後にタイムアウト
2. 第 2：GPT-3.5 による標準的なレビュー - 18s で成功
3. 第 3：試行せず

例 3：検索結果のランキング

設定：

• 戦略：積極型（5s / 2s / 1s）
• 種類：精度のフォールバック
• 通知：サイレント

実装：

def search_and_rank(query: str) -> List[Result]:
    """Search with ML ranking, fallback to simple ranking"""

    results = fetch_results(query)

    # PRIMARY: ML-based ranking (sophisticated)
    try:
        return ml_rank(results, timeout=5)
    except TimeoutError:
        pass  # Silent fallback

    # SECONDARY: Heuristic ranking (good enough)
    try:
        return heuristic_rank(results, timeout=2)
    except TimeoutError:
        pass

    # TERTIARY: Simple text match ranking (basic)
    return simple_rank(results)  # Always fast

哲学との整合性

このワークフローでは、以下を徹底します。

• 耐障害性： システムは常に処理を完了し、完全に失敗することはありません
• ユーザー体験： エラーメッセージよりも、品質が低下していてもサービスを提供することを優先します
• 透明性： ユーザーは受け取る結果を理解できます（明示モードの場合）
• 段階的な拡張： デフォルトでは最適な状態で動作し、必要に応じて品質を下げます
• 品質の測定可能性： 各レベルで何が劣化するかを明確に定義します
• 継続的な改善： メトリクスに基づいてタイムアウトを最適化します
• 確実な完了： 第 3 レベルで失敗してはなりません

重要な原則

サービスを提供できないよりも、品質が低下していてもサービスを提供する方がよい