self-checking

name	self-checking
description	成果物（コード・調査・ドキュメント）をルーブリックと自動チェックで定量評価し、PASSになるまで改善を繰り返すスキル。「自己評価して」「品質チェックして」「成果物をレビューして」「改善ループ回して」などで発動。scrum-master・skill-mentor からも自動起動される。
metadata	{"version":"1.1.0","tier":"stable","category":"evaluation","tags":["self-checking","evaluation","reflection","quality","code","research","document"]}

self-checking

エージェントが自身の成果物を評価・改善する反復ループスキル。コード・調査レポート・ドキュメントに対応する。

生成・実行 → 自己評価 → 改善 → 再評価 → 合格
     ↑                                      │
     └──────── スコア未達の場合のみ ─────────┘

パス解決

このSKILL.mdが置かれているディレクトリを SKILL_DIR とする。

• スクリプト: ${SKILL_DIR}/scripts/check.py
• ルーブリック: ${SKILL_DIR}/references/rubrics/

---

対応する成果物の種別

artifact_type	対象	ルーブリック
code	ソースコード・テストコード・設定ファイル	${SKILL_DIR}/references/rubrics/code.md
research	調査レポート・技術調査・競合分析	${SKILL_DIR}/references/rubrics/research.md
document	設計書・要件定義書・README・仕様書	${SKILL_DIR}/references/rubrics/document.md

artifact_type が不明な場合は check.py --detect [file] で自動検出する。

---

実行プロトコル

Step 1: 成果物と種別の確認

1. 評価対象の成果物と artifact_type を確認する
2. artifact_type が未指定の場合:

   python ${SKILL_DIR}/scripts/check.py --detect [対象ファイルパス]
   

   出力例: {"artifact_type": "code", "confidence": 0.95}
3. 対応するルーブリックファイルを読み込む:

   # 例: code の場合
   # ${SKILL_DIR}/references/rubrics/code.md を読む
   

4. 完了基準（done_criteria）が渡されている場合は評価基準に追加する

---

Step 2: 自動チェックの実行

スクリプトで定量チェックを実施する:

python ${SKILL_DIR}/scripts/check.py \
  --type [artifact_type] \
  --files [対象ファイルパス（スペース区切り、複数可）] \
  --criteria "[完了基準（任意）]"

出力例（JSON）:

{
  "artifact_type": "code",
  "checks": {
    "syntax": {"passed": true, "details": ""},
    "completeness": {"passed": true, "details": ""},
    "test_presence": {"passed": false, "details": "テストファイルが見当たらない"}
  },
  "auto_score": 0.67,
  "failed_checks": ["test_presence"]
}

スクリプト失敗時（ファイルなし・パースエラー等）は自動チェックをスキップし、ルーブリック評価のみを実施する。

---

Step 2.5: 実行証拠ゲート（code のみ・必須）

artifact_type が code の場合、「動くはず」という推論だけで PASS にしてはならない。 完了報告の前にエージェント自身が実際に動かし、客観的な実行証拠を取得する。これにより人間が後追いで検証する手間を肩代わりする。

証拠として認める成果（いずれか 1 つ以上、対象成果物に応じて選ぶ）:

証拠	取得方法の例
テスト実行結果	テストランナーを実行し、件数・成否（pass/fail）の実出力を取得
ビルド／型チェック／リンタ	ビルド・型・lint コマンドを実行し、終了コードと出力を取得
実行ログ	スクリプト・CLI を実際に走らせ、想定どおりの出力を確認
画面の挙動	Web/UI は webapp-testing（Playwright）で操作し、スクリーンショット・コンソールログを取得

ゲート判定:

• 実行証拠が取得できた → execution_evidence = "verified"。証拠の要約（実行コマンド・結果）を記録して Step 3 へ
• 実行が環境制約等で不可能だった → execution_evidence = "blocked"。理由と、人間が確認すべき手順を blocking_issues に明記して Step 3 へ。この場合 PASS にはできず NEEDS_IMPROVEMENT が上限
• まだ実行していない → 実行してから判定する（未実行のまま先へ進まない）

research / document ではこのゲートは適用しない（Step 3 へ直行）。

---

Step 3: ルーブリック評価

読み込んだルーブリックに従って各ディメンションを評価する。

評価スケール: 各ディメンションを 1〜5 で採点し、重み付き合計スコアを算出する。

スコア = Σ (採点 / 5 × 重み)

評価結果を以下の形式で記録する:

{
  "dimensions": {
    "[ディメンション名]": {
      "score": 4,
      "weight": 0.3,
      "verdict": "PASS",
      "feedback": "[評価コメント]"
    }
  },
  "rubric_score": 0.82,
  "failed_dimensions": ["[基準未達のディメンション名]"]
}

判定閾値:

• rubric_score >= 0.8 かつ auto_score >= 0.7（自動チェックあり時）かつ 実行証拠ゲートを通過（code 時は execution_evidence == "verified"） → PASS
• それ以外 → NEEDS_IMPROVEMENT（改善ループへ）

code で実行証拠が blocked の場合、スコアが閾値を超えていても PASS にはできない。NEEDS_IMPROVEMENT のまま、人間が確認すべき手順を添えて返す。

---

Step 4: 改善ループ（NEEDS_IMPROVEMENT の場合のみ）

基準未達のディメンション・チェック項目のみを対象に改善し、PASS になるまで繰り返す。

終了条件（どちらか先に満たした方で Step 5 へ進む）:

条件	判定	次の処理
rubric_score >= 0.8 かつ auto_score >= 0.7（自動チェックあり時）かつ 実行証拠ゲート通過（code 時）	PASS	Step 5 へ
連続 2 イテレーションでスコア改善幅 < 0.03（収束）	NEEDS_IMPROVEMENT	Step 5 へ（外部レビューに引き渡す）

改善ループでは、実行証拠が blocked／未取得のまま PASS 条件に到達しても PASS とせず、まず実行証拠の取得を試みる。

各イテレーション:
  1. 失敗した項目を特定する: failed_dimensions + failed_checks
  2. 各失敗項目について改善を実施する
  3. 改善内容を記録する: {"dimension": "...", "action": "...", "before": "...", "after": "..."}
  4. Step 2〜3 を再実施してスコアを再計算する
  5. 終了条件を確認する → 満たせば Step 5 へ。満たさなければ 1 へ戻る

改善時の注意:

• 失敗していない項目には手を加えない
• ただし、ある基準の改善が用語・構造・前提に波及する場合、その波及先は失敗項目でなくても整合のために修正する。整合性のための波及修正は回帰リスクではなく回帰防止である
• 改善前後のスコアと主な変更点を記録する

---

Step 5: 結果報告

評価結果を以下の形式でまとめる:

## 自己評価結果

| 項目 | 値 |
|------|-----|
| 種別 | [artifact_type] |
| 最終判定 | PASS ✅ / NEEDS_IMPROVEMENT ⚠️ |
| ルーブリックスコア | [0.0〜1.0] |
| 自動チェックスコア | [0.0〜1.0 / N/A] |
| 実行証拠 | verified ✅ / blocked ⚠️ / N/A（code 以外） |
| 反復回数 | [0〜N（PASS or 収束まで）] |

実行証拠が `verified` の場合は、実行したコマンドと結果の要約を「改善の軌跡」または専用の小節に残す。

### ディメンション別結果

| ディメンション | スコア | 判定 | コメント |
|---|---|---|---|
| [name] | [N]/5 | PASS ✅ / FAIL ❌ | [feedback] |

### 改善の軌跡

[反復ごとの変更概要]

### 残存する懸念事項（あれば）

[最終反復後も未解決の項目]

verdict-json（オーケストレーターが読み取る構造化出力）:

<!-- verdict-json -->
{
  "skill": "self-checking",
  "verdict": "PASS | NEEDS_IMPROVEMENT",
  "artifact_type": "[code|research|document]",
  "rubric_score": 0.0,
  "auto_score": 0.0,
  "execution_evidence": "verified | blocked | n/a",
  "evidence_summary": "[実行したコマンドと結果の要約。code かつ verified 時は必須]",
  "iterations": 0,
  "improved_files": [],
  "blocking_issues": []
}
<!-- /verdict-json -->

---

ベストプラクティス

プラクティス	理由
失敗した基準のみ改善する（整合性の波及は例外）	合格済み項目への不要な変更を防ぎ、回帰リスクを下げる。ただし整合性に関わる波及は失敗項目外でも修正対象とする
PASSになるまで改善する	回数ではなく「スコア閾値を超えるまで」を終了条件とする
収束で安全に終了する	連続 2 回の改善幅 < 0.03 で収束とみなし、NEEDS_IMPROVEMENT のまま外部レビューに引き渡す
自動チェックとルーブリックを組み合わせる	定量的な客観指標と定性的な評価の両方を担保する
code は実行で裏取りしてから PASS にする	「動くはず」を排し、人間の後追い検証の手間を肩代わりする。証拠の要約を必ず残す
改善履歴をログに残す	デバッグと振り返り分析のために全反復のトレースを保持する

---

エラーハンドリング

状況	対応
check.py が失敗する	ルーブリック評価のみで続行。自動チェックスコアは N/A とする
ルーブリックファイルが見当たらない	artifact_type に最も近いルーブリックを使用するか、汎用的な評価（正確性・完全性・明確性）で代替する
収束（連続 2 イテレーションで改善幅 < 0.03）してもスコアが閾値未達	NEEDS_IMPROVEMENT のまま結果を返す。外部レビュー（agent-reviewer）で追加確認する
成果物ファイルが存在しない	エラーを報告してスキルを終了する