Eval-Driven Skill Design

Pattern declaration

Primary pattern: Reviewer Secondary patterns: Tool Wrapper Why: skill 追加・重要変更時に happy-path / guard fixture、eval 配線、paired ablation の評価可能性を診断し、存在・発火と実効性を混同しないための educator スキル。fixture-only / docs-only PR では起動しない。

Goal / 目的

• 新規 skills/**/SKILL.md を追加する PR が 検出ケース (happy-path) と抑制ケース (guard) のペア を fixture として持つことを確認する。
• eval/promptfoo.yaml 相当の評価設定または tests/fixtures/repo-wide-eval/ への登録が用意されているかを確認する。
• 欠けている場合は npm run eval:fixtures / npm run eval:repo-context をどう通すかを案内する。
• 新規・重要変更された skill について、同じ case / runtime / model / effort で WITH skill と WITHOUT skill（または旧版 baseline と candidate） を比較できるか確認する。
• installed / selected / fired を effectiveness の証拠にせず、寄与が不明なら INCONCLUSIVE として追加 Evidence を要求する。

Guidance

Eval cycle 全体像 (#688 で整備済)

new SKILL.md
  ├─ fixtures/
  │   ├─ <NN>-happy.md        # 検出されるべき diff（必須 1 件以上）
  │   └─ <NN>-guard.md        # 検出してはいけない diff（必須 1 件以上）
  ├─ golden/<NN>-*.md         # promptfoo similar 評価用の代表出力
  ├─ prompt/{system,user}.md  # promptfoo prompts:
  └─ eval/promptfoo.yaml      # contains / not-contains / llm-rubric / similar

または tests/fixtures/repo-wide-eval/ に同じ skill の {happy, guard} ケースを追加し、tests/fixtures/repo-wide-eval/cases.json に登録する形でも eval lift が測定できる。

Marginal contribution / paired ablation

fixture / golden output は「壊れていないか」を見る regression evidence です。skill が存在する価値そのものは、可能な範囲で baseline と candidate の差分として測ります。

same case / runtime / model / effort
  ├─ WITHOUT skill (or previous-version baseline)
  └─ WITH skill    (or candidate)
       ↓
compare delta

原則:

• Usage != Effectiveness: installed / selected / fired は availability / activation evidence であり、品質改善の証拠ではない。
• 比較では skill 以外の条件を固定する。model / runtime / effort / input が違う結果を skill の寄与として扱わない。
• 非決定的な実行は単発結果で断定せず、複数 trial と paired case を使う。
• 最低限、detection / false positive / critical regression を比較し、取得可能なら time / token / cost / human intervention も見る。
• candidate 側が実際に発火していない、paired case が不足している、sample が足りない場合は INCONCLUSIVE。自動的に「効果なし」へ倒さない。
• River Review 内の Harness 改善では、独自比較器を増やさず既存の Experiment Manifest / paired replay（src/lib/paired-replay.mjs、docs/development/1574-p2-paired-replay.md）を優先して再利用する。
• model / runtime の major update、skill の責務・prompt・routing の大幅変更時は再評価する。旧モデルで有効だった skill が新モデルでは冗長になる可能性を前提にする。

判定は PASS | FAIL | INCONCLUSIVE とし、採用・廃止・自動 merge の authority はこのスキルに持たせません。

happy-path × guard ペア convention

• happy-path fixture: 「このパターンを必ず検出すること」を保証する。fixture ファイル名に happy / should-detect を含める。
• guard fixture: 「このパターンを誤検出してはいけない」を保証する。fixture ファイル名に guard / false-positive / should-not-detect を含める。
• ペアにすることで falsePositiveRateWith / detectionRateWith (evaluateRepoWideFixtures メトリクス) が両方測れ、後の改善で 片方だけが破綻するケース を検知できる。

eval コマンドと役割

対象	コマンド	何が回るか
skill schema	npm run skills:validate	YAML frontmatter / 必須キー検証
review fixtures	npm run eval:fixtures	tests/fixtures/review-eval/cases.json に登録された skill の出力検証
repo-wide eval	npm run eval:repo-context	tests/fixtures/repo-wide-eval/ の context-lift / FP rate メトリクス
集約 driver	npm run eval:all	上記 + planner / regression / meta を一括実行

ローカルで失敗したまま push しない（CI 通過のみに頼らない）。

判断フロー

新規 skills/**/SKILL.md の追加 diff を見たとき、次の順で確認する。

1. fixtures/ ディレクトリが追加されているか？
   • なし → 「happy / guard fixture が必要」を指摘する。
2. happy-path ペアが揃っているか？
   • guard だけ / happy だけ → 片側欠落として指摘する。
3. eval/promptfoo.yaml か tests/fixtures/repo-wide-eval/cases.json への配線があるか？
   • なし → どちらかを選んで配線する手順を提示する（per-skill promptfoo か repo-wide cases.json か）。
4. baseline / candidate の比較方法が定義されているか？
   • 新規 skill なら WITHOUT skill、既存 skill の重要変更なら旧版を baseline にする。
5. activation と effectiveness が分離されているか？
   • fired だけを成功条件にしている場合は指摘する。
6. paired comparison が実行不能または sample 不足か？
   • INCONCLUSIVE と追加 Evidence の取得条件を明示する。推測で PASS / FAIL にしない。
7. fixture / eval / contribution path が揃っている → 何も指摘しない（このスキルは silent でよい）。

Non-goals / 扱わないこと

• skill の 検出ロジックの妥当性 自体（それは各 skill の領分）。
• typo / wording / reference link だけの docs-like 変更など、skill の責務・trigger・判断ロジック・routing・modelHint・実行ロジックを変えない軽微変更。
• prompt/ や golden/ 内容のスタイル指摘（fixture / eval の有無のみを確認する）。
• 個別 fixture の diff 内容のレビュー（scripts/evaluate-review-fixtures.mjs などが回す）。

Pre-execution Gate / 実行前ゲート

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

• 差分に新規 skills/**/SKILL.md、または 実質変更された SKILL.md / prompt/** / scripts/** が含まれている
• fixture / eval / paired contribution のいずれかに未確定がある、または責務・trigger・判断ロジック・routing・modelHint・実行ロジックの変更によって既存 Evidence の再利用可否を確認する必要がある

ゲート不成立時の出力:

NO_REVIEW: eval-driven-skill-design — skill の実質変更がない、または fixture / eval / contribution evidence が既に十分

False-positive guards / 抑制条件

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

• 同 PR 内に別の eval 配線（tests/fixtures/repo-wide-eval/cases.json 編集等）がある場合、fixtures/ ディレクトリが skill 配下になくても "missing eval" として指摘しない。
• 新規 skill の applyTo が **/* のみで真の対象パターンが空のドラフトであることが明らか（severity: info + tags: [draft] 等）なケースでは、fixture 必須化を促さない。代わりに「ドラフト解除前に eval を整備する」と案内する。
• 既存 skill の copy-and-rename だけで実質 fixture も流用される PR（同 commit で git mv の rename detected）では片側 fixture でも許容する。

Output / 出力例

findings:
  - severity: minor
    file: skills/midstream/rr-midstream-newcheck-001/SKILL.md
    line: 1
    issue: |
      新規 skill `rr-midstream-newcheck-001` が追加されましたが、
      `fixtures/` ディレクトリが見当たりません。happy-path × guard
      のペア fixture が無いと #688 の repo-wide eval で
      detectionRate / falsePositiveRate を測定できず、
      後続改修時の regression を検知できません。
    suggestion: |
      最低限以下を追加してください。
      - skills/midstream/rr-midstream-newcheck-001/fixtures/01-should-detect.md
      - skills/midstream/rr-midstream-newcheck-001/fixtures/02-should-not-detect.md
      評価配線は per-skill promptfoo (`eval/promptfoo.yaml`) か、
      `tests/fixtures/repo-wide-eval/cases.json` への追加のいずれかを選び、
      ローカルで `npm run eval:fixtures` または
      `npm run eval:repo-context` が exit 0 で通ることを確認してください。
actions:
  - type: 'verify'
    description: 'PR merge 前にローカルで `npm run eval:all` が通ることを確認する'

References

• Repo-wide eval 実装: src/lib/repo-wide-fixtures-eval.mjs / scripts/evaluate-review-fixtures.mjs
• Fixture 構造の参考: skills/midstream/security-basic/
• Schema: schemas/skill.schema.json
• 改善ループ: skills/agent-skills/river-review/references/IMPROVEMENT_LOOP.md
• paired comparison: docs/development/1574-p2-paired-replay.md / src/lib/paired-replay.mjs