ソースレコン
ビデオのすべてのピクセルとすべての文は、後でコードと照合されます。そのため、コードは正しいコードでなければなりません。 このスキルが生まれた本番環境では、メインのフロントエンドチェックアウトが本番環境より約2ヶ月遅れており、現在のコードは誰も3日間見ていない別のワークツリーにありました。誰も気づかないうちに、古いコードから1つのビデオの3つのバージョンが再構築されました。このスキルは、そのようなことが二度と起こらないようにするために存在します。まずソースを固定し、それらが本番環境であることを証明し、次に画面をファイルにマッピングします。
読み取り専用で作業します。コードを読み取ります。ユーザーのリポジトリで編集、チェックアウト、フェッチ、またはワークツリーの作成は決して行いません。ユーザーの作業ツリーには、コミットされていない作業が含まれている可能性があり、チェックアウトやフェッチは、ユーザーが依頼していない状態を変更します。
1. ソースを固定する
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/source-recon/scripts/fetch_sources.py" <product_dir>
product.yaml から sources: を読み取り、ロールごとに次の処理を行います。
url:: ブランチをsources/.git-cache/<role>.gitにシャロークローンし、エクスポートします。path:(git リポジトリへのパス):<branch>とorigin/<branch>の新しい方のgit archiveを実行します。ローカルブランチが origin より遅れているか分岐している場合、origin 参照が1週間以上前にフェッチされた場合、同じリポジトリの別のワークツリーがエクスポートより新しい場合に警告します。path:(git リポジトリではない): ファイルのハッシュによってコピーされ固定されます("pinned": falseのため、それへの引用は警告なしに古くなる可能性があります。git ソースを推奨します)。
エクスポートは sources/<role>/ に読み取り専用で保存され、sources.lock にコミットが記録されます。ディスク上にない(プロダクトリポジトリの新しいクローン)ロックされたロールは、ロックされたコミットで復元されるため、引用は同じ行を指し続けます。表示されるすべての note: 行を読み、先に進む前にそれに従って行動してください。それぞれが、エクスポートが本番環境ではない可能性を示しています。
下流のすべての引用は <role>/<path>:<line>@<short sha> を使用します。ここで、パスはリポジトリルートからの相対パス(sources/<role>/<path> が存在する)であり、sha はロックされたものです。
2. それが本番環境であることを証明する
ブランチ名は証明にはなりません。本番環境とは、デプロイパイプラインが最後にビルドしたものです。画面をマッピングする前に、強度順に、どのコミットがライブであるかを確立します。
- リリースレコード: リリースタグ、デプロイログ、デプロイリポジトリ内の "last deployed sha" ファイル。
- デプロイパイプライ構成: ビルド元のブランド、およびそのビルド引数(ビルドに組み込まれた環境変数はブランディングを変更したり機能を隠したりする可能性があります)。
- チームがデプロイされていると確認した最新のブランチ。
git worktree list、ブランチの日付、merge-baseと照合します。
正確なコマンドと落とし穴(古いリモート参照、フィーチャーフラグ、レンダリング内容を変更するビルド引数)については、references/freshness.md を参照してください。本番コミットを確認できない場合は、SOURCES.md の先頭にその旨を記述し(「production commit unconfirmed」)、ユーザーに推奨される回答を含むクローズドクエスチョンを1つ質問します。例:「Export origin/develop (newest, contains main) as production? Recommended: yes, it is what the deploy workflow builds.」
ユーザーが別のブランチを確認した場合は、product.yaml の branch: を変更し、fetch_sources.py <product_dir> --refresh --role <role> を実行します(ビデオが既にこのソースを引用している場合は、最初に changed_since.py(セクション6)を実行します)。
3. 各画面をマッピングする
ビデオの BRIEF.md(チャプター)と COVERAGE.md から画面と状態を取得します。画面ごと、またはコンポーネントを共有する画面の小さなグループごとに、並行して読み取り専用の Explore サブエージェントを1つ起動します。各サブエージェントには、references/recon-prompt.md のプロンプトを指定し、sources/<role>/(固定されたエクスポート。ユーザーのチェックアウトは不可)をポイントします。これにより、返されるすべての行番号がロックと一致します。
各サブエージェントは、引用付きで、次の情報を返します。ルート、ページおよび子コンポーネント(テンプレート、ロジック、スタイルファイル)、ビデオの言語における i18n キーとその正確な文字列、何をレンダリングするかを決定する状態(デフォルト、フラグ、フィーチャーゲート、空の状態、権限チェック)、使用されているアイコンセットとアセット、および未リリース、ゲート付き、または制限されているように見えるもの。
次に、コピーを自分で本番環境と照合します。各画面につき2~3の文字列を、手持ちの参照(録画、復元されたキャプチャ、ドキュメント)とスポットチェックします。異なる文字列がある場合は、エクスポートが本番環境でないか、画面がフラグの背後にあることを意味します。SOURCES.md を書き込む前に解決してください。
4. SOURCES.md を書き込む
ビデオごとに1つのファイル、videos/<video>/SOURCES.md にあります。
# Sources: <video>
Locked: frontend main@1a2b3c4 (2026-01-12), backend main@5d6e7f8 (2026-01-10)
Production: confirmed by <release tag v4.2.0 | deploy workflow builds main | team confirmation>
| screen | route | components | citation |
|---|---|---|---|
| Board, empty | /board | BoardPage > TaskList > EmptyState | frontend/src/pages/board/BoardPage.tsx:14@1a2b3c4 |
## Board, empty
- Strings: `board.empty.title` "Nothing planned yet" (frontend/src/i18n/en.json:88@1a2b3c4)
- State: renders when `tasks.length === 0` (frontend/src/pages/board/TaskList.tsx:41@1a2b3c4)
- Icons: lucide `calendar-plus` (frontend/src/pages/board/EmptyState.tsx:9@1a2b3c4)
- Flags or gates: none found
- Not found: <anything the brief needs that the code does not have>
## No-code references
<what exists for each screen without code, see section 5>
引用がない画面はビデオに含めません。「Not found」の下にリストし、ユーザーに伝えてください。画面をでっち上げることは、レビュー担当者が決して許さない唯一のミスです。なぜなら、存在しないプロダクトを示すことになるからです。
5. コード以外の参照をリストする
コードが表示できない画面(サードパーティUI、ランタイム出力、リポジトリにないバックエンド、またはフロントエンドコードがまったくない場合)については、利用可能なものを優先順位順にリストします。references/ 内の分析された画面録画、過去のセッションのトランスクリプトから復元可能なキャプチャ、本番環境と同様にビルドされたアプリのローカルインスタンス、公開ドキュメント、スクリーンショット。ここでは自分でキャプチャしないでください。それは ui-reference-capture の役割です。レビュー担当者の個人ブラウザに頼ることは絶対にしないでください。
6. コードが変更された場合
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/source-recon/scripts/changed_since.py" <product_dir> [--offline]
ロックされた各コミットと現在のブランチヘッドを比較し、変更されたファイルを引用しているすべてのビデオ(およびキットファイル)の SOURCES.md、TRUTH.md、スペック、video/src/ をリストし、正確な行が変更された引用をマークします。何も移動しません。--refresh の前に実行します。ロックとヘッドを比較し、リフレッシュするとそれらが等しくなるため、その後は変更内容のリストが失われます(スクリプトは代わりにヒントを出力します)。そのリストをユーザーに表示し、新しいコードが必要な場合は、fetch_sources.py --refresh を実行し、影響を受ける画面に対して ui-spec-from-code を、影響を受ける行に対して product-truth を再実行します。変更が引用されていないビデオはそのまま残されます。
ルールとその理由
- エクスポートを読み、ロックを引用する。 異なるチェックアウトからの行番号は、次回のリフレッシュ後に暗黙的に間違ったコードを指します。
- コード内で見つけた秘密を決して印刷しない。 フロントエンドにはキーやトークンが含まれていることがよくあります。ファイルと行のみを報告し、それをユーザーにとってのセキュリティ上の発見事項として扱います。
- 未リリース、ゲート付き、または制限された機能も事実です。 SOURCES.md にマークします(
gate: <flag>、restricted: <who sees it>)。product-truth が、ビデオでそれらを表示できるかどうかを決定します。通常はレビュー担当者の承認が必要です。 - 実際のデータは含めない。 リポジトリ内のフィクスチャやシードファイルには、実際の顧客名が含まれている可能性があります。それらの構造を引用し、値は引用しないでください。