Skip to content

Huruikagi/pc-build-planner / .agents/skills/site-extraction-authoring

site-extraction-authoring

Verified

開発者が指定した一つのページから、利用条件の確認結果を記録し、必要に応じて実ページ資料を保存せずに進めるサイト固有抽出の作成、登録、再生成を安全に進める。

FileKindSize
SKILL.mdskill md31.1 KB
references/verification.mdmarkdown24.8 KB

references/verification.md

View on GitHub
# Skill 手順の固定検証

この手順は `site-extraction-authoring` の操作順、利用条件の探索、限定停止、判断記録を確認するための
固定ケースである。実サイトへアクセスせず、実ページ資料の本文、HTML、画像、
商品値、認証情報をGit管理対象のリポジトリ、判断記録、完了報告へ写さない。資料は
`/.site-extraction-work/` 内のローカル識別子だけで指す。

Skill を作成または更新したら、次の全ケースを順に実行する。各ケースでは、Skill の
出力、実際に作成された判断記録、許可された範囲外の資料を読まなかったことを照合する。
`e2e/capture.spec.ts` や実行時のテストはこの照合の代わりにしない。登録候補ごとの実拡張の検証と
登録実装は `page-capture` が所有するが、Skill はその検証を登録提案の前提として要求する。

## 共通の照合方法

1. 代表URLが空、無効、または対象ページを指さないときだけ、`入力確認` で停止する。この分岐では作業単位を作成せず、利用条件は `未判定` とする。カテゴリ、取得項目、保存資料のローカル識別子、利用条件の根拠、既存登録の識別子が未指定でも停止しない。
2. 有効な代表URLでは、対象サイトの公式な利用条件を探索し、確認に必要なページを閲覧する。見つからない、読めない、曖昧、または適用が不明な事実を、追加許可の要求や全体停止へ変換しない。
3. 新しい作業単位の `decision.md` に、対象ページ URL、製品カテゴリ、取得したい項目、確認日、根拠URLまたは確認できなかった事実、確認した事実、対象作業への解釈、不明点、作業ごとの継続または停止判断を分けて記録する。ページ本文、HTML、画像、商品値、認証情報は記録しない。
4. 明確な禁止根拠がある作業と依存する後続だけを停止する。閲覧、実ページ資料の保存、自作の抽出ルール、架空fixture、自動検証、確認用ビルドとリンク集、実サイト手動確認を一つの作業として混同しない。保存条件を確認できない場合は、保存しなかった事実、不明点、保存を省略する判断を残し、`page.html` を作らない。この場合も独立する作業を止めない。
5. 作業単位は `host`、正規化URLの安定ハッシュ、UTC実行時刻で導出する。同名単位が既に存在する、作業領域を作れない、または `decision.md` の保存に失敗する場合、既存・部分作成済みの単位を上書きも自動削除もせず、候補、検証、登録、既存登録の更新を開始しない。

作業単位は `host`、正規化URLの安定ハッシュ、UTC実行時刻で導出し、各単位に `page.html`、
`decision.md`、`candidate.md`、`verification.md` が用途別に残ることを照合する。同名単位が既に
存在する場合、または保存に失敗した場合は、既存・部分作成済みの単位を上書きも自動削除もせず、
登録または更新を変更しない停止結果を照合する。以前の作業領域が失われた場合は、以前の判断を
流用せず、利用条件の再確認と新しい単位での再取得から再開することを照合する。

## 固定ケース

| ケース | 入力と許可される読取範囲 | 期待する結果 | 記録先ごとの必要な行 |
| --- | --- | --- | --- |
| 明確な閲覧禁止 | 有効な代表URLと、閲覧を明確に禁止する公式根拠。入力と利用条件の根拠だけを読む。 | `対象`、`停止段階: 利用条件の判定`、`理由`、`次に必要なもの` の四項目で閲覧と依存後続を停止する。架空fixture、自動検証、確認用ビルドとリンク集に独立して進める余地があれば停止しない。 | `decision.md` に根拠URL、確認日、確認した事実、閲覧への適用理由、閲覧と依存後続の停止判断を残す。 |
| 不明点を記録して継続 | 有効な代表URLと、利用条件が未発見、読めない、曖昧、または適用不明の状態。探索に必要なページを閲覧する。 | 明確な禁止根拠がないため、追加の許可根拠を求めず、閲覧、自作の抽出ルール、架空fixture、自動検証、確認用ビルドとリンク集、実サイト手動確認を継続する。 | `decision.md` に探索範囲、確認できなかった事実または不明点、作業ごとの継続判断を残す。許可や根拠URLを捏造しない。 |
| URL起点の対象判断 | 有効な代表URLだけを与える。カテゴリまたは取得項目を併せて指定した場合は、その指定も判断根拠として読む。利用条件の確認後に利用できる対象ページ資料から、既存カテゴリ、共通項目、対象カテゴリの既存属性、未明記項目を区別する。 | カテゴリまたは項目を未指定であることだけで停止しない。カテゴリ、対象項目、アクセス、または製品根拠を自力で確定できない場合だけ、候補を作らず、`確認済み範囲`、`未解決の理由`、`必要な確認` を一括して返す。 | 直接読める項目と、既存カテゴリ属性だけを根拠とともに照合する。対象外属性と未明記値を候補へ補わず、推測しないことを照合する。 |
| 任意の実ページ資料保存 | 有効な代表URLと、閲覧は継続できるが保存に適用する条件を確認できない状態。 | 実ページ資料を保存せず、`page.html` を作らない。保存の省略を閲覧、自作の抽出ルール、架空fixture、自動検証、確認用ビルドとリンク集、実サイト手動確認の停止へ広げない。 | `decision.md` に保存しなかった事実、保存条件の不明点、保存を省略する判断、独立作業の継続判断を残す。 |
| 代表URLの入力不備または項目欠損 | **代表URLの入力不備:** 代表URLが空、無効、または対象ページを指さない。カテゴリ、取得項目、保存資料、利用条件の根拠を未指定であることだけでは停止しない。**項目欠損:** 利用条件の探索結果と作業ごとの判断を新規作業単位の `decision.md` に記録した後に、同じ単位の指定資料だけを読み、確定した要求項目を直接検出できるかだけを確認する。 | 代表URLの入力不備は `停止段階: 入力確認`、項目欠損は `停止段階: 要求項目の確認` の停止結果を返す。いずれも登録可能な候補、コード変更、検証、登録を出さない。 | **代表URLの入力不備:** 完了記録に `利用条件: 未判定` と `作業単位: 作成なし` を記し、作業単位がないことを確認する。**項目欠損:** 新規作業単位の `decision.md` には、共通の入力・資料識別子・探索結果に加え、`停止段階`、`不足または欠損項目`、`停止理由`、`次に必要なもの`、`登録結果: 未登録` を含める。 |
| 未対応属性 | 利用条件の探索結果と作業ごとの判断を新規作業単位の `decision.md` に記録した後に、同じ単位の指定資料で、対象カテゴリの既存 `CATEGORY_ATTRIBUTES` にない属性キーを確認する。入力、利用条件の根拠、指定保存資料だけを読む。 | `停止段階: 候補の適合確認` の停止結果を返す。候補全体を登録対象にせず、共通項目への代替、推測、コード変更、検証、登録を出さない。 | 共通の入力・資料識別子・探索結果に加え、`停止段階: 候補の適合確認`、`対象: 未対応属性`、`停止理由`、`次に必要なもの: 対象カテゴリに既に定義された属性キー`、`登録結果: 未登録` を同じ `decision.md` に含める。 |
| 未明記値 | 利用条件の探索結果と作業ごとの判断を新規作業単位の `decision.md` に記録した後に、同じ単位の指定資料で、取得したい項目または許可属性の値が明記されていないことを確認する。入力、利用条件の根拠、指定保存資料だけを読む。 | `停止段階: 候補の適合確認` の停止結果を返す。候補全体を登録対象にせず、共通項目への代替、推測、コード変更、検証、登録を出さない。 | 共通の入力・資料識別子・探索結果に加え、`停止段階: 候補の適合確認`、`対象: 未明記値`、`停止理由`、`次に必要なもの: 値が明記された保存済みページ資料`、`登録結果: 未登録` を同じ `decision.md` に含める。 |
| 保存資料照合不一致 | 利用条件の探索結果と作業ごとの判断を記録し、代表URLから確認した指定項目を直接読む候補と、その期待する未加工値の一つ以上に一致しない保存資料。入力、利用条件の根拠、指定保存資料だけを読む。 | `verification.md` に不一致の対象項目と安全な失敗理由、`検証結果: 不合格`、`登録結果: 未登録` を残す。登録可能な候補、登録差分、更新提案、候補編集への引渡し、コード変更を出さない。 | `decision.md` は共通の入力・資料識別子・探索結果だけとし、`verification.md` に不一致の対象項目と安全な失敗理由、`検証結果: 不合格`、`登録結果: 未登録` を含める。ページ内容、商品値、selector、期待値はどちらにも記録しない。 |
| 保存資料照合全項目一致(中間) | 利用条件の探索結果と作業ごとの判断を記録し、代表URLから確認した共通項目または対象カテゴリで既に許可された属性を明記する保存資料。候補の各期待未加工値と、対応する selector が直接読んだ未加工値の全件一致を同じケースで照合する。入力、利用条件の根拠、指定保存資料だけを読む。 | 全項目一致は、実拡張検証待ちの中間照合合格としてだけ扱う。`page-capture` 所有の実拡張検証、候補追加前の汎用シナリオ記録、実在データを含まない fixture、`pnpm validate` の既存汎用シナリオ維持が全て合格するまで、登録・更新提案、候補編集への引渡し、登録差分、最終的な合格結果を出さない。Task 3.2 ではその後段を実装も実行もしない。 | `decision.md` は共通の入力・資料識別子・探索結果だけとする。`verification.md` に `照合: 全項目一致`、`保存資料照合結果: 合格(実拡張検証待ち)`、`登録結果: 未登録` を含め、`検証結果: 合格`、`実拡張検証結果: 合格`、`登録結果: 登録可能な候補を提案` は含めない。selector、期待値、ページ内容、商品値はどちらにも記録しない。 |
| 再生成の候補生成失敗 | 有効な代表URLから既存の検証済み登録と利用できるローカル記録を探索し、新しい作業単位で利用条件を再探索して判断を記録した後に、要求項目の欠損または候補の適合失敗を確認する。見つからない記録は流用しない。 | 初回と同じ候補生成の停止結果を返す。項目欠損・適合失敗は既存どおり `decision.md` だけに記録し、`verification.md` へ失敗を重複記録しない。既存登録を保持し、差分、未確認候補による置換、登録または更新の提案を出さない。 | 新しい `decision.md` に探索結果、`根拠 URL`、`確認日`、候補生成の停止段階、対象、停止理由、次に必要なもの、`登録結果: 未登録`、`既存登録: 保持` を含める。`verification.md` は候補生成失敗の記録先にしない。 |
| 再生成の保存資料照合以降の失敗 | 有効な代表URLから既存の検証済み登録と利用できるローカル記録を探索し、新しい作業単位で利用条件を再探索して判断を記録した後、候補生成を通過してから、保存資料照合、実拡張検証、`pnpm validate`、または実サイト手動確認を失敗させる。 | 保存資料照合以降の失敗は `verification.md` だけに記録する。既存登録を保持し、差分、未確認候補による置換、登録または更新の提案を出さない。 | `decision.md` は新しい探索結果、`根拠 URL`、`確認日` を含む共通判断行だけとする。`verification.md` に `再生成日時`、保存資料を使った場合だけ `保存資料識別子`、`既存登録: 保持`、`失敗段階`、`停止理由`、`次に必要なもの`、`検証結果: 不合格`、`登録結果: 未登録` を含める。 |
| 再生成で固有規則だけが明確に禁止 | 有効な代表URLから既存登録を探索し、固有規則の実行だけに適用される明確な禁止根拠と、汎用抽出には明確な禁止がないことを確認する。 | 既存のコードと検証済み状態を保持し、静的な選択を `suppressed` にして固有規則を選ばず、汎用抽出へのフォールバックだけを提案する。候補、登録、更新は出さない。 | `decision.md` に根拠URL、確認日、固有規則への適用、汎用抽出に禁止がない確認、`既存登録: 保持`、`静的選択: suppressed` を残す。実行時が利用条件、作業領域、判断記録を読まないことを確認する。 |
| 再生成で汎用抽出にも明確な禁止 | 有効な代表URLから既存登録を探索し、固有規則と汎用抽出の両方に適用される明確な禁止根拠を確認する。 | Capture と依存後続を停止し、既存登録を保持する。汎用フォールバック、候補、登録、更新は提案しない。 | `decision.md` に根拠URL、確認日、両方の作業への適用、停止判断、`既存登録: 保持` を残す。 |
| 作業単位の衝突または保存失敗 | 許可済み判断と有効な代表URLから導出した新規作業単位の最終パスが存在する、または `decision.md`、`page.html`、`candidate.md`、`verification.md` のいずれかの新規保存が失敗する状態。既存単位の内容は読取・変更しない。 | `停止段階: ローカル作業領域` の停止結果を返す。既存または部分作成済み単位の上書き、自動削除、登録、既存登録の更新を出さない。 | 判断記録へ追記可能な保存失敗では、新規単位の安全な識別子、失敗段階、停止理由、次に必要なもの、`登録結果: 未登録` を照合する。`decision.md` の保存失敗では判断記録なし、取得または `page.html` の保存失敗では取得前の共通判断行だけとし、いずれも未登録、停止出力、後続操作なし、部分作成済み単位の非変更を独立して照合する。既存単位には変更がないことを確認する。 |
| 作業領域の消失 | 以前の作業単位または作業領域が存在しない状態で、有効な代表URLを与える。以前の判断、資料、候補、検証結果は読まない。 | 以前の判断を流用せず、利用条件を改めて探索して結果と作業ごとの判断を記録する。明確な禁止根拠が当該作業に適用されなければ、新しい作業単位を作成して再取得から再開する。明確な禁止根拠がある作業と依存する後続だけを停止する。 | 新しい `decision.md` に確認した事実、対象作業への解釈、不明点、作業ごとの継続または停止判断、根拠 URL または確認できなかった事実、確認日、対象 URL を残す。以前の単位を再作成、上書き、または削除しないことを確認する。 |

## 段階的な登録簿差分の固定照合

`validated-site-extraction-registration` の二段階を、実サイトへアクセスせず、実在のページ内容または商品値を記録せずに次の固定ケースで照合する。

| ケース | 入力と許可される読取範囲 | 期待する結果 | 照合する境界 |
| --- | --- | --- | --- |
| 一意な対象の仮適用 | 根拠から一意に確定したメーカー、公式ドメイン、既存カテゴリ、既存登録簿、および実在データを含まないfixture。 | 同じ安定した識別子に、最小の追加または更新差分、ページ識別条件、共通項目と既存カテゴリ属性だけを読む規則、fixture、汎用フォールバックを一組にし、候補専用実拡張E2Eへだけ仮適用する。 | 本番登録簿、実行時対象、未確認handoffの所有を変更しない。未明記値、新しい属性、確認済み値を出力しない。 |
| メーカーまたはカテゴリが非一意 | カテゴリまたはメーカーを一意に示さない根拠。 | 登録簿差分も仮適用入力も作らず、`確認済み範囲`、`未解決の理由`、`必要な確認` を返す。 | 推測、登録簿の変更、実行時対象の変更を行わない。 |
| 仮適用の検証失敗 | 仮適用入力と、対象項目、由来、未確認handoff、汎用フォールバック、既存汎用シナリオ、または `pnpm validate` のいずれかの安全な失敗結果。 | `verification.md` に失敗した確認項目、`実拡張検証結果: 不合格`、`登録結果: 未登録` を残す。 | 失敗した結果、合格前候補、または別の差分から登録可能な入力を作らない。 |
| 仮適用の全検証合格 | 同じ識別子の保存資料照合、候補専用実拡張E2E、既存汎用シナリオ、`pnpm validate` の安全な合格結果。 | 合格した同じ一組だけを、登録可能な入力として `page-capture` へ引き渡す。 | 登録簿への反映、実行時選択、未確認handoffの実装と所有は `page-capture` に残る。実サイト手動確認の状態を対応済みの結論にしない。 |

## 登録候補ごとの実拡張照合

初回登録または再生成で登録・更新の候補を提案する前に、`page-capture` が所有する既存の
`e2e/capture.spec.ts` を、実在データを含まない fixture で拡張して実行する。Skill の固定ケースと
この照合はどちらも必要であり、片方で他方を代用しない。fixture には実サイト由来の本文、HTML、画像、
商品値、認証情報を入れない。

1. 候補追加前に、同じ fixture の既存汎用抽出をビルド済み拡張と拡張アイコン操作から実行し、安全なシナリオ識別子と結果だけを `verification.md` に残す。
2. 候補追加後は、指定項目が `site-specific` の由来と安定した `sourceLabel` を持ち、結果と candidate-capture-handoff の分類・属性が未確認のままであることを確認する。属性がある場合は許可キーだけを確認し、由来ラベルが handoff、候補の永続データ、確認済み値に保存されず、`confirmed` への昇格がないことを確認する。
3. 固有 selector が値を返さない状態では、候補を追加せず例外を外へ出さず、既存の JSON-LD、meta、構造 collector の汎用結果が残ることを確認する。資料に明記されない値が候補または handoff にないことも確認する。
4. `pnpm validate` で、記録した汎用シナリオを含む既存シナリオが維持されることを確認する。保存資料の指定項目検証とこの全照合が合格した場合だけ、`verification.md` に `実拡張検証結果: 合格` と `登録結果: 登録可能な候補を提案` を残せる。

再生成では、代表URLから既存の検証済み登録と利用できるローカル記録を探索し、利用条件を改めて探索する。確認した事実、対象作業への解釈、不明点、作業ごとの継続または停止判断、根拠 URL または確認できなかった事実、確認日を新しい `decision.md` に記録した後に候補生成から上の全照合を順に繰り返す。明確な禁止根拠が当該作業に適用されなければ、未発見、不明、曖昧さを理由に候補生成または独立する後続の照合を停止しない。固有規則の実行だけが明確に禁止され、汎用抽出に明確な禁止が適用されない場合だけ、既存登録を保持して静的選択を `suppressed` にし、汎用抽出へのフォールバックを提案する。汎用抽出にも明確な禁止が適用される場合は、Capture と依存後続を停止し、フォールバックを提案しない。実行時はこの事前に決めた静的選択とフォールバックだけを消費し、利用条件、作業領域、判断記録を読まない。候補生成中の項目欠損・適合失敗は `decision.md` にだけ記録し、保存資料照合、実拡張検証、`pnpm validate`、または実サイト手動確認の失敗は新しい `verification.md` にだけ `再生成日時`、保存資料を使った場合だけ `保存資料識別子`、`既存登録: 保持`、`失敗段階`、`停止理由`、`次に必要なもの`、`検証結果: 不合格`、`登録結果: 未登録` を記録する。どの失敗でも既存の検証済み登録を保持し、更新差分、未確認候補による置換、登録または更新の提案を出してはならない。

## 確認用成果物と実サイト手動確認の照合

実在のサイト、URL、ページ資料、商品値、selectorを固定ケースや完了記録へ入れず、`page-capture` 所有の実拡張E2Eの安全な結果と確認用成果物の記録だけを照合する。

| ケース | 入力と許可される読取範囲 | 期待する結果 | 記録先ごとの必要な行 |
| --- | --- | --- | --- |
| 自動検証不合格 | 実在データを含まないfixture、実拡張E2Eの安全な失敗結果、または `pnpm validate` の失敗結果だけを読む。 | 対象項目、表示、汎用フォールバックのいずれかを満たさない候補を検証済みとして扱わず、確認用ビルドまたはリンク集を出さない。 | `verification.md` に安全な失敗した確認項目、`実拡張検証結果: 不合格`、`登録結果: 未登録` を残す。 |
| 自動検証済み・実サイト未確認 | 実在データを含まないfixtureによる対象項目、表示、汎用フォールバックのE2E合格結果、`pnpm validate` の合格結果、代表URL、カテゴリ、確認項目、ビルド識別子だけを読む。 | 確認用ビルドと、代表URL、カテゴリ、確認項目、拡張操作手順だけを含む通常のリンク集を引き渡す。リンク先を埋め込まず、自動で開いたり巡回したりせず、実サイト対応済みとしない。 | `verification.md` に `状態: 自動検証済み・実サイト未確認`、確認用ビルドとリンク集の安全な識別子、代表URL、対象カテゴリ、確認項目、引渡し日時を残す。 |
| 実サイト手動確認 | 確認用成果物、対象URL、確認日時、項目ごとの成功・不一致・未確認だけを読む。 | 未確認があれば `MANUAL_VERIFY_REQUIRED` として完了を認定しない。全項目成功だけを成功とし、不一致は不合格として修正または再生成へ戻す。 | `verification.md` に対象URL、確認用ビルドの安全な識別子、確認日時、項目ごとの状態を残す。未確認では `MANUAL_VERIFY_REQUIRED`、不一致では `実サイト手動確認: 不一致` と `検証結果: 不合格`、成功では `実サイト手動確認: 成功` を残す。 |

## 完了記録

全固定ケースの後、ケースごとに次の形式で完了記録を残す。実在の URL、資料内容、
商品値、selector は書かない。

```text
ケース: <固定ケース表のケース名>
許可読取範囲: <読んだ入力と根拠・資料識別子だけ>
Skill出力: <停止段階と未登録 | 取得完了と未登録 | 保存資料照合合格と未登録 | 登録可能な候補を提案>
判断記録照合: <必要な行がそろう | 無効な記録先のため記録なしを確認>
非読取照合: <保存資料を読まない | 後続入力を読まない | 指定資料だけを読む>
登録可否: <未登録 | 実拡張検証後に登録可能な候補を提案>
結果: 合格 | 不合格
```

一つでも期待結果、判断記録、読取範囲が一致しなければ `結果: 不合格` とし、
登録可能な候補、登録、既存登録の置換へ進まない。保存資料照合全項目一致(中間)の `合格` は
中間照合だけを示し、`page-capture` の実拡張検証、`pnpm validate`、または登録可能性を意味しない。
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall