octkp/knowledge-rewrite-judge

Knowledge Rewrite Judge

AIが生成した作業ログ・調査記録を前にして、「これを人間向けの簡潔なナレッジドキュメントとしてわざわざ書き直す価値があるか」を判定するスキル。

前提となる棲み分けの思想

このリポジトリでは、ナレッジを2形式で共存させる：

| 区分 | 形式 | 役割 | |---|---|---| | AI向け | AIが生成した詳細ログ・調査記録。多少冗長でも構造化されていて検索ヒットしやすい | Skill経由で横断検索。書き直さずそのまま活用 | | 人間向け | 人が手で書いた簡潔なエッセンス。核心だけ。 | 別途、意図的に書き起こす |

「人間が読みやすい」＝「AIが書いたものではない簡潔な文章」と定義する。 AIログがそのまま存在するのに、人が手で書き直す価値があるものだけを選別するのがこのスキルの目的。

ベースパス

/Users/takano_y/ghq/github.com/kokopelli-inc/badev-knowledge-base

入力の受け取り

次のいずれかで対象を受け取る：

• ファイルパス：単一ドキュメント（例: docs/takano/調査/BAX-10987_.../README.md）
• ディレクトリパス：チケットフォルダ全体（例: docs/takano/調査/BAX-10987_障害調査.../）
• テーマキーワード：テーマ名（例: 「年払い対応」「PostgreSQLロック」）

ファイル/ディレクトリ指定の場合はその中身を読み取る。テーマ指定の場合は次の探索を先に行う。

ワークフロー

1. 対象ドキュメントの読み取り

指定されたファイル/ディレクトリを Read で読む。ディレクトリの場合は README.md を優先し、なければ主要な .md を読む。

2. 関連ドキュメントの探索（横断性の判定材料）

テーマに関連する他のチケット・ドキュメントが散らばっていないかを調べる。これが「複数チケット横断」判定の根拠になる。

cd {ベースパス}
# テーマキーワードでファイル名・本文を横断検索
grep -ril "{キーワード}" docs/ --include="*.md"
# チケット番号やテーマ語でディレクトリ名を検索
find docs/ -type d -iname "*{キーワード}*"

複数の担当者ディレクトリ・複数チケットに同テーマが散在していれば、横断的ナレッジの価値が高い。

3. 選別観点での評価

以下5観点それぞれについて、当てはまるか（✅/❌）と理由を判定する。

| 観点 | 説明 | 判定の手がかり | |---|---|---| | 横断的な教訓 | 1チケットでは見えず、複数の作業を跨いで初めて見えるもの | 手順2で同テーマの複数チケットが見つかる／「再発」「共通」等の記述 | | 再現性の高い罠 | 別の人が同じ間違いを踏みやすいもの | 「障害」「ゾンビ」「再発」「ハマった」「注意」等のキーワード | | 設計の意図・歴史的経緯 | コードを読んでも分からない「なぜこうなっているか」 | 「なぜ」「経緯」「背景」「理由」「意図」等の記述 | | 暗黙知の言語化 | 経験者の頭にしかない判断基準・価値観 | 「〜すべき」「〜は異常」「〜の産物」等の主張・判断基準 | | オンボーディング素材 | 新メンバーが最初に知るべき領域の全体像 | システム全体像・業務ドメインの仕様説明 |

4. 判定フローの適用

次の4問に Yes/No で答える。

1. 3ヶ月後の自分が読み返す可能性があるか？
2. 他のメンバーが同じ場面に遭遇しそうか？
3. AIが書いた長文を要約せず読むのは苦痛か？（＝原文が冗長で核心が埋もれているか）
4. 複数チケットを跨ぐテーマか？（手順2の結果を反映）

5. 結論の導出

• Yesが3つ以上 → 「書き直しを推奨」
• Yesが2つ → 「検討余地あり」（観点評価で✅が多ければ推奨寄り）
• Yesが1つ以下 → 「書き直し不要」（AIログのままSkill検索で十分）

ただし以下は判定フローに関わらず原則「書き直し不要」とする：

• 単発のバグ修正記録（横展開しない）
• チケット固有の対応手順（再利用性が低い）
• 既にAIが十分構造化していて、かつ単一チケット完結の調査結果

6. 結果出力

以下のフォーマットで会話に出力する。

# ナレッジ書き直し判定: {対象名}

## 結論
**書き直しを推奨 / 検討余地あり / 書き直し不要**

（一言で理由）

## 選別観点の評価
- 横断的な教訓: ✅/❌ — {理由}
- 再現性の高い罠: ✅/❌ — {理由}
- 設計の意図・歴史的経緯: ✅/❌ — {理由}
- 暗黙知の言語化: ✅/❌ — {理由}
- オンボーディング素材: ✅/❌ — {理由}

## 判定フロー（Yes {n}/4）
1. 3ヶ月後に読み返す可能性: Yes/No
2. 他メンバーも遭遇しそう: Yes/No
3. 原文が冗長で読むのが苦痛: Yes/No
4. 複数チケット横断テーマ: Yes/No

## 関連ドキュメント（横断テーマの場合）
- {パス1}
- {パス2}
...

## 書き直しの方向性（推奨の場合のみ）
- **想定読者**: {新メンバー / 同領域の担当者 / 将来の自分 など}
- **集約すべき関連ドキュメント**: {手順2で見つかったもの}
- **構成案**: {見出しレベルの骨子}
- **削ぎ落とすもの**: {AIログのうち人間向けでは不要な部分}

複数ドキュメントの一括判定

ディレクトリ全体やテーマ群を渡された場合は、各対象に対して手順1〜5を回し、最後に一覧表でまとめる。

# 一括判定サマリー

| 対象 | 結論 | Yes数 | 備考 |
|---|---|---|---|
| {テーマ/チケット} | 推奨 | 4/4 | {一言} |
| ... | 不要 | 1/4 | {一言} |

## 書き直し推奨の優先順位
1. {最も価値が高いもの}（理由）
2. ...

注意事項

• 判定はあくまで支援。最終判断はユーザーに委ねる前提で、断定しすぎない。
• 「書き直し不要＝価値がない」ではない。AIログとしては有用だが人間向け書き直しの優先度が低い、という意味であることを明示する。
• コミットメッセージは簡素（"c" 等）なので参照しない。ファイル内容とディレクトリ構造で判断する。
• 横断性の判定では、担当者ディレクトリ（kudouke, nakayama, okonogi, shiina, takano, ushiroyama, yoshizawa, yukioka）をまたいで同テーマが存在するかも確認する。