--- id: 'failure-modes-observability' name: Failure Modes & Observability in Design description: Ensure designs specify failure modes, timeouts, error contracts, and observability for critical flows. version: 0.1.0 category: upstream phase: upstream applyTo: - '**/api/**' - '**/routes/**' - 'docs/**/*' - 'pages/**/*' tags: [reliability, observability, api, design, upstream] severity: major inputContext: [diff, adr] outputKind: [findings, actions, questions, summary] modelHint: balanced dependencies: [repo_metadata, tracing] --- ## 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: rr-upstream-failure-modes-observability-001 — 失敗モード/観測性に関連する設計差分がない` ## False-positive guards / 抑制条件 - 失敗モード/観測性が別 ADR で既に合意され、差分が参照更新のみ。 - 影響範囲がローカルな試験コードで、運用対象外と明記されている。 ## 評価指標（Evaluation） - 合格基準: 指摘が差分に紐づき、根拠と次アクションが説明されている。 - 不合格基準: 差分と無関係な指摘、根拠のない断定、抑制条件の無視。 ## 人間に返す条件（Human Handoff） - 仕様や意図が不明確で解釈が分かれる場合は質問として返す。 - 影響範囲が広い設計判断やトレードオフは人間レビューへ返す。