maintain-verification-skill

Files (1)

• SKILL.md

SKILL.md (first lines)

# 検証スキルをメンテナンスする

機能マップは、アプリが変更された瞬間から古くなります。このスキルは、`/create-verification-skill` で生成されたスキル（または機能マップを持つ任意のプロジェクトローカルな検証スキル）のメンテナンスループです。厳密さの単位は、個々の文ではなく機能です。すべての箇条書きを 1 つずつ完結させる必要はなく、すべての機能ファイルをソースから網羅し、すべての機能をライブで実行してください。

## 結果

以下から 1 つを選び、どれを選んだか明示してください。

- **clean** - すべての機能をソースとライブの両方で網羅し、ship する価値のあるものはありません。ブランチも PR も作成しません。
- **changed** - 証明済みのドキュメント、ハーネス、マップの修正を 1 件の PR で ship します。
- **blocked** - 網羅を完了できなかったか、証明済みの修正を安全に ship できませんでした。何が妨げたかを正確に伝えます。

## 編集範囲

検証スキル自身のディレクトリ（その `SKILL.md`、`features/`、およびスキルが所有するハーネススクリプト）だけを編集してください。実行中にプロダクトコードを編集してはいけません。アプリがマップに記載された振る舞いをしなくなった場合、それはドキュメントの乖離（マップを修正）またはプロダクトのリグレッション（報告し、ドキュメントで取り繕わない）のいずれかです。

## パス

0. **対象を特定する。** メンテナンス対象の検証スキルを探します。本文に launch/drive セクションと機能マップがあるプロジェクトローカルなスキルです（通常は `.pi/skills/verify-*/`）。候補が複数ある場合は、どれかを質問してください。候補がない場合は、対象をでっち上げずに停止し、代わりに `/create-verification-skill` を案内してください。

1. **索引を健全に保つ。** 機能マップの README を読み、同階層のファイルを glob します。欠落、余分、重複、無効なエントリーを修正してください。これは軽量な作業です。生成されたインベントリは不要です。

2. **ソースウェーブ。** 機能ファイルごとに読み取り専用のサブエージェントを 1 つ、並行して起動します。各エージェントは「このユーザー向け機能はどのように動くか」をソースから説明し、ドキュメントが乖離している可能性を引用付きで指摘し、簡潔なライブ検証レシピを 1 つ返します。子エージェントはアプリを操作せず、ファイルも編集しません。返却形式は、機能の要約 / ソース上のエントリーポイント / 乖離の可能性または none / 1 つのレシピです。

3. **照合する。** すべての機能ファイルについて要約が返っていることを確認します。重複するレシピは、実用的な範囲で最小限のアプリ状態に統合します。引用された乖離は抜き取り確認し、問題なしとされた主張を再証明しないでください。最近変更された箇所を調べ、マップから漏れたユーザー向けサーフェスがないか確認します。欠落と判断するには、具体的なソースパスが必要です。

4. **ライブパス。** ソースに問題がないように見える場合でも必須です。すべての操作はコーディネーターが担当します。検証スキル自体の起動モデルに従ってください。サーバーと UI では長時間稼働する 1 つのインスタンスを直列に操作し、短時間で終了する CLI では操作ごとに新しい分離セッションを使用します（このスキルではなく、検証スキルの Launch セクションが決定します）。すべての機能を少なくとも 1 回実行し、どのような失敗が起きても、パス全体で次の 3 つの不変条件を守ってください。(1) 最後に意外な動作をして以降 health-check していないインスタンスは、決して操作しないこと。最初の操作前、セッションが単位の場合は新しいセッションごと、操作失敗後に doctor を実行してください。doctor で失敗を検出できない場合（正常なプロセス内で UI 状態が固まっているなど）は、期待に頼らず、既知の状態にリセットするか再起動してください。(2) それまでに取得した証拠がすべてのクリーンアップ後も残っていること。指定場所で確認し、推測しないでください。(3) 操作が開始したものは、その操作で有用でなくなった後まで残さないこと。セッションが停止、終了、共有のいずれであっても、失敗した反復の残留物をクリーンアップしてください（共有インスタンスでは、インスタンスではなく残留物をクリーンアップします）。スキルの乖離による doctor の失敗は乖離です。パスを `blocked` と判断する前に、編集範囲内で修正して一度だけ再試行してください。その際、修正で無効になったものだけを再起動し、それ以上は行いません。到達不能な機能を `verified-unreachable` とできるのは、具体的な前提条件（認証、権限、OS、外部状態）と試行したルートがある場合だけです。マップにその前提条件がなければ、それは乖離です。トリアージでハーネスを修正した場合、ship する前にライブで再操作してください。最後の操作（再証明を含む）が終わった後に最終終了処理を行い、実行したものを何も残さないでください（スキルの規定どおり、証拠は残します）。

5. **トリアージする。** ユーザー視点の説明が誤っている、または欠けている場合はドキュメントの乖離なので修正します。動作している振る舞いをハーネスで操作できない場合はハーネスの不足なので修正します。ハーネスの修正には、生成時と同じ helpers ルールが適用されます（スクリプトに実行権限を付け、呼び出し方法をスキル本文に記載します）。アプリの振る舞いが実際に壊れている場合はプロダクトの不足です。ユーザー向けに記録し、この PR には含めません。

6. **Ship または停止する。** changed の場合は、証明済みの修正を 1 件の PR にまとめます。その前に、変更したすべてのファイルを読み直してください。clean または blocked の場合は PR を作らず、結果と網羅状況を正直に報告します。

簡潔な実行メモ（網羅した機能、到達不能の前提条件、確認済みの乖離、結果）を一時的な場所に保存し、コミットしないでください。

From yasuhito/skills, MIT.

More from yasuhito/skills