review-skill-improver

レビュースキル改善ツール

目的

構造化されたフィードバックログを分析して、次の項目を特定します。

1. 偽陽性を発生させるルール（REJECT 率が高い）
2. 欠落しているルール（検出されるべきだった問題）
3. 具体的なスキルの修正案

入力

拡張スキーマ形式のフィードバックログ（review-feedback-schema スキルを参照）。

必須ゲート

順番に実行し、各ゲートを通過するまで最終的な Review Skill Improvement Report を出力しないでください。

1. 入力記録の確認 — ログが、リポジトリ内の明示されたパス、または添付された成果物から読み込まれていること。記憶や言い換えに基づいてはなりません。合格条件： レポートのヘッダーまたは概要に、そのパス、あるいはバイト数／行数を添えて「attached feedback blob」と記載されていること。
2. スキーマ／形式 — エントリが拡張スキーマ（review-feedback-schema スキルにある rule_source、verdict、rationale など）に一致していること。合格条件： すべての行が解析されるか、形式不正でスキップされた行が件数と行インデックス付きで列挙されていること（黙って除外しないこと）。
3. しきい値判定前の集計 — ルールを「reject 率が高い」と判定したり、推奨事項を記述したりする前に、全解析済みデータを対象にステップ 1（rule_source ごとの合計、ACCEPT と REJECT、拒否率、拒否理由）を完了すること。合格条件： 概要に、集計表と一致する「Unique rules triggered」が含まれていること。
4. エビデンスに基づく推奨事項 — すべての推奨事項に、Proposed Fix の前に少なくとも 1 つの具体的なエビデンスポインター（ログの行、または短い引用を添えた file:line）を含めること。合格条件： 各推奨事項の Evidence が空でないこと。

分析プロセス

ステップ 1：ルールソースごとに集計する

For each unique rule_source:
  - Count total issues flagged
  - Count ACCEPT vs REJECT
  - Calculate rejection rate
  - Extract rejection rationales

ステップ 2：拒否率の高いルールを特定する

拒否率が 30% を超えるルールは調査が必要です。

• 拒否理由を読む
• 共通する傾向を特定する
• ルールの修正または例外が必要か判断する

ステップ 3：パターンを分析する

拒否を理由の傾向ごとに分類します。

• 「リンターがすでに対応している」→ リンターによる検証手順を追加する
• 「フレームワークがこのパターンをサポートしている」→ スキルに例外を追加する
• 「意図的な設計上の決定」→ コードベースのコンテキスト確認を追加する
• 「想定したコードパスが誤っている」→ コードの追跡手順を追加する

ステップ 4：改善案を作成する

特定した問題ごとに、次の項目を提示します。

## Recommendation: [SHORT_TITLE]

**Affected Skill:** `skill-name/SKILL.md` or `skill-name/references/file.md`

**Problem:** [What's causing false positives]

**Evidence:**
- [X] rejections with rationale "[common theme]"
- Example: [file:line] - [issue] - [rationale]

**Proposed Fix:**
```markdown
[Exact text to add/modify in the skill]

期待される効果： [rule] の偽陽性率を X% から Y% に低減する

## Output Format

```markdown
# Review Skill Improvement Report

## Summary
- Feedback entries analyzed: [N]
- Unique rules triggered: [N]
- High-rejection rules identified: [N]
- Recommendations generated: [N]

## High-Rejection Rules

| Rule Source | Total | Rejected | Rate | Theme |
|-------------|-------|----------|------|-------|
| ... | ... | ... | ... | ... |

## Recommendations

[Numbered list of recommendations in format above]

## Rules Performing Well

[Rules with <10% rejection rate - preserve these]

使用方法

review-skill-improver スキルを呼び出してフィードバックを分析し、改善レポートを生成します。必要に応じて出力パスを指定できます。

review-skill-improver --output improvement-report.md

分析例

次のフィードバックデータの場合：

rule_source,verdict,rationale
python-code-review:line-length,REJECT,ruff check passes
python-code-review:line-length,REJECT,no E501 violation
python-code-review:line-length,REJECT,linter config allows 120
python-code-review:line-length,ACCEPT,fixed long line
pydantic-ai-common-pitfalls:tool-decorator,REJECT,docs support raw functions
python-code-review:type-safety,ACCEPT,added type annotation
python-code-review:type-safety,ACCEPT,fixed Any usage

分析結果：

# Review Skill Improvement Report

## Summary
- Feedback entries analyzed: 7
- Unique rules triggered: 3
- High-rejection rules identified: 2
- Recommendations generated: 2

## High-Rejection Rules

| Rule Source | Total | Rejected | Rate | Theme |
|-------------|-------|----------|------|-------|
| python-code-review:line-length | 4 | 3 | 75% | linter handles this |
| pydantic-ai-common-pitfalls:tool-decorator | 1 | 1 | 100% | framework supports pattern |

## Recommendations

### 1. Add Linter Verification for Line Length

**Affected Skill:** `commands/review-python.md`

**Problem:** Flagging line length issues that linters confirm don't exist

**Evidence:**
- 3 rejections with rationale "linter passes/handles this"
- Example: amelia/drivers/api/openai.py:102 - Line too long - ruff check passes

**Proposed Fix:**
Add step to run `ruff check` before manual review. If linter passes for line length, do not flag manually.

**Expected Impact:** Reduce false positive rate for line-length from 75% to <10%

### 2. Add Raw Function Tool Registration Exception

**Affected Skill:** `skills/pydantic-ai-common-pitfalls/SKILL.md`

**Problem:** Flagging valid pydantic-ai pattern as error

**Evidence:**
- 1 rejection with rationale "docs support raw functions"

**Proposed Fix:**
Add "Valid Patterns" section documenting that passing functions with RunContext to Agent(tools=[...]) is valid.

**Expected Impact:** Eliminate false positives for this pattern

## Rules Performing Well

| Rule Source | Total | Accepted | Rate |
|-------------|-------|----------|------|
| python-code-review:type-safety | 2 | 2 | 100% |

今後：スキル更新の自動化

確信度が高まれば、このスキルで次のことが可能になります。

1. スキル改善を含む PR を beagle に作成する
2. 改善の効果を継続的に追跡する
3. ルールのバリエーションを A/B テストする

フィードバックループ

Review Code -> Log Outcomes -> Analyze Patterns -> Improve Skills -> Better Reviews
     ^                                                                    |
     +--------------------------------------------------------------------+

これにより、推測ではなく実証データに基づいてレビュー品質を向上させる、継続的な改善サイクルが生まれます。