octkp/ticket-knowledge-reader

Ticket Knowledge Reader

ticket-knowledge-logger スキルが badev-knowledge-base リポジトリに記録したナレッジを、チケット番号だけを頼りに自動で見つけて読み込むスキル。書く側（logger）と対になる「読む側」のスキル。

別セッションで「あのチケット、前に調べたよな…どこに書いたっけ」となったときに、BAX-XXXX を伝えるだけで該当ドキュメントを探し出して内容を提示する。

何を探すか

ticket-knowledge-logger は以下の構造でナレッジを記録している：

docs/{ユーザー名}/{カテゴリ}/{チケット番号}_{チケット名}/
  ├─ README.md  ← まとめ（結論・要点）。まずこれを読む
  ├─ LOG.md     ← 会話ログ（時系列の詳細）
  └─ PLAN.md    ← プラン計画書（あれば）

• カテゴリは 調査 / 実装 / その他 のほか、ユーザーによっては レビュー / レポート / 勉強会 等もありうる。
• 同じ BAX 番号が複数の場所に存在しうる（別カテゴリ・別ユーザー・チケット名違いで複数ディレクトリ等）。検索は全件拾って提示する。
• docs/knowledge/ には人間向けに書き直された横断ナレッジ（トピック単位）が置かれている。BAX 番号がファイル名に無くても本文で参照されることがあるので、ここも併せて検索する。

ワークフロー

1. 入力からチケット番号を抽出

ユーザーの入力から BAX-\d+ 形式のチケット番号を抜き出す。「BAX-10987」だけでも、「BAX-10987のナレッジ読んで」でも同じ。複数指定されたらそれぞれについて処理する。

番号が抽出できない場合はユーザーに確認する。

2. リポジトリのルートを解決し、最新化する

badev-knowledge-base リポジトリのクローン先はメンバーごとに異なる可能性があるため、以下の優先順位で REPO_ROOT を解決する（ticket-knowledge-logger と共通の解決ルール）：

1. 環境変数 BADEV_KNOWLEDGE_BASE_PATH が設定されていればそれを使う
2. 設定ファイル $HOME/.config/claude-skills/badev-knowledge-base-path が存在すればその中身を使う
3. どちらも無い場合は AskUserQuestion でユーザーにクローン先パスを尋ねる。入力されたパスを .git の有無で検証してから設定ファイルに保存し、次回以降は手順2でヒットさせる

CONFIG_FILE="$HOME/.config/claude-skills/badev-knowledge-base-path"
REPO_ROOT="${BADEV_KNOWLEDGE_BASE_PATH:-}"
if [ -z "$REPO_ROOT" ] && [ -f "$CONFIG_FILE" ]; then
  REPO_ROOT=$(cat "$CONFIG_FILE")
fi

if [ -z "$REPO_ROOT" ] || [ ! -d "$REPO_ROOT/.git" ]; then
  echo "NEED_USER_INPUT"   # → AskUserQuestion で対話、検証OKなら $CONFIG_FILE に保存
else
  cd "$REPO_ROOT"
  # 他セッション・他メンバーが push した最新ナレッジを取りこぼさないよう best-effort で pull
  git pull --ff-only origin main 2>/dev/null || echo "（git pull はスキップ。ローカルの内容で検索します）"
fi

• git pull は best-effort。失敗してもローカルにあるもので続行する（オフラインやコンフリクト時に止めない）。
• 対話保存処理は ticket-knowledge-logger の「ベースパスの決定」セクションと完全に同一の仕様（同じ設定ファイルを共有）。

3. 横断検索

チケットディレクトリを全 docs/ ツリーから検索する：

TICKET="BAX-XXXX"   # 抽出した番号に置換
cd "$REPO_ROOT"
echo "=== チケットディレクトリ ==="
find docs -type d -name "${TICKET}_*" 2>/dev/null
echo "=== knowledge/ 内での言及 ==="
grep -rl "$TICKET" docs/knowledge/ 2>/dev/null

• find で {TICKET}_* に一致するディレクトリを全件取得する。
• grep -rl で docs/knowledge/ 配下に当該番号への言及があるファイルを探す。
• 必要なら LOG/README 本文への言及も拾う: grep -rl "$TICKET" docs --include="*.md" 2>/dev/null（番号が別チケットのドキュメント内で参照されているケースを拾いたいとき）。

4. 検索結果のハンドリング

ヒット 0 件の場合

1. まだ pull していない可能性を考え、ステップ2の git pull を未実行なら実行して再検索する。
2. それでも 0 件なら、まだナレッジが記録されていない旨を伝える。
   • 「ticket-knowledge-logger でまだ記録されていないようです」と案内。
   • 必要であれば JIRA チケット本文・コメントを参照する選択肢を提示してもよい（mcp__claude_ai_Atlassian_Rovo__getJiraIssue 等。ただし本スキルの主目的はローカル記録の読み込みなので、ユーザーが望んだ場合のみ）。

ヒット 1 件の場合

そのディレクトリの README.md を読み込み、内容を要約して提示する（ステップ5）。

ヒット複数件の場合

• 見つかったディレクトリを一覧で提示する（ユーザー名・カテゴリ・チケット名が分かる形で）。
• 全件の README.md を読み込み、それぞれ簡潔に要約して並べて提示してよい（件数が少ない＝3件程度までなら推奨）。
• 件数が多い、またはユーザーが特定の1件を読みたそうな場合は、どれを詳しく読むか AskUserQuestion で確認する。

5. ドキュメントの読み込みと提示

1. 必ず README.md を最初に読む（Read ツール）。結論・要点・関連ファイル・参考情報がまとまっている。
2. README が薄い、またはユーザーが詳細・経緯・続きの作業を求めている場合は LOG.md を読む（時系列の詳細）。
3. PLAN.md があり、実装方針やタスク分解が必要な場合は読む。
4. docs/knowledge/ に関連ファイルがあれば、人間向けに整理された横断ナレッジとして併せて参照する。

提示は以下の形でまとめる：

## 📖 {チケット番号} のナレッジ

**場所**: `docs/{ユーザー名}/{カテゴリ}/{チケット番号}_{チケット名}/`（記録者: {ユーザー名}）

### 概要
{README の概要}

### 結論/解決策
{README の結論・解決策}

### 関連ファイル
- `path/to/file.php:123` - {説明}

### 補足
- 詳細な経緯は LOG.md にあります（必要なら読み込みます）
- {PLAN.md / knowledge/ の関連ナレッジがあれば言及}

6. 続きの作業への橋渡し（任意）

ユーザーが「続きをやりたい」「この調査をベースに実装する」等の意図を示している場合：

• README/LOG/PLAN から現状・未完了タスク・next action を抽出して提示する。
• そのまま作業を続け、記録が必要になったら ticket-knowledge-logger で追記する流れを案内する（このスキルは読み込み専用。記録・コミットは行わない）。

注意事項

• このスキルは読み込み専用。ファイルの作成・編集・コミット・JIRA投稿は一切行わない（それらは ticket-knowledge-logger の責務）。
• git pull は best-effort。失敗してもローカルの内容で処理を続行する。
• 自分（実行ユーザー）以外が記録したナレッジもヒットする。記録者が誰かを明示して提示する。
• 同一チケットが複数ディレクトリにある場合は、どれが自分の探しているものか分かるよう全件を簡潔に示してから詳細に入る。
• README を主、LOG/PLAN を従として読む（LOG は長いので、要約に必要な範囲で読む）。

使用例

チケット番号だけで読み直す

ユーザー: 「BAX-10987」

実行:

1. BAX-10987 を抽出
2. git pull（best-effort）
3. find docs -type d -name "BAX-10987_*" → docs/takano/調査/BAX-10987_障害調査（…）/ がヒット
4. README.md を読み込み、概要・結論・関連ファイルを要約して提示
5. 「詳細な経緯は LOG.md にあります」と案内

別メンバーの記録も含めて探す

ユーザー: 「BAX-11027の記録を読み直したい」

実行:

1. find docs -type d -name "BAX-11027_*" → 複数ヒット（例: 実装/BAX-11027_【年払い】契約プラン変更履歴の修正 と 実装/BAX-11027_契約プラン変更履歴の修正）
2. 一覧を記録者・カテゴリ・チケット名付きで提示
3. 各 README を読み込んで要約、または AskUserQuestion でどれを詳しく読むか確認

続きの作業をしたい

ユーザー: 「前に調べたBAX-XXXXの続きで実装したい」

実行:

1. 該当ディレクトリを検索・特定
2. README → 必要なら PLAN/LOG を読み、現状と未完了タスクを整理して提示
3. そのまま作業に入る。記録は ticket-knowledge-logger で追記する旨を案内