self-improve

name	self-improve
description	Analyze accumulated blueprint usage logs and generate improvement PRs for the plugin itself. Use when the user wants to "improve blueprint plugin", "analyze blueprint logs", "self-improve", "check improvement opportunities", "generate improvement PR", "review plugin usage patterns", "blueprint-improve", or "show blueprint stats". Also use when the user says "blueprint改善", "ログ分析", "自己改善", "改善PRを出す", "プラグインを改善する", "使用パターンを分析", or "ログの統計を見せて". This skill reads usage logs from ~/.claude/blueprint-logs/ and identifies recurring patterns, common errors, and user correction frequencies to propose concrete improvements to the blueprint-plugin's core specs, skills, and templates.
version	1.1.0
core_ref	core/self-improve.md

Self-Improve スキル (Claude Code)

blueprint パイプラインの使用ログを分析し、改善案を PR として提出するスキル。 ログは SessionEnd Hook で自動収集され、このスキルで分析・改善サイクルを回す。

仕様参照

分析ポリシーは core/self-improve.md に定義。 ログスキーマは {baseDir}/references/log-schema.md を参照。 分析サマリースキーマは {baseDir}/references/analysis-schema.md を参照。

前提条件

条件	必須	説明
未分析ログ	○	~/.claude/blueprint-logs/ に triage.status: open のログが 1 件以上
gh CLI	△	PR 作成時のみ必要
blueprint-plugin リポジトリ	△	PR 作成時のみ。パスは自動検出（$CLAUDE_PLUGIN_ROOT）

ツール

ツール	用途
Bash	analyze_logs.sh 実行、gh pr create、git 操作
Read	ログファイル読み込み、改善対象ファイル読み込み
Write/Edit	改善案の適用
Glob	ログファイルの検索
AskUserQuestion	改善案のユーザー承認

出力

出力	説明
統計レポート	YAML 形式のログ分析サマリー（stdout 表示）
改善 PR	sizukutamago/blueprint-plugin への GitHub PR
分析サマリー	~/.claude/blueprint-logs/analysis/analysis-{YYYYMMDD}.yaml
トリアージ更新	対象ログの triage.status を pr_created に更新

コマンドオプション

オプション	説明	ワークフロー
/blueprint-improve	分析 → 改善案提示 → PR 作成	Step 1〜6 全実行
/blueprint-improve --stats	統計レポートのみ表示	Step 1 のみ実行して終了
/blueprint-improve --cleanup	期限切れログの削除	専用フローを実行（下記参照）

ワークフロー

Step 0: モード判定

引数を確認し、モードに応じて分岐する:

• --stats → Step 1 のみ実行して統計レポートを表示し終了
• --cleanup → 期限切れログ削除フローへ（下記「cleanup モード」参照）
• 引数なし → Step 1〜6 を順に実行

Step 1: ログ読み込みと統計レポート生成

# 未分析ログ数の確認
bash "${baseDir}/scripts/analyze_logs.sh" --count

# 統計レポートの生成
bash "${baseDir}/scripts/analyze_logs.sh" --details

未分析ログが 0 件の場合は「分析対象のログがありません」と報告して終了。

統計レポートの出力を読み取り、以下を把握:

• ログ件数と期間（log_range の from / to）
• Gate findings の P0/P1/P2 分布
• エラー数とユーザー修正数
• category 別・phase 別・stage 別の分布

--stats モードの場合はここで統計レポートをユーザーに表示して終了。

Step 2: パターン分析

core/self-improve.md の分析ポリシーに従い、統計レポートから改善パターンを特定する。

1. recurring_findings の検出: category 別集計から閾値（3 回以上）を超えるパターンを抽出
2. common_errors の検出: phase 別集計から反復エラーを抽出
3. user_corrections の検出: stage 別修正頻度から生成品質の問題を特定

検出したパターンから、改善対象ファイルを core/self-improve.md の「改善案のカテゴリ」表に従い特定する:

パターン種別	対象ファイル	改善カテゴリ
Gate の category 反復	core/review-criteria.md	review_criteria_update
/requirements 関連の修正	core/requirements.md, skills/requirements/SKILL.md	requirements_update
/spec 関連の修正	core/spec.md	spec_update
Contract 関連の指摘	core/contract-schema.md	schema_update
実装規約のエラー	core/defaults/	default_update
テンプレート品質	skills/*/references/	template_update
スキル手順の問題	skills/*/SKILL.md	skill_update

改善対象ファイルを Read ツールで読み込み、具体的な改善案を生成する。

Step 3: 改善案提示 + ユーザー承認

AskUserQuestion で改善案を一覧提示する。以下のフォーマットで提示:

## 改善案一覧（{count} 件）

分析期間: {from} ~ {to}（{log_count} セッション）

### [1] {改善タイトル}  ⬆ {priority}
- 根拠: {category} が {count} 回検出
- 対象: {target_file}
- 内容: {description}

### [2] ...

---
採用する改善案の番号を選択してください（例: 1,3）
全て採用: all / 全て棄却: none

ユーザーが採用/棄却を選択。全棄却の場合はログの triage.status を analyzed に更新して終了。

Step 4: 変更適用 + PR 作成

ブランチ作成前に、blueprint-plugin リポジトリの状態を確認する:

PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"

# 作業ディレクトリの状態確認（未コミット変更があれば警告）
git -C "$PLUGIN_ROOT" status --short

# feature branch を作成（日時で一意性を保証）
BRANCH_NAME="self-improve/$(date +%Y%m%d-%H%M%S)"
git -C "$PLUGIN_ROOT" checkout -b "$BRANCH_NAME"

未コミット変更がある場合はユーザーに警告し、続行するか確認する。

承認された改善を Edit/Write ツールで適用した後:

# 変更したファイルのみを明示的に add（git add -A は使わない）
git -C "$PLUGIN_ROOT" add <変更したファイルパス1> <変更したファイルパス2> ...

git -C "$PLUGIN_ROOT" commit -m "$(cat <<'EOF'
self-improve: [改善の要約]
EOF
)"

# push + PR 作成
git -C "$PLUGIN_ROOT" push -u origin "$BRANCH_NAME"
PR_URL=$(gh pr create --repo sizukutamago/blueprint-plugin \
  --title "self-improve: [改善の要約]" \
  --body "$(cat <<'EOF'
## Summary
Blueprint self-improvement: {改善の要約}

## Evidence
- 分析期間: {from} ~ {to} ({count} セッション)
- 検出パターン: {patterns}

## Changes
- {file}: {変更概要}

---
Auto-generated by `/blueprint-improve`
EOF
)")

PR_URL を後続の Step 5 で使用するため保持する。

Step 5: トリアージ更新

Step 1 で分析対象となったログのみを更新する。統計レポートの log_range.from / log_range.to を使い、対象範囲を特定する:

# Step 1 で取得した対象ログ一覧を使用（analyze_logs.sh が処理した open ログ）
FIRST_LOG="<log_range.from の値>"
LAST_LOG="<log_range.to の値>"

# 対象ログのみ更新（全 open ログではなく、分析対象に含まれたもののみ）
for log_file in ~/.claude/blueprint-logs/bl-*.yaml; do
    [ -f "$log_file" ] || continue
    LOG_ID=$(basename "$log_file" .yaml)
    # log_range 内のログのみ対象
    if [[ "$LOG_ID" >= "$FIRST_LOG" && "$LOG_ID" <= "$LAST_LOG" ]] && grep -q 'status: open' "$log_file"; then
        sed -i '' 's/status: open/status: pr_created/' "$log_file"
        sed -i '' "s/analysis_range: \"\"/analysis_range: \"${FIRST_LOG} ~ ${LAST_LOG}\"/" "$log_file"
        sed -i '' "s|pr_url: \"\"|pr_url: \"${PR_URL}\"|" "$log_file"
    fi
done

Step 6: 分析サマリー保存

~/.claude/blueprint-logs/analysis/analysis-{YYYYMMDD}.yaml に分析結果を保存。 ディレクトリが存在しない場合は作成する。 スキーマは {baseDir}/references/analysis-schema.md を参照。

---

cleanup モード

/blueprint-improve --cleanup で実行。期限切れログ（privacy.expires_at が現在日時より前）を削除する。

# 期限切れログの検出
EXPIRED_COUNT=0
for log_file in ~/.claude/blueprint-logs/bl-*.yaml; do
    [ -f "$log_file" ] || continue
    EXPIRES=$(grep 'expires_at:' "$log_file" | head -1 | sed 's/.*: *//' | tr -d '"')
    if [ -n "$EXPIRES" ] && [[ "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$EXPIRES" ]]; then
        echo "期限切れ: $(basename "$log_file") (expires: $EXPIRES)"
        EXPIRED_COUNT=$((EXPIRED_COUNT + 1))
    fi
done

期限切れログがある場合、AskUserQuestion で削除確認を取ってから rm で削除する。 triage.status が analyzed 以降のログは TTL に関わらず保持する（core/self-improve.md のポリシーに従う）。

原則

• ユーザー承認必須: PR 作成前に必ず改善案の承認を取得する
• 最小変更: 1 PR に含める改善は関連するパターンのみ。無関係な改善は分割する
• エビデンス駆動: 全ての改善案に検出パターンと件数の根拠を添える
• 重複防止: fingerprint と analysis_range で同一ログの再分析を防ぐ
• 明示的ステージング: git add は変更したファイルのパスを明示的に指定する（-A は使わない）

エラーハンドリング

状況	対応
ログ 0 件	「分析対象のログがありません」と報告して終了
gh CLI 未インストール	改善案の表示まで行い、PR 作成はスキップ。手動手順を案内
blueprint-plugin リポが見つからない	$CLAUDE_PLUGIN_ROOT でフォールバック
分析スクリプトエラー	エラー内容を表示し、ログファイルの直接読み込みにフォールバック
リポに未コミット変更あり	ユーザーに警告し、続行するか確認
ブランチ名衝突	日時ベースの命名（%Y%m%d-%H%M%S）で回避