dx-roaster
GitHubリポジトリの開発者体験（DX）を辛辣にレビューします。以下の4つのファイルを生成します: roast.md、action-plan.md、ideal-readme.md、score.json。Show HN、Product Hunt、または最初の5分が重要なあらゆるローンチを控えたOSSメンテナーやDevToolsファウンダー向けに構築されています。
重要なルール（実行前に毎回読むこと）
-
採点前に3つのリファレンスファイルをすべて読むこと。
references/scoring-rubric.md、references/roast-voice-guide.md、references/readme-template.md。ルーブリックは絶対です — 正確に10の次元を使用すること。 -
すべての次元を0–10のスケールで採点すること。絶対にスキップしないこと。 データがない = スコア0 (「該当なし」ではない)。
-
レビューは具体的な発見事項を引用すること。 問題のある行をそのまま引用する。ファイルパスを参照する。可能な限り行番号を引用する。「ドキュメントは改善できる」のような一般的な決まり文句は絶対に書かないこと。
-
トーンは重要です。 デフォルトは
honest。references/roast-voice-guide.mdに従って声を切り替えること。brutalは面白くても個人攻撃にならないように。kindは励ましつつも具体的であること。 -
アクションプランは影響度順であり、重大度順ではない。
impact × (1 / effort)を使用すること。2時間かけて12ポイント上げる修正より、5分で10ポイント上げる修正の方が優先度が高い。 -
URLをでっち上げないこと。
ideal-readme.mdを書くときは、不足しているリンクに<placeholder>構文を使用すること。レビューではメンテナーに埋めるよう促すこと。 -
メンテナーやコントリビューターの名前を決して出さないこと。 作品をレビューし、人をレビューしないこと。
-
正確に4つのファイルを
dx-roast/に出力すること。 他の場所に書き込まないこと。ファイルをスキップしないこと。
ステップ 1: 入力
必須:
repo— ローカルパス (デフォルト.) またはhttps://github.com/owner/repoURL
オプション:
| パラメータ | デフォルト | 説明 |
|---|---|---|
tone | honest | brutal / honest / kind |
output_dir | dx-roast/ | 4つの出力ファイルを書き込む場所 |
compare_to | なし | ベンチマーク比較用のオプションの2つ目のリポジトリURL |
repo がURLの場合: git clone <url> /tmp/dx-roast-<short-hash> を使用して一時ディレクトリにクローンする。そこからスキャンする。実行後に一時ディレクトリを削除する。
repo が . またはローカルパスの場合: その場でスキャンし、何も変更しない。
ステップ 2: 発見
以下のファイルを読む（それぞれ存在しない可能性があり、その場合は存在しないことを記録すること）:
README.md— 全内容、構造（見出し）、コードブロック、画像参照、バッジURLCONTRIBUTING.md、CODE_OF_CONDUCT.md.github/ISSUE_TEMPLATE/、.github/PULL_REQUEST_TEMPLATE.md、.github/CODEOWNERSpackage.json(description, homepage, repository, license, scripts)、pyproject.toml、Cargo.toml、go.modLICENSE(存在の有無 + タイプ)docs/フォルダの内容（ファイル名とサイズのみ）examples/またはsamples/またはcookbook/フォルダ.github/workflows/*.yml(名前と簡単なCIプレゼンスチェックのみ)
repo がURLの場合、gh 経由でも取得する:
git clone <url> <temp_dir>
cd <temp_dir>
# gh api 呼び出しはクローン後に行われる
gh api repos/<owner>/<repo> --jq '{stars: .stargazers_count, forks: .forks_count, watchers: .subscribers_count, pushed_at, description, homepage, topics, default_branch}'
gh api repos/<owner>/<repo>/commits --jq '.[0].commit.author.date' | head -1
gh api repos/<owner>/<repo>/contributors --paginate --jq '[.[] | .login] | length'
いずれかのGitHub呼び出しが失敗した場合はキャッチして続行する。
ステップ 3: 10の次元を採点する
references/scoring-rubric.md の10の次元それぞれについて、{score: 0–10, evidence: [...]} を出力する。evidence は、発見した内容を引用した1〜3の短い文字列のリストである。
例:
"visual_proof": {
"score": 4,
"evidence": [
"89行目にスクリーンショット1つを発見（ファーストビューの下）",
"アニメーションデモ/GIFなし",
"動画なし"
]
}
スコアを合計 → 合計 (0–100) → グレード (ルーブリックに従い A/B/C/D/F)。
以下の正確な形式で dx-roast/score.json に保存する:
{
"repo": "<owner/repo または ローカルパス>",
"scanned_at": "<ISO 8601 タイムスタンプ>",
"dimensions": {
"time_to_first_success": { "score": 7, "evidence": ["..."] },
"what_is_this_clarity": { "score": 5, "evidence": ["..."] },
"visual_proof": { "score": 4, "evidence": ["..."] },
"install_simplicity": { "score": 9, "evidence": ["..."] },
"runnable_quick_start": { "score": 8, "evidence": ["..."] },
"documentation_depth": { "score": 6, "evidence": ["..."] },
"examples": { "score": 5, "evidence": ["..."] },
"community_signals": { "score": 3, "evidence": ["..."] },
"trust_signals": { "score": 7, "evidence": ["..."] },
"marketing_signals": { "score": 4, "evidence": ["..."] }
},
"total": 58,
"grade": "D",
"tone": "honest"
}
ステップ 4: レビューを書く
references/roast-voice-guide.md を読む。リクエストされたトーンを適用する。250〜500語で dx-roast/roast.md に書く。
必須の構造:
# DX Roast: <リポジトリ名>
**グレード: <レター> (<合計点数>/100)** · トーン: <tone>
<パラグラフ1: 評決。機能している点 + 大きなギャップ。>
<パラグラフ2: ファイル参照付きで具体的な発見事項を2つ引用。>
<パラグラフ3: さらに2つの発見事項を引用し、次元スコアと結びつける。>
<パラグラフ4 (オプション): 最後のひねり、または既知の優良リポジトリとの比較。>
<最終パラグラフ: 今後の道筋として `action-plan.md` を参照するように促す。>
すべてのレビューは score.json のevidence配列から 少なくとも3つの具体的な発見事項 を参照しなければならない。
ステップ5: アクションプランを生成する
各修正候補について priority = impact / effort_minutes を計算する。上位5〜10件を取得する。優先度の降順でソートする。
各修正について、dx-roast/action-plan.md に以下を書き込む:
### N. <修正内容を命令形で一行で>
**理由:** <一文での正当性。どの次元を改善するかを参照すること。>
**影響:** +<X> ポイント · **努力:** <5分 / 30分 / 2時間 / 半日>
**方法:**
1. <具体的なステップ1>
2. <具体的なステップ2>
3. <具体的なステップ3>
<正確な変更を示すオプションのコード/マークダウンスニペット>
action-plan.md を以下の内容で開く:
# アクションプラン — <リポジトリ名>
現在のグレード: <レター> (<合計点>/100)
インパクト × 努力でランク付けされたトップ修正。この順序で実行すること。
---
ステップ 6: 理想のREADMEを生成する
references/readme-template.md を読む。「埋め方のルール」セクションに従ってテンプレートを埋める。dx-roast/ideal-readme.md に書き込む。
不足している値には <homepage_url> などのプレースホルダーを使用する。長さの上限: 100行。
ステップ 7: ターミナルサマリー
以下の正確な形式をユーザーに出力する:
DX Roast 完了 — グレード: <レター> (<合計点>/100)
トップ3修正 (影響度順):
1. <修正1> +<X> pts · <努力>
2. <修正2> +<X> pts · <努力>
3. <修正3> +<X> pts · <努力>
ファイル:
→ dx-roast/roast.md (共有可能な評決)
→ dx-roast/action-plan.md (優先順位付けされた修正)
→ dx-roast/ideal-readme.md (目標状態)
→ dx-roast/score.json (生スコア)
compare_to が指定された場合、比較行を追加する:
ベンチマーク: <他のリポジトリ> スコア <X>/100 (グレード <Y>) — 差分 <デルタ> ポイント。
セルフQA（実行毎、ターミナルサマリーを出力する前）
-
score.jsonの全10次元にスコアとevidenceがある - 合計が各次元の合計と一致する
- グレードのレターがルーブリックの閾値に従った合計と一致する
- レビューが score.json から少なくとも3つのevidence項目を参照している
- レビューがメンテナー/コントリビューターの名前を出していない
- アクションプランに5〜10個の項目があり、優先度の降順でソートされている
- 理想のREADMEが100行未満である
- 理想のREADMEがスキャンで見つからなかったURLに
<placeholder>を使用している - 4つすべてのファイルが output_dir に存在する
- roast.md または action-plan.md に
<TBD>/<TODO>プレースホルダーがない
いずれかのチェックが失敗した場合、修正してそのステップを再実行する。
エラーハンドリング
以下の4つの障害モードは明示的に処理される — 原因を明らかにせずに不完全な出力をスキルが静かに生成しないようにすること。
| ケース | 動作 |
|---|---|
repo が存在しない、クローンできない、または読み取れない | 即座に リポジトリが見つからないかアクセス不可: <repo> というメッセージで終了する。出力ファイルは一切書き込まない。 |
README.md がない | それでも実行する。what_is_this_clarity、visual_proof、runnable_quick_start、marketing_signals を0近くに採点する。レビューの冒頭でその不在を利用する（「READMEがないということは、それ自体が主張です」）。 |
| リポジトリがプライベートで、GitHub認証がない | ローカルクローンを試みる (git clone <url>); 失敗した場合、リポジトリはプライベートで、認証が利用できません で終了する。ユーザーに GITHUB_TOKEN を設定するか、ローカルパスを渡すよう提案する。 |
compare_to URLが失敗する（ネットワーク、404、プライベートなど） | ベンチマークなしで続行する。レビューに次の1行を追加する: 注記: <compare_to> に対するリクエストされたベンチマークは取得できませんでした。 ターミナルサマリーから ベンチマーク: 行を省略する。 |
ステップ2のメタデータ取得中に発生したGitHub APIエラー（レート制限、一時的な5xx）は、score.json の trust_signals.evidence に "github metadata unavailable" としてキャプチャされ記録される。実行の残りは続行される。
例
良い呼び出し例:
「https://github.com/myorg/mytool のリポジトリをレビューして — トーン: brutal。」
→ スキルがクローン、スキャン、採点し、4つのファイルを dx-roast/ に書き込み、サマリーを出力する。典型的なリポジトリで総実行時間 <60秒。
良い比較例:
「カレントディレクトリのDX監査をして。https://github.com/vercel/next.js とベンチマーク比較して。」
→ 両方をスキャンし、カレントを採点し、レビューとサマリーにベンチマーク行を含める。
このスキルがやらないこと
- ターゲットリポジトリを変更しない（読み取り専用スキャン）
- セキュリティ監査や依存関係スキャンを実行しない
- マーケティングコピーを生成しない（アクション項目は具体的であり、「トーンを書き直す」ではない）
- 画像やアセットを生成しない（プレースホルダーのみ）
- ソーシャルメディアに投稿しない（共有可能なテキストのみを書き込む）