メインコンテンツまでスキップ

Skill Policy（運用ルール）

この文書は、River Review のスキルを「運用として育てる」ためのルールです。スキル作者向けの書き方は pages/guides/write-a-skill.md を参照してください。

目的​

  • スキルが増えても品質がブレず、レビューが “うるさく” ならない
  • 変更がテスト可能な仕様（ルール）として残り、回帰を防げる
  • 外部コントリビューターが参加しやすい（期待が明確）

スキル追加・変更のレビューフロー（最小）​

  1. 変更の目的が 1 行で言える（何を減らす/増やす/防ぐのか）
  2. applyTo が適切に絞られている（過剰適用しない）
  3. 誤検知ガード（黙る条件）と Non-goals がある
  4. 出力（指摘文）が短く、次の行動に結びつく
  5. npm run skills:validate が通る

最終判断（迷ったとき）​

曖昧なケースや意見が割れた場合、最終的な判断はメンテナが行います。判断基準は coverage よりも precision を優先します。

後方互換（Breaking を避ける）​

原則:

  • 既存の利用者が困る変更は避ける（同名の意味変更、破壊的な出力変更など）
  • 破壊的変更が必要なら、PR で明示し、必要に応じて Issue で合意してから進める

最低限:

  • id は安定させる（移動・リネームしても同一スキルとして追跡できる）
  • phase / applyTo の変更は影響が大きいので、理由を PR に残す

誤検知（False Positive）報告の扱い​

誤検知は “直す価値がある不具合” です。次を揃えます。

  • 症状: どの差分で、何が誤検知だったか
  • 期待: 本来どう振る舞うべきか（黙る/条件付きで言う）
  • 対応: ガード条件（黙る条件）を追加する、または表現を弱める

可能なら、最小の再現差分を fixtures として追加し、回帰を検知できる形にします。

“良いスキル” の採用基準（優先順）​

  1. Precision（当たる）: 誤検知が少ない
  2. Actionability（次の一手）: 修正方針が分かる
  3. Evidence（根拠）: どこを見て言っているかが明確
  4. Coverage（網羅）: 後から増やす（最初から広げすぎない）

Stable Contract（変えてはいけない核）​

以下は安定した契約（stable contract）として扱い、破壊的変更をする場合は major version bump が必要です。

  • 出力フォーマット（例: <file>:<line>: <message> 形式や NO_ISSUES の意味）
  • severity / confidence の意味論（利用者が期待する解釈）

Community → First-party 昇格（recommended: true）​

community/ に置かれたスキルは以下の条件をすべて満たすと昇格候補になります。

昇格条件​

  1. フィクスチャカバレッジ: fixtures/ に happy-path と false-positive の両方を含む .md フィクスチャがあること（例: 01-icon-button-happy.md, 02-decorative-img-false-positive.md）
  2. ゴールデン出力: 各フィクスチャに対応する golden/<name>.md（Finding: / Evidence: 形式の散文ゴールデン出力）が存在し、eval（eval/promptfoo.yaml のアサーション）がパスすること
  3. 誤検知ガード / Non-goals: スキル本文に黙る条件と対象外ケースが明記されていること
  4. メンテナーレビュー: 少なくとも 1 名のメンテナー（CODEOWNERS 記載者）の Approve があること。複数メンテナーによる相互レビューが望ましいが、現状の CODEOWNERS は単独オーナー（@s977043）のため努力目標として扱う

eval の実行手順とゴールデン生成の詳細は docs/runbook/community-skill-eval.md を参照してください。

昇格を申請する手順​

  1. 上記条件が整ったら、PR のタイトルに [promotion-request] プレフィックスを付ける。
  2. PR 本文に次を記載する。
    • フィクスチャ一覧（ファイルパスと件数）
    • eval 出力（scripts/run-promptfoo-eval.sh などのパス確認）
    • 誤検知ガードと Non-goals の箇条書き
  3. レビュアーを CODEOWNERS に記載されたメンテナーからアサインする。
  4. メンテナーの Approve 取得後、skills/registry.yaml で当該スキルの recommended: false → true を設定して PR をマージする。

タイムライン目安: 条件を満たした PR は通常 2 週間以内にレビューが入ります。長期間応答がない場合は Issue でメンテナーに ping してください。

廃止（Deprecate）ポリシー​

  • 使われなくなったスキルや、重複したスキルは整理する
  • 置き換え先がある場合は、PR で代替スキル（id）を明記する
  • 影響が大きい場合は、先に Issue を立てて合意を取る