eval-driven-skill-design

id	eval-driven-skill-design
name	Eval-Driven Skill Design
description	新規 skill SKILL.md PR で `fixtures/` と `eval/` の happy-path × guard ペアが揃っているかを確認し、欠けている場合は eval cycle (#688) に乗せる手順を案内する。
version	0.1.0
category	upstream
phase	upstream
applyTo	["skills/**/SKILL.md"]
inputContext	["diff","repoConfig"]
outputKind	["findings","actions"]
modelHint	balanced
tags	["skill-authoring","eval","process","upstream"]
severity	minor
dependencies	["repo_metadata"]

Pattern declaration

Primary pattern: Reviewer Secondary patterns: Tool Wrapper Why: 新規 skill 追加時に happy-path / guard fixture と eval 配線の有無を診断し、欠けていれば repo-wide eval (#688) に組み込む手順を案内する educator スキル。既存 skill の改修や fixture-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 をどう通すかを案内する。

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 が測定できる。

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