build-list

手順

セットアップ状態。 この組織ではまだ設定されていません。Readme サブページを一度読み込み、組織のデフォルトの列プラン、ソースの優先順位、アクティベーションのデフォルトを取得してください。（セットアップ後に swan-update-skill でこの段落を書き換え、今後の実行では現在の設定を読み込み、再確認を省略するようにしてください。）

---

メンタルモデル — 列のラダー

すべてのリスト作成はテーブルです。各列には4つのプロパティがあります。

1. 入力 — 参照する前段の列。
2. コスト層 — 無料のフィルター／無料の除外／低コストのエンリッチメント／AI リサーチ／有料の連絡先データ。
3. 実行条件 — どの上流の Boolean ゲートが実行を許可するか（ほとんどの場合は icp_pass）。
4. フォールバック — 解決できない場合に書き込む内容。

「検索して、結果を見て何をするか考える」ことはしません。列プランを作成してユーザーに提示し、その後で実行します。低コストのフィルターで大半の行を除外し、残った行だけが高コストの列に進みます。

---

ステップ 0 — 依頼内容を固め、曖昧さには異議を唱える

ツールを呼び出す前に、依頼内容を WHO + WHAT + WHY + SIZE として言い換えて確認します。

• WHO — どの ICP セグメントと、どのペルソナか。組織に複数のセグメントがあり、ユーザーが選んでいない場合は質問します。
• WHAT — どの条件が必須で、どれがあれば望ましい条件か。
• WHY — どの施策か（コールド一斉配信、ABM、シグナル起点、イベント後のフォローアップ、競合からの切り替え）。
• SIZE — 目標の行数。

依頼内容が組織の保存済み ICP セグメントと矛盾する場合は、はっきりと異議を唱えてください。 組織がエンジニアリングチーム向けのオブザーバビリティを販売しているのに、「オハイオ州の歯科医のリストを作って」と言われても、黙って従ってはいけません。対象外の実験なのか、依頼の間違いなのかを指摘して確認してください。

依頼が「X に関心を持つかもしれない SaaS 企業をたくさん」なら、それは依頼内容として不十分です。どのサブセグメントか、どの規模帯か、どのシグナルかを質問してください。

---

ステップ 1 — まず対象規模を見積もる

全件を取得する前に、必ず size: 1 で規模の見積もりを実行し、対象の件数を低コストで把握してください。候補のフィルターを設定した swan-fetch-businesses を size: 1 で使用し、total フィールドを確認します。

• 対象企業が50社未満の場合は、先にユーザーに伝えてください。ニッチな市場の候補が少ない場合、通常はフィルターを広げるか、まったく別のソース取得方法（Apify のディレクトリー、ウェブ調査）が必要です。同じクエリを何度も試すべきではありません。
• 5,000社を超える場合は、依頼内容が広すぎます。何かを取得する前に、条件を絞るようユーザーに依頼してください。

先に規模を見積もることで、ツールを20回呼び出した後に対象が存在しないと判明する失敗を防げます。

---

ステップ 2 — 列プランを作成してユーザーに提示する

ソースを取得する前に、列のラダーを作成します。このテンプレートを使い、施策に応じた列を追加し、不要な列は削除してください。

INPUT  (free preview)
  domain, name, employee_band, industry, geo, linkedin_url

FREE ELIMINATION  (0 credits — pure code/formula filters)
  ✗ dedupe_keep         — drop duplicate domains (normalize www, lowercase)
  ✗ in_geo              — hard-filter geo from the preview field
  ✗ in_size_band        — re-filter employee count to the user's exact threshold
  ✗ not_in_crm_active   — drop companies/contacts already in active sequences
  ✗ name_sniff_test     — cheap LLM scan on name+domain: "plausibly fits the brief?"
  → icp_pass = AND(all of the above)

CHEAP ENRICHMENT  (~1 credit each — only IF icp_pass)
  + enriched_headcount  — swan-enrich-company (precise headcount, not band)
  + enriched_hq_city    — confirm geo at city, not state level
  + enriched_tech_stack — if motion depends on technographic signal
  → icp_pass_strict = AND(icp_pass, enriched columns confirm)

AI RESEARCH COLUMNS  (LLM tokens — only IF icp_pass_strict)
  Each column = ONE delegated sub-agent answering ONE narrow question.
  + sells_dtc           — "Does {domain} sell direct-to-consumer? yes/no/unclear"
  + has_signal_X        — "Does {domain} show signal X? yes/no/unclear"
  → research_pass = AND(icp_pass_strict, sells_dtc=yes, ...)

TIER  (0 credits)
  + tier                — A/B/C/D from research_pass + signal strength
  → drop tier=D before any contact work

PEOPLE DISCOVERY  (free preview — only IF tier ∈ {A,B,C})
  + contact_rows        — swan-search-employees, filtered to persona(s)
  → people_pass = persona match + LinkedIn URL present

CONTACT ENRICHMENT  (paid — only IF tier ∈ {A,B} AND people_pass)
  + verified_email      — email waterfall: cheapest → next → coalesce → verify
  + phone               — A-tier only, only if cold-call motion exists

ACTIVATION  (only after explicit user approval of size + cost)
  → save as Swan list, tag with segment + source
  → A-tier: priority outreach (sequence or direct push)
  → B-tier: standard nurture
  → C-tier: low-touch / content

実行前にテーブルをユーザーに提示してください。 列と icp_pass の定義を明確に確認します。ここで30秒かけて確認すれば、後で何時間も見当違いのエンリッチメントに費やさずに済みます。

---

ステップ 3 — ラダーを実行する

各列を上から順に実行します。候補プールが約50行を超えた時点で、swan-execute-codeに切り替えます。プレビュー結果をファイルに出力し、正規化したドメインで統合して、各列をコード処理として実行します。会話のコンテキスト内で数百行を推論しないでください。

よくある失敗を防ぐためのプロバイダー呼び出しルール：

• 列挙型のフィルター値（業種、所在地、従業員規模）には、必ず ​​swan-autocomplete-business-filterを呼び出してください。swan-fetch-businessesより先に実行します。列挙値を推測すると、結果が0件でもエラーが返らない場合や422エラーが発生します。トレースでは10000+と10001+の違いで失敗しました。まずオートコンプリートを実行し、値をそのままコピーしてください。
• マルチツールの計画では、最初に一度だけ**swan-load-tool-schemasでツールスキーマを読み込み**、列挙値をそのままコピーしてください。言い換えないでください。
• カバレッジのために複数のソースを使います。1つのソースではTAMの約60％、2つでは約85％、3つでは約92％をカバーします。デフォルトの順序は、Swanネイティブプレビュー → CRMの失注／解約／休眠データ → 最初の2つで明らかな不足がある場合に限り、専門ソース（Apollo／Apify）です。フィルターを変えて同じプロバイダーを使っても、複数ソースにはなりません。
• まず企業、次に人物です。「SaaS企業の営業担当VP」のような広範な人物検索から始めないでください。まず企業のリストを作成してから、その企業に所属する人物を探します。

---

ステップ 4 — 無料の除外処理が最も重要です

ソースからデータを取得した後、有料の呼び出しを行う前に、コードで無料の除外処理を実行します。

1. ドメインの重複を排除します。 正規化（www.を削除して小文字に変換）し、重複を取り除きます。
2. プレビュー項目を厳密に再フィルタリングします。 ユーザーが「従業員20人以上」を指定したのに、プレビューの従業員規模が「11-50」の場合、その範囲は曖昧です。除外するか、確認のためにエンリッチメント対象としてフラグを付けます。曖昧なプレビュー範囲を、厳密なしきい値を満たす根拠として扱わないでください。
3. 地域を正確に確認します。 州と市は同じではありません。ユーザーがSFを指定したのにプレビューが州レベルの一致を返した場合、エンリッチメント対象としてフラグを付け、条件を満たしたものとして数えないでください。
4. CRMと照合します。 進行中のシーケンスに含まれているものや、最近の未完了商談があるものは除外します。重複したアプローチは到達率を損ないます。
5. 低コストのLLM簡易チェックを行います。 企業名とドメインを対象に、短いLLM処理を1回実行して、「この行は依頼内容に合致しそうか」を確認します。明らかなノイズ（ギターショップ、花屋など）を、クレジットを消費せずに除外できます。

この手順で候補プールの60～80％を除外できます。**このフローで最も大きなクレジット節約につながる手順です。**これを省略してすぐにエンリッチメントに進むことが、最もコストのかかる失敗パターンです。

---

ステップ 5 — AIリサーチ列を委任されたサブエージェントとして使う

各AIリサーチ列では、1行について1つの限定的な質問に答えるため、swan-delegate-to-sub-agentsを1回呼び出します。「この企業はDTCで、SFにあり、電気製品を販売しているか」を1つのプロンプトにまとめないでください。それぞれ別の列にします。

サブエージェントのプロンプトテンプレート：

Visit {domain}.
Answer ONE question: {specific_question}.
Look at: {specific_pages — homepage, /about, /shop, /products}.
Return one of: yes / no / unclear.
If the site is down or you cannot determine, return: unclear.
Do not guess. Do not infer from general language.

ルール：

• icp_passを通過した行にのみ実行します。プール全体を対象にリサーチを委任しないでください。
• まず10行で試験運用します。「不明」が80％以上の場合は質問が適切ではありません。規模を拡大する前に書き直してください。
• 実用可能な中で最も低コストのモデルを使います。高コストな推論は、真に判断が必要なケース（ICP適合性、アカウントの課題の推測）に限定してください。
• アクセスできないページによって列の処理が失敗しないよう、常にフォールバック値（「不明」）を設定してください。

---

ステップ 6 — ティアを判定してから、連絡先を見つける

ティアのルール：

• A — ICPに適合し、アクティブなシグナル（資金調達、採用、インテント、ニュース）がある。
• B — ICPに適合するが、アクティブなシグナルはない。
• C — ICPに部分的に適合し、継続的な育成に値する。
• D — ICPに適合しない。直ちに除外する。

連絡先の検索を行う前に、Dティアを除外します。その後、ステップ0で選んだペルソナに絞り込んで、swan-search-employees（無料プレビュー）を実行します。プレイの種類ごとの上限：

• コールド一斉送信／単一スレッドのシーケンス：企業ごとに連絡先1件。
• ABM／マルチスレッド：購買委員会を網羅する3～5件。

---

ステップ 7 — 対象を絞ってメールのウォーターフォールを実施

A/B ティアの連絡先にのみ実施します。次の順でウォーターフォールを実行します：最も安価なプロバイダー → 次のプロバイダー → 統合 → 検証。

• 最も安価なプロバイダーを最初に使って swan-enrich-email を実行し、見つからない場合にのみ次のプロバイダーにフォールバックします。
• 20 行を超える場合は、swan-execute-code と output/actions.json を使ってバッチ処理します。1 バッチあたりのアクションは最大 50 件です。
• 統合後に検証し、統合中には検証しません。invalid は除外します。catch_all はリスクがあるものとして扱います。ユーザーが配信到達率の低下を許容する場合にのみ使用します。
• 有効化の前に、ロールベースのメールアドレス（info@、support@、hello@、admin@、contact@）を除外します。

電話番号のエンリッチメントは、A ティアに限り、コールドコールを行う場合にのみ実施します。

---

ステップ 8 — 重複を排除し、コストを提示して、有効化する

• 企業レベルでは、正規化したドメインを基準に重複を排除します。
• 個人レベルでは、検証済みメールアドレスを基準に重複を排除し、見つからない場合は LinkedIn URL を使います。
• CRM と照合し、すでにアクティブなシーケンスに含まれている連絡先を除外します。
• リストの件数、ティア別の内訳、各列の充足率、推定クレジットコストをユーザーに提示します。 明示的な承認を待ちます。
• 承認後、セグメントとソースのタグを付けて Swan リストとして保存します。組織の有効化に関するデフォルト設定に従って振り分けます。
  • A ティア → 優先的なアウトリーチ（シーケンスの作成または直接プッシュ）。
  • B ティア → 標準的なナーチャリング。
  • C ティア → 接触頻度を抑えた対応／コンテンツ。

リストが保存されるか、ユーザーが明示的に中止するまで、このスキルは完了ではありません。リストオブジェクトを作成せずに「続けますか？」で終わらせないでください。

---

共通ルール

1. icp_pass = true でない限り、有料の列は実行しません。 有料のエンリッチメント列にはすべて、実行条件を示す明示的な Boolean があります。
2. ソースを取得する前に規模を確認します。 最初の呼び出しでは必ず、オーディエンスを確認するために size: 1 を指定します。
3. 最初に企業、その後に人を対象にします。 広範な人物検索から始めてはいけません。
4. 検索の前にオートコンプリートを使います。 列挙型のフィルター値は、取得処理を実行する前に検証します。列挙値を推測してはいけません。
5. 最も安価なフィルターを先に使います。 無料の除外列により、クレジットを使う前に対象の 60～80％を除外します。
6. AI 列ごとに質問は 1 つです。 委任された各サブエージェントは、範囲を絞った質問に 1 つだけ回答します。
7. 新しい AI 列やエンリッチメントプロバイダーを拡大する前に、10 行でパイロットを実施します。
8. 実行前に列の計画をユーザーに提示します。 有効化の前に、件数とコストを提示します。
9. 保存済み ICP に矛盾する依頼には、懸念を伝えます。 食い違いを明らかにし、黙って従ってはいけません。

---

アンチパターン

• 異なるフィルター条件で swan-fetch-businesses を 4 回並列に実行し、それを「マルチソース」と呼ぶ。同じプロバイダーでフィルターだけを変えても、ソースは 1 つです。
• companySize のような列挙値に対して swan-autocomplete-business-filter を省略する。サイレントに 422 エラーが発生します。
• 11-50 のプレビュー範囲を「従業員 20 人超」に該当するものとして扱う。プレビューの結果が返された後に厳密な閾値を再適用するか、エンリッチメントで確認する必要があります。
• ユーザーが市を指定しているのに、州レベルの一致を通過させる。
• 無料の除外を適用する前に、対象全体をエンリッチメントする。このスキルで最も大きなクレジットの浪費です。
• 「DTC である」「SF に所在する」「電気製品を販売している」を 1 つの AI リサーチ用プロンプトにまとめる。これは 3 つの列であり、サブエージェントも 3 つ必要です。
• 保存済みリストがないまま「続けますか？」で終わらせる。有効化が行われるか、ユーザーが中止するまで、このスキルは完了ではありません。
• 組織の保存済み ICP セグメントに矛盾する依頼に、何も伝えずに従う。

---

うまくできている状態

• ソーシングを開始する前に、ユーザーが列の計画と icp_pass Boolean の定義を確認できる。
• オーディエンスの規模を把握するため、最初に swan-fetch-businesses を size: 1 で 1 回呼び出す。
• クレジットを 1 つも使う前に、無料の除外で対象の 60～80％を除外する。
• すべての有料列に、上流の Boolean を参照する実行条件がある。
• AI リサーチ列ごとに質問への回答は 1 つだけであり、拡大する前に 10 行でパイロットを実施している。
• 最終サマリーに件数、ティア別の内訳、各列の充足率、クレジットコストが表示され、ユーザーが明示的に承認する。
• 最後に、セグメントとソースのタグが付けられ、有効化のデフォルト設定に従って振り分けられた Swan リストオブジェクトが存在する。

---

このスキルで今後追加する詳細なサブページ

組織が各施策を実際に実施する際に追加します。一度にすべて追加するわけではありません。

• LookalikeFromWon — 受注済み顧客に類似する見込み顧客のリストです。
• CompetitorCustomers — 特定の競合他社の顧客と思われる企業です。
• EventAttendees — イベント参加者リストを、情報を充実させたアウトリーチリストに変換します。
• JobPostingSignal — 特定の職種を募集している企業です。
• FundingSignal — 最近資金調達した企業です。
• LocalBusinesses — 地域の企業／SMBを対象とします（Maps形式のソーシング）。