fork-intelligence

フォークの知見

GitHub のフォークエコシステムで価値ある作業を発見するための体系的な方法論です。スターだけで絞り込むと、実質的なフォークの 60〜100％を見逃します。このスキルでは、ブランチ単位の差分分析、上流の PR との相互参照、ドメイン固有のヒューリスティックを使って重要なものを見つけます。

Python、Rust、TypeScript、C++/Python、Node.js にまたがる 10 個のリポジトリ（tensortrade、backtesting.py、kokoro、pymoo、firecrawl、barter-rs、pueue、dukascopy-node、ArcticDB、flowsurface）で実証済みです。

自己進化するスキル：このスキルは使用を通じて改善されます。指示が誤っている場合、パラメーターにずれが生じている場合、または回避策が必要だった場合は、先送りせず、ただちにこのファイルを修正してください。実際に再現可能な問題がある場合にのみ更新してください。

最初に — TodoWrite タスクテンプレート

必須：フォークの分析を始める前に、適切なテンプレートを選択して読み込んでください。

テンプレート A — 完全な分析（新しいリポジトリ）

1. Get upstream baseline (stars, forks, default branch, last push)
2. List all forks with pagination, note timestamp clusters
3. Filter to unique-timestamp forks (skip bulk mirrors)
4. Check default branch divergence (ahead_by/behind_by)
5. Check non-default branches for all forks with recent push or >1 branch
6. Evaluate commit content, author emails, tags/releases
7. Cross-reference upstream PR history from fork owners
8. Tier ranking and cross-fork convergence analysis
9. Produce report with actionable recommendations

テンプレート B — クイックスキャン（トリアージのみ）

1. Get upstream baseline
2. List forks, filter by timestamp clustering
3. Check default branch divergence only
4. Report forks with ahead_by > 0

テンプレート C — 対象を絞ったフォーク評価（特定のフォーク）

1. Compare fork vs upstream on all branches
2. Examine commit messages and changed files
3. Check for tags/releases, open issues, PRs
4. Assess cherry-pick viability

---

シグナルの優先順位

10 個のリポジトリでの実証済みの信頼性に基づく順位です。詳細は signal-priority.md を参照してください。

順位	シグナル	信頼性	検出できるもの
1	ブランチ単位の差分	最高	フィーチャーブランチ上の作業（実質的なフォークの 50％以上）
2	上流 PR との相互参照	高	compare API では見えない、リベース／強制プッシュされた作業
3	フォークのタグ／リリース	高	独立して保守する意図
4	コミットのメールドメイン	高	組織に所属するコントリビューター（@company.com）
5	タイムスタンプのクラスタリング	中	ミラーによるノイズを 85％以上除去
6	フォーク間の収束	中	上流で満たされていない需要を明らかにする
7	スター	最低	実際の価値と逆相関することが多い

---

パイプライン — 7 ステップ

ステップ 1：上流のベースライン

UPSTREAM="OWNER/REPO"
gh api "repos/$UPSTREAM" --jq '{forks_count, pushed_at, default_branch, stargazers_count}'

ステップ 2：すべてのフォークを一覧表示＋タイムスタンプのクラスタリング

# List all forks with activity signals
gh api "repos/$UPSTREAM/forks" --paginate \
  --jq '.[] | {full_name, pushed_at, stargazers_count, default_branch}'

タイムスタンプのクラスタリング：pushed_at が上流と完全に一致するフォークは、GitHub のフォーク機能によって一括作成され、その後一度も変更されていないミラーです。pushed_at でグループ化してください。一意のタイムスタンプを持つフォークは調査する価値があります。これだけでノイズを 85％以上除去できます。

# Filter to unique-timestamp forks (skip bulk mirrors)
gh api "repos/$UPSTREAM/forks" --paginate \
  --jq '.[] | {full_name, pushed_at, stargazers_count}' | \
  jq -s 'group_by(.pushed_at) | map(select(length == 1)) | flatten'

ステップ 3：デフォルトブランチの差分

BRANCH=$(gh api "repos/$UPSTREAM" --jq '.default_branch')

# For each candidate fork
gh api "repos/$UPSTREAM/compare/$BRANCH...FORK_OWNER:$BRANCH" \
  --jq '{ahead_by, behind_by, status}'

status フィールドの意味：

• identical — 完全なミラー。スキップ
• behind — 古いミラー。スキップ
• diverged — 独自のコミットがあり、上流より遅れている（興味深い）
• ahead — 独自のコミットがあり、上流に追いついている（まれで、最も価値が高い）

重要：常に上流リポジトリ側から比較してください（repos/UPSTREAM/compare/...）。逆方向（repos/FORK/compare/...）では、一部のリポジトリで 404 が返されます。

ステップ 4：デフォルト以外のブランチの分析（重要）

これは方法論における最大の改善点です。 テストした 10 個すべてのリポジトリで、最も価値のあるフォーク作業の 50％以上は、フィーチャーブランチ上だけに存在していました。

例：

• flowsurface/aviu16：7,000 行の GPU シェーダーヒートマップが shader-heatmap 上だけに存在
• ArcticDB/DerThorsten：conda_build、clang、apple_changes にまたがる 147 件のコミット
• pueue/FrancescElies：時間表示機能が cesc/duration 上だけに存在
• barter-rs：上位 12 個のフォークのうち 6 個は、フィーチャーブランチ上だけに作業が存在

# List branches on a fork
gh api "repos/FORK_OWNER/REPO/branches" --jq '.[].name' | head -20

# Check divergence on a specific branch
gh api "repos/$UPSTREAM/compare/$BRANCH...FORK_OWNER:FEATURE_BRANCH" \
  --jq '{ahead_by, behind_by, status}'

ブランチを確認するフォークのヒューリスティック：

• pushed_at が上流より新しい一方で、デフォルトブランチの ahead_by == 0 であるフォーク
• ブランチが 1 つより多いフォーク
• ブランチ数が 10 を超える場合は注意が必要です。重要な作業が含まれている可能性があります（ArcticDB の Rohan-flutterint には 197 個のブランチがありました）

ステップ 5：コミット内容の評価

gh api "repos/$UPSTREAM/compare/$BRANCH...FORK_OWNER:BRANCH" \
  --jq '.commits[] | {sha: .sha[:8], message: .commit.message | split("\n")[0], date: .commit.committer.date[:10], author: .commit.author.email}'

確認する点：

• コミットのメールアドレスのドメインから、組織に所属する貢献者が分かります（@man.com、@quantstack.net）
• ahead_by の数からマージコミットを差し引きます（例：akedа2/pueue は ahead が 35 件でしたが、そのうち 28 件は上流からのマージでした）
• ビルドシステムの変更（CMakeLists.txt、Cargo.toml、pyproject.toml）は、プラットフォーム対応を示します
• Protobuf スキーマの変更は、アーキテクチャレベルの機能を示します
• ソースコードの変更と並んでテストファイルがある場合は、本番環境を意識した作業であることを示します

ステップ 6：フォーク固有のシグナル

# Tags/releases (strongest independent maintenance signal)
gh api "repos/FORK_OWNER/REPO/tags" --jq '.[].name' | head -10
gh api "repos/FORK_OWNER/REPO/releases" --jq '.[] | {tag_name, name, published_at}' | head -5

# Open issues on the fork (signals independent project maintenance)
gh api "repos/FORK_OWNER/REPO/issues?state=open" --jq 'length'

# Check if repo was renamed (strong divergence intent signal)
gh api "repos/FORK_OWNER/REPO" --jq '.name'

シグナル	強さ	例
フォークのタグ／リリース	最高	pueue/freesrz93 には 6 件のリリースがありました
上流に対するオープン PR	高	レビューの文脈を伴う正式な提案
フォークのオープン issue	高	独立したプロジェクトのメンテナンス
リポジトリ名の変更	中	flowsurface/sinaha81 が volume_flow になりました
ビルド設定の変更	高（コンパイル言語の場合）	Cargo.toml、CMakeLists.txt の差分
説明の変更	低	コード変更のない見栄え目的の名前変更が多数

ステップ 7：フォーク間の収束と上流 PR 履歴の照合

# Check upstream PRs from fork owners
gh api "repos/$UPSTREAM/pulls?state=all" --paginate \
  --jq '.[] | select(.head.repo.fork) | {number, title, state, user: .user.login}'

フォーク間の収束：複数のフォークが独立して同じ問題を解決している場合、上流での需要が満たされていないことを示します。

• firecrawl：3 つのフォークが、検出回避のために Patchright を採用
• flowsurface：3 つのフォークが、独立してテクニカル指標を追加
• kokoro：独立したバッチ推論の実装が 2 つ
• barter-rs：4 つのフォークが Bybit のサポートを追加

上流 PR との照合で検出できるもの：

• リベース／強制プッシュされたため、比較 API では見えない作業
• 上流にマージされた作業（フォークでは ahead が 0 件でも、過去に重要な意味を持っていたもの）
• フォークが引き続き維持している、価値あるコードを含む却下済み PR

---

ティア分類

パイプラインの実行後、フォークをティアに分類します。

ティア	基準	対応
ティア 1：大規模な拡張	新機能、アーキテクチャの変更、オリジナルのコミットが 10 件超	詳細に評価し、チェリーピック候補とする
ティア 2：対象を絞った機能	対象を絞った追加、バグ修正、コミットが 2～10 件	個々のコミットをチェリーピックする
ティア 3：インフラストラクチャ	CI/CD、パッケージング、デプロイ、ドキュメント	利用環境に関連するかを評価する
ティア 4：歴史的なもの	上流にマージ済み、または古くなっているが、かつて重要だったもの	背景情報として記録し、対応は不要

---

ドメイン固有のパターン

コードベースによって、フォークの挙動は異なります。詳細はdomain-patterns.mdを参照してください。

ドメイン	主なパターン	例
科学／ML	研究者がフォークして実装・公開した後、姿を消す。ソーシャルエンゲージメントは皆無	pymoo：300 ファイルのフォークでスター 0 個
トレーディング／金融	取引所コネクターが中心。最良のフォークは非公開	barter-rs：独立した Bybit 実装が 4 件
インフラ／開発ツール	セルフホスティング／SaaS 機能の削除が主なテーマ	firecrawl：devflowinc/firecrawl-simple（スター 630 個）
C++／Python 混在	機能開発はブランチ上で行われ、メールドメインから所属機関が分かる	ArcticDB：@man.com、@quantstack.net
Node.js ライブラリ	npm で別パッケージとして公開されているか確認	dukascopy-node：kyo06 が dukascopy-node-plus を公開
Rust CLI	Cargo.toml の差分は信頼できる簡易フィルター。「上位互換」フォークはサブコマンドを追加	pueue：freesrz93 がサブコマンドを 7 件追加

---

クイックスキャンパイプライン（5 分間のトリアージ）

新しいリポジトリを迅速にトリアージするには：

UPSTREAM="OWNER/REPO"
BRANCH=$(gh api "repos/$UPSTREAM" --jq '.default_branch')

# 1. Baseline
gh api "repos/$UPSTREAM" --jq '{forks_count, pushed_at, stargazers_count}'

# 2. Forks with unique timestamps (skip mirrors)
gh api "repos/$UPSTREAM/forks" --paginate \
  --jq '.[] | {full_name, pushed_at, stargazers_count}' | \
  jq -s 'group_by(.pushed_at) | map(select(length == 1)) | flatten | sort_by(.pushed_at) | reverse'

# 3. Check ahead_by for each candidate
# (loop over candidates from step 2)

# 4. Check upstream PRs from fork authors
gh api "repos/$UPSTREAM/pulls?state=all" --paginate \
  --jq '.[] | select(.head.repo.fork) | {number, title, state, user: .user.login}'

---

既知の制限事項

制限事項	影響	回避策
GitHub compare API の 250 コミット制限	大きく乖離したフォークでは結果が途切れる可能性があります	gh api repos/FORK/commits?per_page=1 を使用して合計数を取得します
非公開フォークは確認できない	トレーディング企業は最良の成果を非公開にしています	既知の制限として受け入れます
強制プッシュされたブランチでは compare API が機能しない	大きな変更があっても先行コミット数が 0 と表示されます	上流の PR 履歴と照合します
名前変更されたフォークでは API 呼び出しに失敗する可能性がある	古い URL では 404 が返る可能性があります	gh api repos/FORK_OWNER/REPO --jq '.name' を使用して名前変更を検出します
大規模なフォークエコシステムではレート制限が発生する	フォークが 1000 件を超えると、API 呼び出しが多数必要です	タイムスタンプのクラスタリングを使用して呼び出しを 85% 以上削減します
メンテナーの開発用フォークが独立した作業に見える	ブランチ名が上流の PR と 1 対 1 で対応しています	ブランチ名を上流の PR ブランチ名と照合します

---

レポートテンプレート

最終分析レポートには次の構成を使用してください：

# Fork Analysis Report: OWNER/REPO

**Repository**: OWNER/REPO (N stars, M forks)
**Analysis date**: YYYY-MM-DD

## Fork Landscape Summary

| Metric                                | Value  |
| ------------------------------------- | ------ |
| Total forks                           | N      |
| Pure mirrors                          | N (X%) |
| Divergent forks (ahead on any branch) | N      |
| Substantive forks (meaningful work)   | N      |
| Stars-only miss rate                  | X%     |

## Tiered Ranking

### Tier 1: Major Extensions

(fork details with ahead_by, key features, files changed)

### Tier 2: Targeted Features

...

### Tier 3: Infrastructure/Packaging

...

## Cross-Fork Convergence Patterns

(themes that multiple forks independently implemented)

## Actionable Recommendations

- Cherry-pick candidates
- Feature inspiration
- Security fixes

---

変更後のチェックリスト

このスキルを変更した後：

1. YAML フロントマターが有効（description にコロンがない）
2. description のトリガーキーワードが最新
3. すべての ./references/ リンクが解決できる
4. パイプラインの手順番号に一貫性がある
5. シェルコマンドを実際のリポジトリでテスト済み
6. 変更をevolution-log.mdに追記する

実行後の振り返り

このスキルの実行が完了したら、タスクを終了する前に振り返ってください：

0. 自分の場所を確認する。 — 編集する前に、この SKILL.md の正規パスを確認します。
1. 何が失敗したか？ — 原因となった指示を修正します。
2. 予想以上にうまくいったことは？ — 推奨プラクティスとして採用します。
3. 何が現状とずれていたか？ — 実態に合わなくなったスクリプト、参照先、依存関係を修正します。
4. 記録する。 — トリガー、修正内容、根拠を記載した Evolution-log エントリーを追加します。

先送りしないでください。次回の呼び出しでは、あなたが残した状態が引き継がれます。