automated-assessment

自動評価スキル

チェックポイントに対応したスキルを対象とする体系的なコンプライアンス評価です。

使用方法

/assess                              # All matching skills
/assess skill-repo typo3-testing     # Specific skills only
/assess --force                      # Ignore preconditions
/assess --mechanical-only            # Scripted checks only
/assess --autofix                    # Fix issues automatically
/assess --review                     # Categorize failures
/assess --autoimprove                # Fix + propose improvements
/assess dependency-compatibility     # Dependency compat checks
/assess --pre-push                   # Pre-push validation gate
/assess --check-coverage             # Verify checkpoint coverage

オプション

オプション	効果
<skill-names>	指定したスキルのみのチェックポイントを実行します（dependency-compatibility などのドメイン名も指定できます）
--force	前提条件のチェックをスキップします
--mechanical-only	LLM によるレビューをスキップします
--autofix	担当スキルで不備を修正し、再検証します
--review	不備を分類し、スキルの改善案を提案します
--autoimprove	修正とチェックポイントの変更案を作成します。課題を登録するには --create-issues を追加します
--json	JSON をそのまま出力します
--pre-push	プッシュ前のゲートを実行します（PHPStan、テスト、PHP-CS-Fixer、Rector）
--check-coverage	チェックポイントのカバレッジが十分か確認します

手順

1. 対象のリビジョン、環境、想定範囲を記録し、該当するチェックポイントを特定します
2. 機械的なチェックポイントを実行し、実行上の失敗とプロジェクトの不備を分けて記録します
3. 必要な LLM チェックのみをドメインごとにまとめ、候補となる指摘を個別に検証します
4. 確認済みの指摘、未解決のチェック、カバレッジを分けて報告します

LLM レビューでは、references/checkpoint-workflow.md に記載された候補／検証の手順に従ってください。 検証者には生の証拠と関連リポジトリへのアクセスを提供し、作成者の結論は伝えないでください。 独立したリスクに限り、並行して専門家に確認を依頼してください。リビジョンとプロパティが変わっていない場合は証拠を再利用し、スキルごとに新たなループを開始しないでください。タスクのレビューバジェットを共有し、明示的に未解決とするまでの修正／レビューのラウンドは最大3回としてください。

評価を先に行うルール

カバレッジ、ミューテーションテスト、品質ゲート、静的解析レベルなど、プロジェクト全体の品質向上に着手する前に、該当する評価を実施してください。そのギャップレポートをタスクリストとして扱います。範囲がすでに限定されている小規模な変更は、その範囲に集中させてください。該当するチェックポイントがない場合、無関係な評価を作り出したり、要望に近いだけのスキルで代用したりしないでください。

ワークフロー

1. 関連するスキルを指定して /assess を実行します
2. ギャップレポートを確認します。このレポートがタスクリストになります
3. 優先順位に従って修正します（警告よりエラーを優先し、自動解決には --autofix を使用します）
4. /assess を再実行して検証します

該当するスキルがない場合は、その旨を伝えてください

最も近いスキルではなく、該当するスキルがないと判断してください。 利用可能なスキルのチェックポイントが要望をカバーしていない場合は、そのことを報告して終了します。隣接するドメインのスキルで代用すると、測定されたアブレーションではスキルがない場合よりもスコアが低くなりました。詳しくは references/capability-selection.md を参照してください。

この判断はチェックポイントの実行前に行われるため、シリアライズする実行結果はありません。--json で出力するレポートもなく、呼び出し元への回答は、ギャップと該当しそうでも要望を満たさないスキルを示す文章になります。skill_gaps の行を作り出さないでください。この形式はチェックポイントに失敗した skill を含みますが、ここではスキルが選択されておらず、評価も行われていません。

/assess を使わずに 1 つのスキルのチェックを実行する

1 ホップ形式は、スキル名を指定するスラッシュコマンド、つまり /assess typo3-extension-upgrade です。別のスキルのワークフロー内から使う場合は、この方法を選んでください。パスは不要です。

直接呼び出す方法は、スラッシュコマンドがないスクリプトやハーネス向けです。ローダーのベースディレクトリからの相対パス、チェックポイントファイル、最後の引数としてプロジェクトのルートを指定します。すべての target: はそのルートを基準に解決されるため、それ以外の場所から実行すると、チェック対象のツリーが誤ってしまいます。チェックポイントファイルは、スキルのフロントマターで checkpoints: の下に指定されているファイルです。何も指定されていない場合に限り、スキルのベースディレクトリにある checkpoints.yaml が使われます（references/checkpoint-workflow.md の検出ルールを参照してください）。独自のチェックポイントファイルを指定しているスキルにルートレベルのファイルを渡すと、誤ったファイルが実行されるか、ファイルが実行されません。

cd <project-root>
"$SKILL_DIR/../automated-assessment/scripts/run-checkpoints.sh" --force \
  "<the checkpoint file that rule resolves to>" .

実測した結果が、スラッシュコマンドを最初に挙げている理由です。直接呼び出す方法をスキル本文の手順として配置した場合、エージェントのコンテキストに含まれたのは 3 回中 3 回でしたが、実行は一度もされませんでした。12 回の試行のうち、変数を何らかの形でバインドしたものはありませんでした。つまり、組み立てる必要のあるパスは使われません。一方、貼り付けたまま実行できるブロックとして本文に記述した同じチェックは、3 回中 3 回実行されました。呼び出し元が前提条件を満たしていると把握している場合は、--force でその確認をスキップできます。--json は機械可読なレポートを出力します。各結果行には、チェックポイント ID、その desc、証拠文字列が含まれます。script タイプのチェックでは、証拠は "Script failed" のみです。ランナーはスクリプト自体の出力を引き継がないため、どこを確認すればよいかはチェックの desc で判断してください。blocked の行は、ランナーがコマンドを拒否し、チェックが実行されなかったことを示します。

チェックポイントの種類

機械的： file_exists、file_not_exists、contains、not_contains、regex、json_path、gh_api、command。LLM： llm_review（ドメイン別にグループ化）。references/checkpoints-schema.md を参照してください。

ドメイン

repo-health security code-quality documentation git-workflow docker ddev upgrade dependency-compatibility pre-push

自動修正とレビュー

--autofix は失敗に対処するスキルを呼び出し、再検証します。ステータス：auto-fixed、needs-review、unfixable。--review／--autoimprove はフィードバックループを作成します。

プッシュ前のゲート

インストール済みのツール（vendor/bin/*）のみをチェックします。実行可能ファイルがない場合はスキップされ、合格とは見なされません。ツールがスキップされた状態で正常終了しても、検証が完了したことにはなりません。ID：PP-01（PHPStan）、PP-02（PHPUnit）、PP-03（PHP-CS-Fixer）、PP-04（Rector）。

重大度

error ＝リリースをブロック、warning ＝推奨事項、info ＝任意。

成果

pass fail skip blocked — それぞれ個別にカウントされます（total == pass + fail + skip + blocked）。実行可能ファイルが存在しないコマンド（Composer がない場合の vendor/bin/*、PATH 上にないツール）は、検出事項ではなく、証拠 executable not found: <word> を伴う skip です。

blocked のチェックポイントを検出事項として報告してはいけません。 これは、ランナーが許可リストによってコマンドの実行を拒否したことを意味するため、何も測定されていません。不備があるのは評価対象のプロジェクトではなく、チェックポイントファイルです。ブロックされたチェックポイントは壊れたチェックとして報告し、該当するスキルに対して scripts/validate-checkpoints.sh <file> を実行して、そちらに報告してください。前提条件が拒否された場合も、一段階上で同じ扱いになります。JSON の理由にある REFUSED by the runner allowlist は、「このスキルは適用されない」と同じ意味ではありません。references/checkpoints-schema.md →「Outcomes」を参照してください。

確認された検出事項がゼロであることが妥当なのは、測定対象の範囲を明示している場合に限ります。ツールやリソースの不足、タイムアウト、証拠を利用できない状態、レビューの中断があると、その範囲は不完全になります。これらは、否定的なテストの成功でも、プロジェクトに不具合がある証拠でもありません。ランナーの4つのステータスを維持し、実行の原因を評価レポートに記録してください。静的レビューはテストの実行ではなく、レポート自体がマージゲートを適用したり、人間による承認とみなされたりすることもありません。証拠レベルについては references/verification-patterns.md を、検出事項の処置と後から見つかった不具合については references/calibration.md を参照してください。

参考資料

• references/checkpoints-schema.md -- チェックポイントの YAML スキーマと型
• references/learning-derived-checkpoints.md -- レトロスペクティブからチェックポイントへの振り分け契約
• references/checkpoint-coverage-requirements.md -- スキルごとに必要なカバレッジのカテゴリ
• references/capability-selection.md -- 代替するよりも辞退するほうがよい理由と、その効果を測定したアブレーション
• references/checkpoint-workflow.md -- 自動修正ループを含む評価ワークフローの全体
• references/calibration.md -- キャリブレーション負債、監査の頻度、生成時の基準点、ラチェットのアンチパターン
• references/dependency-compatibility.md -- 複数のメジャーバージョンを対象とする評価のトリガー
• references/migration-guide.md -- 既存のスキルにチェックポイントを追加する方法
• references/verification-patterns.md -- 検証パターンと結果スキーマ