Context Budget Tuning

Pattern declaration

Primary pattern: Reviewer Secondary patterns: Tool Wrapper Why: .river-review の context 設定変更時に、reviewMode プリセット選択 / token・char 上限 / ranking weights をモデル仕様と照合してレビューする educator スキル。

Goal / 目的

• .river-review.{yaml,json} の context.reviewMode / context.budget / context.ranking 変更が モデル仕様 (model.modelName) と整合しているか をレビューで確認する。
• reviewMode: tiny | medium | large プリセットの 既定値 (1024 / 4000 / 16000 max tokens) と explicit budget の優先関係を理解させる。
• ranking weights (pathProximity / symbolUsage / siblingTest / commitRecency) の 0.0〜1.0 範囲 とスキーマキー名を schema (src/config/schema.mjs) と照合する。

Guidance

reviewMode プリセット既定値 (src/lib/context-presets.mjs)

reviewMode	maxTokens 既定	想定モデル
tiny	1024	コンテキスト窓の小さいモデル / 短い PR
medium	4000	gpt-4o-mini / sonnet 級モデルの通常 PR
large	16000	大型モデルでの深掘りレビュー

• 明示的 context.budget がある場合は 常に preset より優先 する。
• budget.maxTokens の上限は schema で 64000、maxChars は 200000 まで。

モデル仕様との整合チェック

• context.budget.maxTokens は 使用する model.modelName の公式仕様（または運用上採用している実効 context window） を超えないように設定する。プロバイダの仕様変更で値は変動するため、本スキルでは具体値を固定しない。
• 小型モデル（例: gpt-4o-mini 級）に large プリセット (16000 token) を当てると、モデルの実効 context window を超える分は切捨てられて redundant になり、コストのみ増える。プリセットの maxTokens がモデル仕様の上限を上回らないか を確認する。
• 逆に大型モデルに tiny プリセット (1024 token) を当てている場合は、context が不足してレビュー品質が落ちる可能性を指摘する。

ranking weights のレビュー

• キーは schema 定義 (pathProximity / symbolUsage / siblingTest / commitRecency) と一致しなければならない。古い名称（symbolOverlap / testAffinity）は #728 で廃止済み。
• contextRankingSchema.weights は .strict() のため、未知キーを含む設定は 設定ロード時に Unknown key エラーで失敗 する（silently 無視されない）。古い名称が残っている設定は CI でも気付かれず動き続けることはなく、即座に明示的なエラーになる。
• 各 weight は 0.0〜1.0。合計が 1 を超えても問題ないが、scoreContextCandidate が weighted average を取るため相対比のみが意味を持つ。

perSectionCaps の整合

• budget.perSectionCaps (fullFile / tests / usages / config) は char 単位。各 cap と budget.maxChars、token budget の min が実効値。
• セクション別 cap を 0 に設定すると当該セクションが収集対象から外れる。意図的な省略でなければ警告。

Non-goals / 扱わないこと

• ranking weights の最適値そのものの探索（プロジェクト固有）。
• context.budget を使わない運用判断（CI 環境差異など）。
• 個別 PR レビューで実際に消費されたトークン量の検証 (それは reviewDebug.repoContextBudget の観測責務)。

Pre-execution Gate / 実行前ゲート

このスキルは以下のいずれかが満たされない限り NO_REVIEW を返す。

• 差分にリポジトリ直下の .river-review.{yaml,yml,json} の変更が含まれている（src/config/loader.mjs が探索する対象はこの 3 ファイルのみ）
• 変更が context.budget / context.ranking / context.reviewMode のいずれかに触れている

ゲート不成立時の出力: NO_REVIEW: context-budget-tuning — context.* 設定の変更が検出されない

False-positive guards / 抑制条件

Pre-execution Gate を通過した後の 個別指摘の抑制条件 に絞る。

• ranking weights の値が schema 範囲内 (0.0〜1.0) で、合計が 1 でなくとも relative ratio として正しければ指摘しない (合計 1 制約は schema にない)。
• reviewMode を tiny にして budget を明示しないケースを「budget 不足」と誤認しない（preset がカバーしている）。

Output / 出力例

findings:
  - severity: minor
    file: .river-review.yaml
    line: 18
    issue: |
      `reviewMode: large` (preset maxTokens 16000) を小型モデル `model.modelName: gpt-4o-mini`
      と組み合わせています。`large` プリセットの 16000 token は当該モデルの公式仕様の
      effective context window を上回る可能性が高く、末尾 context が切捨てられて redundant になります
      (具体値は使用モデルの公式仕様で確認してください)。
    suggestion: |
      モデル仕様の上限内に収まる `reviewMode: medium` (preset maxTokens 4000) を起点に検討し、
      depth が必要な場合は `context.ranking.enabled: true` で近接度の高い候補を
      優先させ、weights を `pathProximity: 0.5, symbolUsage: 0.3` 等に調整してください。
  - severity: major
    file: .river-review.yaml
    line: 24
    issue: |
      `context.ranking.weights.symbolOverlap` を指定していますが、schema
      (`src/config/schema.mjs` `contextRankingSchema.weights`) は `.strict()` で、
      正規キー名は `symbolUsage` です (#728 でリネーム済み)。古い名称のままだと
      設定ロード時に **Unknown key エラーで失敗** します。
    suggestion: |
      `symbolOverlap` → `symbolUsage`、`testAffinity` → `siblingTest` にリネームしてください。
actions:
  - type: 'verify'
    description: 'PR 後の review で `reviewDebug.repoContextBudget.remaining` が 0 / 過大に余っていないかを観測する'