survey

サーベイ

計画を決定する前に全体像を把握することが目的の場合に、このスキルを使用します。

survey は、次の4つを適切に行うことで、移植性を保ちます。

1. 範囲を限定した調査の問いを1つ固定する。
2. 毎回同じ4つの調査レーンを実行する。
3. 固定見出しを使って、再利用可能な .survey/{slug}/ 成果物を保存する。
4. 計画または実行に引き継ぐ前に、成果物の要件を検証する。

慣れていない調査を実行する前に、次のサポートドキュメントを読んでください。

• references/evidence-recovery-ladder.md
• references/platform-adapter-and-artifact-contract.md
• references/output-templates-and-validator.md
• references/keyword-sweep-and-relevance-rescue.md
• references/gh-search-empty-lane-recovery-playbook.md

このスキルを使う場合

• ユーザーが、何が存在するのか、人々が実際に何を使っているのか、現在のソリューションの全体像はどうなっているのかを尋ねている場合。
• 機能、ワークフロー、ツールの選択、または運用上の課題について、計画や実装の前に背景情報が必要な場合。
• 複数のプラットフォームやベンダーにまたがるトピックについて、ベンダー中立的な比較が必要な場合。
• リポジトリのメンテナンスで、スキル、SOP、または再利用可能なワークフローを書き換える前に、範囲を限定した調査が必要な場合。
• すぐにコードを書くよりも、回避策、繰り返し寄せられる不満、構造的なギャップを理解することが次の適切なステップである場合。

このスキルを使わない場合

• ソリューションがすでにわかっており、ユーザーが今すぐ実装を求めている → 直接実装するか、実行スキルに引き継ぎます。
• 小さなバグ修正、範囲の狭いコード変更、または単一ファイルの編集 → 先にサーベイを行う必要はありません。
• 市場やワークフローの調査よりも、アーキテクチャ計画、タスク計画、または変更不可の仕様が必要 → plan、jeo、または ralph を使います。
• 主な依頼が、実際にブラウザーを操作して閲覧やクリックを行うこと → サーベイを装うのではなく、ブラウザー／オペレーター用のスキルを使います。

成果物の要件

出力パッケージは一貫した形に保ちます。

.survey/{slug}/
├── triage.md
├── context.md
├── solutions.md
└── platform-map.md    # required for agent/tooling/platform topics

必要な意味：

• triage.md = 問題、対象者、今取り組む理由
• context.md = ワークフローの背景、影響を受けるユーザー、回避策、関連する問題、ユーザーの声
• solutions.md = ソリューションの一覧、カテゴリ、実際の動作、頻度、ギャップ、矛盾、重要な洞察
• platform-map.md = 該当する場合、Claude／Codex／Gemini 全体で正規化した settings、rules、hooks、platform gaps

ユーザーから明示的な依頼がない限り、別のファイル名や自由形式の成果物は作成しないでください。 サーベイの出力を再利用する予定がある場合は、ファイルを書き込んだ後に python3 .agent-skills/survey/scripts/validate_survey_artifacts.py <path> を実行してください。

手順

ステップ 1：主となるサーベイモードを1つ分類する

調査を始める前に、依頼を次のように標準化します。

survey_run:
  primary_mode: market-landscape | workflow-landscape | repo-maintenance | platform-comparison
  scope: narrow | medium | broad
  evidence_floor: primary-pages-first | indexed-snippets-allowed | thin-evidence-ok
  output_language: repo-default | user-language
  needs_platform_map: true | false
  reuse_existing: true | false | unknown

モードのガイド：

• market-landscape → 製品、カテゴリ、競合、パッケージング、不満
• workflow-landscape → 人々が現在どのように作業しているか、回避策、運用上の慣習
• repo-maintenance → 既存のスキル、SOP、または再利用可能なワークフローを改善するための、範囲を限定した調査
• platform-comparison → Claude／Codex／Gemini の違いを settings、rules、hooks に正規化

トピックが複数のモードに関わる場合でも、主となるモードを1つ選んでください。

ステップ 2：エビデンスの契約を確定する

検索を始める前に、ルールを明確にします。

• ユーザーが別の言語を指定していない限り、英語で幅広く検索する
• 成果物は、リポジトリのデフォルト言語またはユーザーの言語で作成する
• 主張は出典に基づくものにする
• 格下げしたエビデンスには、direct page retrieval、indexed snippet、browser-rendered indexed snippet、feed recovery、または thin evidence のラベルを明記する
• タスクは調査モードのみで進める

references/evidence-recovery-ladder.md にある、低コストな方法から試す復旧手順を使います。

1. 一次情報のページを直接取得する
2. 安定した公式情報で代替する
3. フィードから復旧する
4. ブラウザーでレンダリングされた情報を取得する
5. インデックス済みのスニペットを使う
6. エビデンスが乏しい場合は中止する

ステップ 3：依頼をトリアージし、再利用を確認する

以下を解析します。

• what — 調査する課題、アイデア、または機能
• who — 誰がその課題に直面するか、またはワークフローを運用するか
• why — なぜ今それが重要なのか

次に、.survey/{slug}/triage.md がすでに存在するか確認します。

• 存在し、ユーザーが対応可能な場合は、再利用するか上書きするかを尋ねます。
• 無人ループでは、既存の成果物が同じ問いに当てはまる場合は再利用します。対象範囲が明らかに変わった場合にのみ上書きします。

triage.md に以下を記述します。

• # Triage
• - Problem:
• - Audience:
• - Why now:

ステップ 4：4 つのレーンを並行して実行する

情報が薄いレーンがあっても、レーンは分けておきます。

レーン A — コンテキスト

以下を出力します。

• ## Workflow Context
• ## Affected Users
• ## Current Workarounds
• ## Adjacent Problems
• ## User Voices

レーン B — ソリューション

以下を出力します。

• ## Solutions
• ## Frequency Ranking
• ## Categories
• ## Curated Sources

レーン C — 実際の行動

以下を出力します。

• ## What People Actually Use
• ## Common Workarounds
• ## Pain Points With Current Solutions
• ## Sources

レーン D — 代替手段またはプラットフォームのマップ

デフォルトモード：

• JTBD に基づく代替手段
• 間接的な代替手段
• 業界横断の類似事例

エージェント／ツール／プラットフォームに関するトピックの場合は、以下に置き換えます。

• ## Settings
• ## Rules
• ## Hooks
• ## Platform Gaps

Claude／Codex／Gemini の違いが関係する場合は、共通レイヤーとして settings / rules / hooks を使います。

ステップ 4.5：リポジトリ保守に関する調査では関連性の判定基準を適用する

primary_mode: repo-maintenance の場合、キーワード検索のヒットをそのまま信用しないでください。

最終的な推奨を書く前に、簡潔な判定を行います。

• 肯定的なシグナル（採用）： 対象機能との明確な関連性、最近のメンテナンス、明示されたライセンス、具体的なドキュメント／例。
• 否定的なシグナル（除外またはリスクとして明記）： スパムのような説明、キーワードは一致するが分野が無関係、評価／宿題のみのリポジトリ、強い根拠のない古い／アーカイブ済みリポジトリ、基本的なメタデータの欠落、または明確な根拠のない不明なライセンス。
• メタデータの最低要件： 採用する候補ごとに、license、pushed_at、archived、open_issues、forks、および適合性を説明する一行の理由を記録します。初回のメタデータ取得でライセンスが null／不明（たとえば GraphQL の licenseInfo）の場合は、不明なライセンスと分類する前に GitHub REST（gh api repos/<owner>/<repo> --jq .license.spdx_id）で一度だけ再試行します。フォールバック後もライセンスが不明／欠落している場合は、具体的な例外理由が記録されていない限り、デフォルトで除外します。初回取得で open_issues／forks が得られない場合は、gh api repos/<owner>/<repo> --jq '{open_issues: .open_issues_count, forks: .forks_count}' で一度だけ補完し、取得元を記録します。
• 鮮度の下限（推奨対象として採用する候補）： 最新の pushed_at がデフォルトで 24 か月より前の候補は除外します。古い候補を残す場合は、例外理由とリスクの注記を明記します。

検索／抽出ツールの状態が悪い場合は、GitHub API から直接取得する方法に切り替え、確信があるかのように装うのではなく、取得元とリスクを明記します。

ステップ 4.6：候補の毎時スイープ（リポジトリ保守の cron ループ）

調査が定期的なスキル保守ループの一部である場合は、最終的な推奨の前に、明示的なキーワードスイープを 1 回実行します。 Required keyword families:

• agentic ai skill
• web frontend skill
• web backend skill
• cli open source skill
• game development skill

実行ルール：

• 毎時実行では、まず直近を優先した検索ウィンドウを使用します。デフォルトでは、過去24時間〜7日以内に pushed されたものを対象とし、文書化されたリカバリーステージを通じてのみ範囲を広げます。
• 生のキーワードスキャンを発見の根拠として保持します（検索ページ経由で実施した場合は、通常 browser-rendered retrieval）。
• 候補を残す前に、Step 4.5 の関連性ゲートを適用します。
• 残す候補ごとに、少なくとも license、pushed_at/updated、archived、open_issues、forks、および適合性を説明する1行の理由を記録します。
• 推薦対象として残す候補には、デフォルトの鮮度基準（pushed_at が過去24か月以内）を適用します。古くても残す場合は、例外の理由と明示的なリスクを記録します。
• 推薦対象として残す候補には、デフォルトのシグナル基準を適用します。少なくとも1つのトラクションシグナル（例：スター数 >= 3、または理由を添えたメンテナー／コミュニティによる明示的な採用の証拠）を必須とします。推薦対象リストの基準を厳しくする場合でも、幅広い発見の証拠は保持します。
• agentic ai skill のレーンでは、*/skills のような名前だけの汎用的な個人用キャッチオールリポジトリは、明示的なワークフローの文書化とトラクションがない限り、デフォルトで適合性が低いものとして扱います。生の証拠には残しますが、例外の理由なしに TOP 推薦へ昇格させないでください。
• 推薦対象への昇格前に、否定表現を考慮した意図ガードを適用します。レーンの意図に関するトークンの重複が、明示的な否定句（例：no cli、without cli、not a cli、non-cli）にのみ現れる場合、デフォルトで low-fit に分類し、生の発見証拠に残したうえで、昇格には明示的な例外の理由を必須とします。
• 直接的なウェブ検索／抽出ツールが失敗した場合（認証／レート制限／トランスポート）、GitHub ネイティブの取得方法（gh search + gh api または gh repo view）に切り替え、取得元を明確に表示します。
• 無人ループでは、GH CLI の JSON フィールドの変更に備えてください。nameWithOwner のような非対応フィールドではなく、gh search repos --json fullName,... を優先するか、owner と name を組み合わせて識別情報を構成します。フィールドが一致しない場合は、証拠として stderr を保持し、最終的なレーンのステータスを確定する前に対応フィールドで再実行します。
• 無人ループでは、gh search repos が空の成功ペイロードを返すケースに備えてください。既知のデータがあるプローブ／クエリで終了コードが 0 でも、ペイロードが予期せず []（または実質的に空）の場合は、トランスポートの劣化として扱い、最終的なレーンのステータスを確定する前に GitHub REST 検索で再実行します。
• REST フォールバックでは、エンドポイント形式 gh api "search/repositories?q=<query>&per_page=<n>&sort=updated&order=desc" を優先し、stderr の成果物を取得します。一部の環境で 404 になる可能性のある互換性のない形式には依存しないでください。
• --require-provenance で検証する Markdown 成果物では、アドホックなラベル（github search api など）ではなく、GitHub 検索結果の証拠をバリデーター対応ラベル（検索結果一覧には indexed snippet、リポジトリ／API 詳細の取得には direct page retrieval）に対応付けます。
• キーワードのヒットがノイズの多いもの、または少ないものである場合、推薦を確定する前に references/keyword-sweep-and-relevance-rescue.md のレーン固有のリカバリーテンプレートを実行します。
• プライマリクエリの後に、客観的なリカバリートリガー（raw_count < 8、kept_count == 0、または zero_star_raw/raw_count >= 0.70）を使用し、無人の cron ループでレーンのリカバリーを決定論的に行います。
• 指標整合性ゲート（必須）： リカバリークエリを選択するたびに、成果物を書き出す前に、最終選択結果セットからレーン指標（raw_count、zero_star_raw、median_stars_raw、kept_count）を再計算します。kept_count > raw_count のようなあり得ない組み合わせを決して出力しないでください。
• ステージ1のリカバリー後もレーンの raw_count == 0 の場合、lane_status を確定する前に、そのレーンについて文書化されたステージ2のリカバリークエリをちょうど1回実行します。
• 生のヒットはあるものの、ステージ1のリカバリー後も推薦対象として残る候補の kept_count == 0 であるノイズの多いレーンでは、劣化ステータスを確定する前に、文書化されたステージ2のリカバリークエリをちょうど1回実行します。
• 文書化されたリカバリー後もレーンの raw_count == 0 の場合、degraded_causes に明示的な no-results を設定／報告します（空のままにしないでください）。
• 関連性ゲート通過後の推薦基準として、可能な限り各レーンで少なくとも1件を目指し、cli open source skill では注目枠の品質を確保するため、3件以上を目標にします。
• Markdown にレーンごとのステータス（lane_status: pass|degraded）を明示します。基準に達しない場合も証拠を保持し、簡潔な分類（license、stale、low-fit、archived、low-signal、no-results）と例／件数を用いて degraded_causes を報告します。
• 文書化されたステージ2のリカバリークエリ後もレーンの raw_count == 0 の場合、degraded_causes に no-results を含めて設定／報告します（劣化原因を空のままにしないでください）。
• lane_status とあわせて、簡潔なレーン健全性指標（kept_count、raw_count、median_stars_raw、zero_star_raw）を記載し、レビュアーが毎時実行間の品質の変動を追跡できるようにします。
• 推薦対象候補について、レーン横断の集中度チェックを追加します。recommended_lane_count < 2 の場合、実行結果に single_lane_concentration: true と記し、劣化したレーンの証拠を明示的に保持し、幅広いカバレッジが健全であると主張しないでください。
• 最終的なランキングの前に、レーン横断の推薦重複排除ゲートを追加します。生の発見証拠は変更せずに保持しつつ、リポジトリ識別子（fullName または owner/name）をキーとして推薦対象セットを重複排除し、生データと重複排除後のカバレッジ指標を両方報告します。 参照：references/keyword-sweep-and-relevance-rescue.md

ステップ 5：成果物をまとめる

作成するファイルは簡潔にし、スキーマを安定させてください。

• references/output-templates-and-validator.md にある正確な Markdown テンプレートを使用してください。
• 必須のファイル名と見出しは変更しないでください。
• 証拠が弱い場合は、根拠の正直なラベルを維持してください。
• プラットフォームに関するトピックでは、プラットフォーム間の違いを solutions.md に埋もれさせず、platform-map.md に明記してください。
• repo-maintenance では、採用した候補が関連性のゲートを通過した理由（適合性＋メタデータ＋リスク）を示してください。

ステップ 6：成果物の契約を検証する

ファイルを作成した後、バリデーターを実行してください。

python3 .agent-skills/survey/scripts/validate_survey_artifacts.py .survey/<slug>
python3 .agent-skills/survey/scripts/validate_survey_artifacts.py .survey/<slug> --platform-topic

platform-map.md が必要な場合は --platform-topic を使用してください。 実行時に根拠ラベルが重要な場合は、次も使用してください。

python3 .agent-skills/survey/scripts/validate_survey_artifacts.py .survey/<slug> --require-provenance

バリデーターが失敗した場合は、計画や実装に引き継ぐ前に成果物ファイルを修正してください。

ステップ 7：事実に基づく調査概要で終える

ファイルの作成と検証が完了してから、短い概要を返してください。

• ## Survey complete: {slug}
• 主な回避策を含む背景の箇条書き 1〜2 項目
• 重要な洞察と主要なギャップを含むソリューション状況の箇条書き 1〜2 項目
• 生成した成果物のファイル一覧

ユーザーが次のステップを明示的に求めない限り、計画や実装に移行しないでください。

出力ルール

• まず事実を示し、推奨事項は求められた場合にのみ示してください。
• 調査成果物ごとに、範囲を限定した質問を 1 つ設定してください。
• ソリューション名の重複をなくし、元の証拠を保持したまま、最終順位付けの前に各レーンの推奨候補となるリポジトリの重複を除いてください。
• 情報源が弱い、または間接的な場合は、証拠ラベルを維持してください。
• プラットフォーム間で成果物の出力スキーマを同一にしてください。
• 調査が終わったら、アーキテクチャ、計画、実行の作業は外部に引き継いでください。

例

例 1：リポジトリ保守の調査

入力

このリポジトリ内の既存スキルのうち、次に取り組む範囲を限定した保守対象として最適なものを調査してください

望ましい出力の方向性

• モード：repo-maintenance
• まず既存の .survey/{slug} を確認する
• リポジトリ内のグラフ／Wiki の情報と、必要に応じた一次情報の取得を使用する
• トリアージ、背景、ソリューションを作成し、事実に基づく概要を提示する
• スキルの書き換えを始める前に、出力フォルダーを検証する

例 2：プラットフォーム比較

入力

Claude Code、Codex、Gemini CLI におけるフック、承認、調査ワーカーの違いを調査してください

望ましい出力の方向性

• モード：platform-comparison
• platform-map.md を作成する
• 違いを settings、rules、hooks に分類して整理する
• --platform-topic を指定して検証する
• ベンダー固有の機能を成果物の契約として扱わず、移植性のギャップを記録する

ベストプラクティス

1. 最初の案内は簡潔にしてください。モードを分類し、証拠のルールを固定し、4 つのレーンを実行して、検証後に成果物を保存します。
2. 頻繁には変わらない取得、プラットフォーム、テンプレートの詳細は、メインスキルを膨らませず、参照資料に移してください。
3. 直接的な一次情報を優先しつつ、証拠の格下げはすべて正直にラベル付けしてください。
4. Claude／Codex／Gemini の実行間で、成果物のファイル名と見出しを同一に保ってください。
5. 証拠が乏しい場合は、確実性を装わず、主張の範囲を狭めてください。
6. フックシステムはバリデーターを補助するものとして扱い、リポジトリに含まれる成果物のルールの代わりにしないでください。

参照資料

• references/evidence-recovery-ladder.md — 検索／抽出環境が弱い場合の代替手順と根拠ラベル
• references/platform-adapter-and-artifact-contract.md — settings、rules、hooks の移植性ルールと、プラットフォーム間で同一の成果物出力
• references/output-templates-and-validator.md — .survey/{slug}/ の正確なファイルテンプレートとバリデーターの使用方法
• references/keyword-sweep-and-relevance-rescue.md — 継続的な repo-maintenance の反復に必須となる 5 つのキーワード検索と、ノイズの多いクエリを救済するゲート
• scripts/validate_survey_artifacts.py — 調査出力フォルダーの成果物契約バリデーター