Failure Modes & Observability in Design

Pattern declaration

Primary pattern: Reviewer Secondary patterns: Inversion Why: 設計の差分から失敗モード・エラー契約・観測性の抜けをレビューし、障害シナリオを逆照射してクリティカルフローの堅牢性を検証する。

Rule / ルール

• クリティカルフロー（認証、課金、データ保存など）の失敗モード（タイムアウト、リトライ、フォールバック、外部障害、権限不備）を明示する。
• エラー応答（ステータス、エラーコード、message/detail）の契約を一貫させ、クライアントが判断できる形にする。
• SLO/監視、ログ、メトリクス、トレースなどの観測性を設計に含める。

Heuristics / 判定の手がかり

• 外部依存（DB/HTTP/Queue）の失敗時に「何が起きるか」が仕様に無い（例: リトライ方針、タイムアウト、冪等性）。
• 4xx/5xx の使い分け、エラー構造がエンドポイントごとに不揃い。
• Rate limit / backoff / circuit breaker の前提があるのに、設計/ADR で触れられていない。
• 障害時の切り分けに必要なログ（相関ID、requestId、重要な属性）やメトリクスの設計が無い。

Questions / 確認質問（不明な場合は質問として出す）

• 代表的な失敗モード（タイムアウト、外部 5xx、バリデーション、権限、競合）はどれですか？
• 冪等性キーやリトライ可否の判断はどこで担保しますか？
• 監視対象（SLO、エラーバジェット、アラート条件）はありますか？

Actions / 改善案

• タイムアウト値、リトライ回数、バックオフ、フォールバックを ADR/設計に追記する。
• エラー応答の共通スキーマ（code/message/detail/requestId など）を定義し、例を載せる。
• クリティカルフローに相関IDを付与し、ログ/トレースのキーを設計に含める。

Non-goals / 扱わないこと

• 実際の監視基盤やアラート運用の構築。
• 既存プロダクション障害の原因究明。
• 実装詳細（ログライブラリ選定など）の決定。

Pre-execution Gate / 実行前ゲート

このスキルは以下の条件がすべて満たされない限りNO_REVIEWを返す。

• 差分にAPI定義・ルート定義・設計ドキュメントのいずれかが含まれている
• inputContextにdiffが含まれている

ゲート不成立時の出力: NO_REVIEW: failure-modes-observability — 失敗モード/観測性に関連する設計差分がない

False-positive guards / 抑制条件

• 失敗モード/観測性が別 ADR で既に合意され、差分が参照更新のみ。
• 影響範囲がローカルな試験コードで、運用対象外と明記されている。

評価指標（Evaluation）

• 合格基準: 指摘が差分に紐づき、根拠と次アクションが説明されている。
• 不合格基準: 差分と無関係な指摘、根拠のない断定、抑制条件の無視。

人間に返す条件（Human Handoff）

• 仕様や意図が不明確で解釈が分かれる場合は質問として返す。
• 影響範囲が広い設計判断やトレードオフは人間レビューへ返す。