---
name: poodle-github-research
description: |
  GitHub リポジトリの PR・Issues・コードベースを深く調査し、開発傾向・レビュー
  指摘パターン・用語定義・仕様解説・実装規約・既知の罠をナレッジ提案として
  Poodle に取り込む。エンジニア向けの汎用リサーチスキル。
  「このリポジトリの開発傾向を調べて」「過去の PR/Issue から知識を抽出して」
  「レビューで頻出する指摘を棚卸しして」「コードベースの規約を知識化して」
  のように依頼されたら使う。
---

# GitHub Research Skill

## Purpose

GitHub リポジトリに蓄積された開発の歴史（PR、Issues、コード、CI）を深く調査し、
チームが暗黙的に持っている知識を明文化して Poodle のナレッジ提案にする。

単なるコメント転記ではなく、**傾向分析・用語定義・仕様解説・パターン認識**まで
踏み込んで合成する。生成されたナレッジは提案として人間がレビュー・承認する。

## When to use

- 「このリポジトリの開発傾向を調べて」
- 「過去の PR/Issue からナレッジを抽出して Poodle に入れて」
- 「レビューでよく指摘される点を棚卸しして」
- 「コードベースの設計判断や規約を知識化して」
- 「過去の障害・バグから学びを抽出して」

## Prerequisites

- `gh` CLI が認証済み（`gh auth status` で確認）
- Poodle にログイン済み（`poodle login`）

## Workflow

### Step 1: スコープ合意

ユーザーと以下を確認する（勝手にデフォルトで始めない）:

- **リポジトリ**: `owner/repo`（カレントディレクトリのリポジトリも可）
- **調査の深さ**: quick（直近 30 PR + 20 Issues）/ thorough（直近 100 PR + 50 Issues + コード構造）
- **期間**: `--since YYYY-MM-DD`（省略時は直近のみ）
- **フォーカス**: 全般 / レビュー観点 / 設計判断 / 障害・バグ / 用語集 など

リポジトリの活動頻度を確認して提案するとよい:
```bash
gh pr list -R <owner/repo> --state merged --limit 1 --json mergedAt
gh issue list -R <owner/repo> --state closed --limit 1 --json closedAt
```

### Step 2: データ収集

`gh` CLI で以下を取得する。全てを一度に取る必要はない — フォーカスに応じて取捨選択。

#### 収集時のフィルタリング（重要）

取得した PR/Issue の大半が以下に該当する場合は**スキップして追加取得**する:

- **ライブラリ・依存関係のアップデート**（dependabot、renovate、`bump`、`upgrade` 等）
- **単純な typo 修正・フォーマット変更**
- **CI 設定の微調整**（ワンライナー変更）
- **自動生成ファイルの更新**（lock ファイル、スナップショット等）

これらは知識価値が低い。取得した N 件のうち半数以上がノイズなら、**期間を広げるか
件数を増やして再取得**し、コア機能に関わる PR/Issue を十分な数（最低 10 件以上）
確保する。ユーザーに「ライブラリ更新が多いのでもう少し遡ります」と伝えてから進める。

#### 優先的に深掘りする PR/Issue

- コア機能の追加・変更（feat、機能名を含むもの）
- データ構造・DB スキーマの変更
- API インターフェースの追加・変更
- 設計判断を伴うリファクタリング
- **コア機能 PR に付いたレビューコメント** — 「なぜこうしたか」「こうすべき」の判断履歴が残っている。レビューコメント数が多い PR は特に重要
- Issue での設計議論（RFC、ADR、設計提案）

#### PR（レビュー観点・実装パターン・設計判断）
```bash
# PR 一覧（タイトル・本文・作者・マージ日・ラベル）
gh pr list -R <owner/repo> --state merged --limit <N> \
  --json number,title,body,author,mergedAt,labels,changedFiles

# 各 PR のレビュー（コア機能 PR のみ深掘り — ライブラリ更新はスキップ）
gh pr view <number> -R <owner/repo> --json reviews,comments
```

#### Issues（バグ報告・機能要望・設計議論）
```bash
# クローズ済み Issue（解決済みの知識が多い）
gh issue list -R <owner/repo> --state closed --limit <N> \
  --json number,title,body,author,closedAt,labels,comments

# ラベルで絞る（bug, design, RFC 等）
gh issue list -R <owner/repo> --state closed --label bug --limit <N> \
  --json number,title,body,author,closedAt,comments
```

#### コードベース（構造・規約・パターン）
```bash
# ディレクトリ構造
find . -type f -name "*.ts" -o -name "*.tsx" | head -100

# 主要ファイル（README, CONTRIBUTING, CLAUDE.md 等）
cat README.md CONTRIBUTING.md CLAUDE.md 2>/dev/null

# CI/CD 設定
ls .github/workflows/ && cat .github/workflows/*.yml
```

### Step 3: 深掘り分析

収集したデータから以下の観点で知識を合成する。**転記ではなく分析**が価値。

#### 最優先: コア仕様・データ構造・API（ここに最も時間をかける）

- **コア機能の仕様と仕様変更の経緯** — 何がどう変わったか、なぜ変えたか
- **データ構造・DB スキーマの設計根拠** — テーブル設計、カラム選定、制約の理由
- **API インターフェースの設計判断** — エンドポイント設計、リクエスト/レスポンス形式の根拠
- **ドメインモデルの定義** — エンティティ間の関係、状態遷移、ライフサイクル
- **レビューコメントに残された判断履歴** — 「なぜこの実装にしたか」「別案を却下した理由」「この制約の背景」など。コア機能 PR のレビュースレッドは設計判断の一次ソース

#### 高優先: コーディングスタイル・規約

- コードに一貫して現れるパターン（レイヤリング、エラーハンドリング、認証パターン）
- レビューで「こうすべき」と繰り返し指摘された慣行
- 命名規約、ファイル配置規約

#### 通常: 用語・概念定義

- ドメイン固有の用語（コードやコメントに頻出するが定義がない語）
- コンポーネント名・モジュール名の役割と責務

#### 通常: 既知の罠・障害の学び

- 過去のバグ Issue から得られた教訓（**単発のスポットバグ修正は除外**）
- 繰り返し発生した問題パターン
- 設計上の制約に起因するトラブル

#### 低優先（ナレッジ化しない）

以下はスキップする:
- ライブラリのバージョンアップ対応
- 単純なバグ修正（typo、off-by-one、null チェック漏れ等）
- フォーマット・リント修正
- テストの追加のみの PR

### Step 4: Import Packet 構築

分析結果を Poodle の Import Packet として構造化する。

#### Packet JSON の構造

出自は取り込み経路（`ingestChannel`）で表す。GitHub 由来は `github`。

```json
{
  "origin": "agent_research",
  "ingestChannel": "github",
  "documents": [
    {
      "sourceUrl": "https://github.com/<owner>/<repo>/pull/<number>",
      "title": "PR #<number>: <title> のレビュー観点",
      "retrievedAt": "<ISO datetime>",
      "rawText": "<PR 本文 + レビューコメント + 変更ファイル要約>",
      "headings": ["概要", "レビュー指摘", "変更ファイル"]
    }
  ],
  "findings": [
    {
      "claim": "DB クエリは必ずパラメータ化する（SQL インジェクション防止）",
      "body": "@reviewer-login が PR #42 のレビュー (2026-05) で指摘。以降の PR でも一貫して enforce されている。lib/repositories/ の全メソッドでこのパターンが徹底されている。",
      "sourceUrl": "https://github.com/<owner>/<repo>/pull/42",
      "evidence": "raw pg を使うときは必ず query(sql, [params]) — 文字列補間は禁止",
      "suggestedKind": "constraint",
      "topics": ["security", "database"],
      "confidence": "high"
    }
  ]
}
```

#### findings の suggestedKind ガイド

| カテゴリ | suggestedKind | 例 |
|---------|--------------|---|
| 開発傾向 | `implementation_note` | 「レビューでは型安全性が最も重視される」 |
| 用語定義 | `reference` | 「actor = 操作主体（user または service account）」 |
| 仕様解説 | `decision` | 「ORM を使わず raw pg にした理由は…」 |
| 実装パターン | `implementation_note` | 「route → service → repository のレイヤリング」 |
| 規約・制約 | `constraint` | 「テーブル名は snake_case 必須」 |
| 既知の罠 | `issue` | 「psqldef は check(col in(...)) と vector(n) の同居でパース失敗する」 |

#### 品質ガイドライン

- **転記より合成**: レビューコメントをそのまま写すのではなく、傾向を読み取って一般化する
- **根拠付き**: 必ず evidence（元の発言・コード・Issue 番号）を添える
- **帰属明記**: body に誰がいつ言ったかを含める（`@login が #N のレビュー (YYYY-MM) で`）
- **ノイズ除去**: 瑣末な指摘（typo 修正、import 順序等）はスキップ
- **confidence**: 複数 PR で一貫して見られるパターンは `high`、単発の指摘は `medium`、推測は `low`

### Step 5: ユーザー確認（必須 — スキップしない）

Import Packet を送信する**前に**、抽出した findings の一覧をユーザーに提示して
承認を得る。大量のナレッジが無確認で提案に流れるとレビューが手間になるため。

提示フォーマット:
```
## 抽出したナレッジ提案（N 件）

1. [constraint] DB クエリは必ずパラメータ化する
   根拠: @reviewer PR #42 (2026-05)

2. [decision] ORM を使わず raw pg にした理由は…
   根拠: PR #15 本文

3. [implementation_note] route → service → repository のレイヤリング
   根拠: @reviewer PR #8, #22, #35 で一貫して指摘

---
このまま全件を提案しますか？ 不要な項目があれば番号で指定してください。
```

ユーザーが除外を指定したら findings から該当項目を除去してから次へ進む。
「全件 OK」の確認が取れるまで送信しない。

### Step 6: 取り込み

Poodle への送信は API キー（`x-api-key`）で認証する。`poodle login`（Prerequisites）は
キーを `~/.config/poodle/config.json`（`apiKey` フィールド、mode 0600）に保存するだけで、
標準出力には表示しない。`POODLE_API_KEY` が未設定なら、先に用意する:

```bash
# 既にログイン済みなら config.json から読む（未ログインなら先に `poodle login` で認可する）
export POODLE_API_KEY=$(node -e "console.log(require(process.env.HOME + '/.config/poodle/config.json').apiKey)")
```

準備できたら Import Packet を送信する:

```bash
# POODLE_URL: 接続先（既定: https://app.thepoodle.ai）
curl -X POST "${POODLE_URL:-https://app.thepoodle.ai}/api/import-batches" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: ${POODLE_API_KEY}" \
  --data-binary @<FILE>
# → batchId が返る

# 処理状況を追跡
poodle status <batchId> --watch
```

ユーザーに `/proposals` でレビュー・承認するよう伝える。

## Safety rules

- **secrets / credentials / 個人情報を findings に含めない**
- **推測をファクトとして書かない** — 不確実なものは `confidence: low` を付ける
- **全て提案（レビュー待ち）止まり** — 検索に出るのは人間が承認した後（AI は提案のみ作成）
- **帰属を偽らない** — 誰が言ったかを正確に記録する