juanmackie/juanskills

GitHub Gem Hunter

目的

特定のドメインにおいて、高価値でありながら可視性の低いGitHubリポジトリを、トピックグラフ全体にわたって広く、かつスター数と日付の帯域にわたって深く検索することで表面化します。

使用するタイミング

• ユーザーが技術分野において「隠れた名盤」「過小評価されている」「見逃した機会」「何を見逃しているか」を尋ねたとき。
• ユーザーが発見を求めているのであって、単一の最もよく知られたリポジトリを求めていないとき。
• ユーザーがトピック、言語、または問題の説明を提供したとき。

使用しないタイミング

• ユーザーが最も人気のあるリポジトリを求めている場合（単純にスター数で直接検索してください）。
• ユーザーがコード検索を求めている場合（リポジトリ検索ではなくコード検索を使用してください）。
• ユーザーがGitHubトークンを持っておらず、深い結果を期待している場合（制限について警告してください）。

実行パイプライン

フェーズ0 — 認証確認

• gh CLIが認証済みの場合はそれを優先します。そうでない場合はGITHUB_TOKENが必要です。
• 認証されていない場合、警告します：検索は約10 req/minに制限され、結果は浅くなります。

フェーズ1 — トピック拡張（広く）

1. /search/topics?q=<user-topic> をクエリして、関連するトピック名を見つけます。
2. 3～8個の関連トピックからなるトピッククラスターを構築します。
3. クラスター内の各トピックに対して、topic: 修飾子を使用したリポジトリクエリを構築します。

フェーズ2 — スター帯域スライシング（深く）

クラスター内の各トピックに対して、次の互いに素な帯域を実行します： stars:1..10、stars:11..50、stars:51..200、stars:201..1000、stars:1001..5000。 各帯域内で、1,000件の結果上限までページネーションします。

フェーズ3 — 更新日フィルタ

1,000件を超える結果を返す帯域については、各ウィンドウが上限を下回るまで、pushed: 日付範囲を再帰的に分割します。

フェーズ4 — 低スターgemスイープ

トピックごとに、pushed:>YYYY-MM-DD（6ヶ月前）を指定した専用の stars:1..20 クエリを実行します。これらは別途収集します。

フェーズ5 — 重複排除とエンリッチ

• full_name で重複を排除します。
• メタデータを取得します：スター数、フォーク数、オープンイシュー数、pushed_at、created_at、トピック、ライセンス、READMEの長さ（contents API経由）。
• ユーザーが明示的に求めた場合を除き、フォークは除外します（fork:true）。

フェーズ6 — スコアリングとランキング

gemスコアを適用します：

• スター速度（作成からの月数で割ったスター数）
• 最終プッシュからの日数（少ないほど良い）
• READMEの長さと構造
• トピック関連性の密度
• イシュー応答性（利用可能な場合）

結果を次のようにグループ化します：

• アクティブgem（最近のコミット、上昇速度）
• プレトラクションgem（低スター、最近のアクティビティ）
• ギャップフィル（2つのトピッククラスターを橋渡しするリポジトリ）

フェーズ7 — 出力

次の列を持つランク付けされたマークダウンテーブルを返します： リポジトリ | スター数 | 年数 | 最終プッシュ | gemである理由

簡単な方法論の注釈と、APIレート制限に関する注意事項を含めます。

エラーハンドリング

• HTTP 403（二次レート制限）の場合：スリープして指数バックオフで再試行します。
• HTTP 422（クエリが複雑すぎる）の場合：最も重要でない修飾子を削除してクエリを簡略化し、再試行します。
• スター帯域で結果が空の場合：その帯域をスキップして続行します。

制限事項

• GitHub検索は各クエリを最大1,000件の結果に制限します。スライスはこれを軽減しますが、完全には排除できません。
• スター速度は、非常に新しいリポジトリ（作成から30日未満）ではノイズが多くなります。
• READMEの長さは品質のプロキシであり、保証ではありません。