製品の真実 (Product truth)
製品にない機能を見せてしまう製品動画は、動画がないよりも悪い結果を招きます。このスキルの基となった制作現場では、最もコストがかかったのはすべて真実の欠如による失敗でした。すなわち、誤ったサイズと誤った製品名が付いた手作りバッジ、製品が別のトリガーでしか結果を返さないのに「コール結果を待機中」とナレーションされたワークフロー、エンドツーエンドで誰も検証していないテストコールを確定予約と偽った表示、そしてチームが合意したポジショニングと矛盾する見出しの会社文書です。これらはすべて、レビュー担当者によって遅い段階で発見され、バージョン変更のコストが発生しました。
このスキルは、チェックを明示的かつ機械的に行います。すべての行とすべての画面にTRUTH.md上の行とソースを割り当て、truth_check.py は、どの行が欠けているか、古いか、裏付けがない場合にビデオを拒否します。
入力
videos/<video>/audio/lines.tsv(ナレーション、line idごとに一文)videos/<video>/SOURCES.md(source-reconからの出力:画面とそのコード)videos/<video>/BRIEF.md,COVERAGE.md,CLAIMS.md(動画で説明すべき内容、ポジショニング、避けるべきフレーズ、承認が必要な主張)product.yaml:positioning,never_say,names(正規名からレガシー文字列へのマッピング)、banned_termssources/<role>/およびsources.lock(source-reconによってピン留め。不足している場合は先にsource-reconを実行。引用はロックされたコミットを指す必要があるため)
1. 主張をリストアップする
lines.tsvの各行を、含まれる主張に分割します。「Acme Tasksはあなたのカレンダーを読み取り、期限切れのタスクを明日に移動します」は2つの主張です:カレンダーを読み取ることと、期限切れのタスクを移動することです。SOURCES.mdとチャプターから、画面ごと、画面上のアクションごとに1つの主張を追加します(「Plan my dayをクリックすると、3つの提案を含むプランナーが開く」)。
それらの主張が提起する質問を、コードが回答できるように表現して書き出します:何がこれをトリガーするのか、何が保存されるのか、どのオプションが存在するのか、ユーザーは何をどこで見るのか、サーバー上でのみ何が起こるのか。
2. コードとドキュメントから回答する
読み取り専用のサブエージェントを、製品領域ごとに(フロントエンド動作、各バックエンド、ドキュメント)、references/product-facts-prompt.md のプロンプトを指定して並列起動します。sources/<role>/ を指すよう設定し、ユーザーのチェックアウトは決して指さないようにします。これにより行番号がロックと一致します。これらのエージェントはコードまたはドキュメントからのみ回答し、すべての事実に引用を付け、「見つかりません」と推測せずに答えます。
3. 各主張を分類する
| 可視性 | 意味 | 動画で可能なこと |
|---|---|---|
ui | フロントエンドによってレンダリングされる。テンプレートまたはi18n行を引用 | 表示し、ナレーションできる |
backend | サーバー上で真。画面上に何も表示されない | ナレーションできるが、UIは決して描画しない |
docs | ドキュメントのみが言及 | ドキュメントのURLと共にナレーションできる。可能な場合はコードが同意するか確認 |
mock | 製品UIではない、デザインされた要素(電話画面、エンドカード、生成テキスト) | BRIEF内でデザイン済みとマークして表示できる |
| 判定 | 意味 |
|---|---|
backed | ソースがまさにこれを言っている |
approved | 署名が必要(制限付き、未リリース、CLAIMS.mdにリストされた主張)で、レビュー担当者がCLAIMS.mdで承認した |
needs-approval | 真だが、制限付き、ゲート付き、未リリース、またはCLAIMS.mdにリストされている。レビュー担当者の承認待ち |
rewrite | 部分的に真。ノートに裏付けのある表現を提案する |
cut | 真ではない、またはソースが見つからない |
unbacked | まだチェックされていない |
mock | mock の可視性を持つ場合のみ |
ナレーション行で合格できるのは backed と approved のみです。制限付き機能(特定のロール、プラン、または内部チームにのみ表示される機能)、フラグの背後にある機能、またはマージされていないブランチ上の機能は、レビュー担当者がCLAIMS.mdで承認するまで needs-approval となり、BRIEFには制限付きであることが注記されます。これは元の制作現場で実際に発生しました:内部スタッフのみが見られる機能が、レビュー担当者のリクエストにより表示され、そのようにマークされました。
4. 裏付けのない部分を修正する
- 書き直し:部分的に真の文を、ソースがサポートする最も強力なバージョンに書き換えます。書き手が意図した意味は維持し、メカニズムを実際のものに変更します。
- 削除:ソースがない部分は削除します。曖昧に和らげてはいけません。曖昧な主張も依然として主張です。
- ラベルの変動を決して許さない。「説明用」とマークされたデザイン要素は、ラベルなしバージョンが行う主張を再確認せずに、後で美的理由からそのラベルを失ってはいけません。
- ポジショニングがドキュメントに優先する。デッキやPRDが
never_sayやCLAIMS.mdで禁止されていることを言っている場合、ルールが優先され文章が変更されます。 - 現在の名前のみを使用する。ライブUIやコードにまだレガシー文字列が表示されている場合でも、
product.yamlのnamesにある正規名を使用します。lines.tsv、仕様、テンプレートからすべてのレガシー文字列とbanned_termsエントリ(競合他社、チームが画面に表示しないようにしているサードパーティベンダー、実際の顧客)をgrepし、それぞれ修正します。
5. リクエストが製品と矛盾する場合
ブリーフやレビュー担当者がコードがサポートしていないことを要求した場合、偽物を作成したり、黙って破棄したりしないでください。選択肢と推奨デフォルトを含む1つのクローズドクエスチョンを提示し、ラウンドごとに最大3つの質問に抑えます。なぜなら、拒否のオープンエンドリストは回答されず、その沈黙が誰も行っていない決定になってしまうからです。「現実のみ」パターンは以下の通りです:
ブリーフには、Acme Tasksが会議室を自分で予約するとあります。コードはタスクを作成し、会議室のカレンダーにリンクするのみです(frontend/src/rooms/LinkRoom.tsx:22@1a2b3c4)。予約はカレンダーアプリで行われます。どれにしますか?
- 現実のみ(推奨):リンクステップを表示し、「会議室のカレンダーにリンクします」と言う。
- カレンダーアプリの予約画面をデザイン要素としてラベル付きで表示し、カレンダーのステップとしてナレーションする。
- そのビートを削除する。
回答をCLAIMS.mdに記録し、それに基づいて判定を設定します。
6. TRUTH.md を書く
# 真実: <video>
ロック: frontend main@1a2b3c4, backend main@5d6e7f8。チェック日: 2026-01-12。
| id | 文 | ソース | 可視性 | 判定 | ノート |
|---|---|---|---|---|---|
| N1 | Acme Tasksはあなたのカレンダーから一日を計画します。 | frontend/src/planner/plan.ts:31@1a2b3c4; https://docs.example.com/planner | ui | backed | |
| N2 | 期限切れのタスクは深夜に明日に移動します。 | backend/jobs/rollover.py:12-30@5d6e7f8 | backend | backed | 画面には表示されない |
| screen:board | 3つのタスクがあり、1つが期限切れのボード | frontend/src/pages/board/BoardPage.tsx:14@1a2b3c4 | ui | backed | |
| screen:call | 顧客との電話 | (designed) | mock | mock | BRIEFにマークあり |
## 未解決の質問
1. <推奨回答付きのクローズドクエスチョン>
lines.tsvのline idごとに1行。文は正確にコピーします(チェックが比較するため、真実パス後にラインを編集すると、再検証するまで失敗します)。画面ごとに1行、idは screen:<name> でSOURCES.mdと一致させます。複数の引用は1つのセルに ; で区切って入れます。
7. チェックする
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/product-truth/scripts/truth_check.py" <video_dir>
これは以下の場合に失敗します:行に対応する行がない、文が変更された、ナレーション行の判定がbackedまたはapproved以外、引用のロールがロックされていない、shaがロックされたものと一致しない(コードが移動したので再検証)、ファイルがエクスポートに含まれていない、行がファイルの末尾を超えている。すべての失敗を修正します。チェック自体は編集しないでください。
ユーザーに報告します:裏付けられた行と画面の数、書き直したり削除した内容(理由付き)、承認待ちのもの、および未解決の質問。