# Verify Traceability

> Use when a PR is ready for merge review and someone must confirm that every line of the Issue's approved 期待 is covered by an E2E test with evidence — before human gate ③ reads the test code

- Skill: `yannsugi/verify-traceability` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yannsugi/verify-traceability`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yannsugi/verify-traceability/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yannsugi (https://skillmd.com/u/yannsugi)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yannsugi/verify-traceability

---


# verify-traceability

品質担保フェーズの照合役。承認済みの「期待」の全行が、テストとエビデンスで覆われていることを機械的に示す。
思想は `${CLAUDE_PLUGIN_ROOT}/DESIGN.md` の「品質担保」節と「通底する原則」の入力契約。

**核**: 照合であって判断ではない。迷う差分は結論を出さず上位へ渡す。

## 入力契約

読んでよいもの(全列挙):
- 対象 Issue の「## 期待」節のみ(`gh issue view <n>`。「## コンテキスト」以降は読まない)
- PR の diff(`gh pr diff <n>`)
- テストコード本文(名前だけで判定しない)
- テスト実行ログ・スクリーンショット等のエビデンス

読んではいけないもの:
- Issue の「## コンテキスト」節、実現案の L2(判断根拠・却下案・⚠)。採点が甘くなるため、渡されても使わない
- 実装者の会話履歴・PR 説明文の「意図」の記述

## 手順

1. 期待節の Tobe・制約・非機能を一行一項目に番号づけして列挙する(T1, C1, N1 …)
2. 各項目について、対応するテストを **本文を読んで** 特定する。テスト名の一致は根拠にならない。テストが観測している振る舞いが項目の文と一致するかを見る。本文が読めない(要約しかない・ファイルが無い)場合は covered にできないので escalate
   種別の判定: 利用者の入口(画面・API・ファイル着信)から操作して結果を観測していれば E2E。ディレクトリ名や `e2e` の接頭辞は手がかりであって根拠ではない。本文から判別できなければ escalate
3. 対応表を埋める: 項目 / テスト(ファイル:テスト名) / 種別(E2E か unit か) / エビデンス(ログ行・画像パス) / 判定。エビデンスは項目単位で特定できるものを書く。集計値(3 passed)しか無ければそう書き、項目単位の裏付けが無いことを明示する
4. 判定は3値のみ:
   - **covered**: E2E テスト本文が項目の振る舞いを観測し、passed のエビデンスがある
   - **uncovered**: 対応テストがない、または unit のみで E2E の観測がない
   - **escalate**: 一致するか迷う。理由を一行添えて上位(人間または Fable)へ渡す。自分で白黒をつけない
5. 未カバー一覧と escalate 一覧を分けて出す
6. 対応表 + 未カバー + escalate のみを文面として利用者に提示する。`gh pr comment <n> --body-file` での投稿は、利用者が明示的に指示した場合にのみ実行する。マージ可否の提案、リスク受容の交渉、フォローアップの推奨は書かない(判断は人間の役割)

試走でローカルファイル `<name>.md` を対象にする場合は、PR コメント文面を `<name>.traceability.md` に書く。

## 出力書式

```
## 期待→テスト対応表
| # | 期待 | テスト | 種別 | エビデンス | 判定 |
|---|---|---|---|---|---|
## 未カバー
- T4: …
## エスカレーション
- T2: e2e が localStorage の有無を見ており「再読込後も維持」を直接観測していない可能性
```

## よくある失敗

- コンテキスト節や実現案の⚠を根拠に書く → 入力契約違反。読んだら破棄して期待節だけで再照合
- テスト名が期待の文と同じなので covered → 本文を読んでいない
- unit テストを covered にする → 期待は E2E 観測が定義。unit のみは uncovered
- 「今日中にマージしたい」に応じて条件つき合格を提案する → 照合役の越権。uncovered として出すだけ