utility-pm-skill-iterate

PM Skill Iterate

このスキルは、ユーザーが提供する入力に基づいて対象を絞った変更を適用し、既存の pm-skills スキルを改善します。現在のスキルファイルを読み込み、ファイルごとにまとめた変更前／変更後のプレビューを提示し、ユーザーの確認後に変更を書き込みます。変更を適用した後、バージョン更新の種別を提案し、HISTORY.md の更新を提案します。

イテレーターは、次のいずれかを入力として受け付けます。

• utility-pm-skill-validate による検証レポート
• 直接的なフィードバック（「テンプレートにセクション X がありません」など）
• 規約の変更（「すべてのスキルに Limitations セクションが必要になりました」など）
• 全般的な改善依頼（「例をより現実的にする」など）

使用するタイミング

• utility-pm-skill-validate を実行し、指摘事項を含むレポートを受け取った後
• スキルへの具体的なフィードバックがあり、それを適用したい場合
• リポジトリの規約が変更され、スキルを準拠させる必要がある場合
• スキルの例、テンプレート、または手順を改善する必要がある場合
• リリース前にスキルを反復的に改善する場合

使用しないタイミング

• 新しいスキルをゼロから作成する場合 → utility-pm-skill-builder を使用します
• 変更を加える前にスキルを監査する場合 → まず utility-pm-skill-validate を使用します
• 複数のスキルに対して規約を一括変更する場合 → まず utility-pm-skill-validate --all を実行して優先順位を付け、その後、スキルを一つずつ反復します

手順

スキルの反復改善を依頼された場合は、次の手順に従います。

ステップ 1：対象のスキルを特定する

スキル名は、次のいずれの形式でも受け付けます。

• ディレクトリ名：deliver-prd
• フルパス：skills/deliver-prd/SKILL.md
• スラッシュコマンド：deliver-prd

正規のディレクトリパス skills/{name}/ に解決します。

スキルのディレクトリが存在しない場合は、作業を中止して次のように報告します。「スキルのディレクトリ skills/{name}/ が存在しません。作成するには utility-pm-skill-builder を使用してください。」

ステップ 2：現在のスキルファイルを読む

スキルのディレクトリにあるすべてのファイルを読み込みます。

ファイル	必須	目的
SKILL.md	はい	フロントマターと手順（主な編集対象）
references/TEMPLATE.md	はい	出力テンプレート
references/EXAMPLE.md	はい	作成例
HISTORY.md	いいえ	バージョン履歴（ステップ 7 で必要）

この時点で、各ファイルの正確な内容を記録します。ステップ 5 で書き込む前にこの内容と比較します（古いプレビューを防ぐため）。

ファイルを読み込めない場合（MCP／埋め込み環境）は、作業を進める前に、関連するファイルの内容をユーザーに貼り付けてもらいます（「制限モード」を参照）。

ステップ 3：入力を意図する変更に整理する

入力の種類にかかわらず、編集を生成する前に、意図する変更を構造化したリストにまとめます。この整理手順によって、すべての入力形式で一貫したフローを実現します。

入力が検証レポートの場合（utility-pm-skill-validate によるもの）：

• ヘッダーに Report schema: v1 があるか確認します。ない場合、または異なるスキーマバージョンの場合は、次のように警告します。「このレポートのスキーマは認識されていません。最善を尽くしますが、構造化フィールドを見落とす可能性があります。」
• ## Recommendations セクションを解析します。
• 各推奨事項の行を | で分割し、次の内容を抽出します。
  • 位置 1：重大度（FAIL、WARN、INFO）
  • 位置 2：チェック ID
  • Target: の後：ファイルパス
  • Action: の後（次の行）：変更内容
• これらのフィールドから、意図する変更のリストを作成します。

入力が自由記述の場合（フィードバック、規約の変更、改善依頼）：

• 入力を読み、変更が必要な内容を特定します。
• 各変更を、具体的な対象ファイルとセクションに対応付けます。
• 入力が曖昧な場合は、作業を進める前に確認の質問を1つだけします。

正規化したリストを提示して、ユーザーの確認を求めます。

Intended changes:
1. Target: skills/{name}/SKILL.md -> {section}
   Change: {what will change}
   Source: {validation report check ID | user feedback | convention change}
2. Target: skills/{name}/references/EXAMPLE.md -> {section}
   Change: {what will change}
   Source: {source}

ユーザーがリストの変更（項目の追加、削除、変更）を希望する場合は、修正して再提示してから作業を進めます。

ステップ 4：変更案をプレビューする

意図する変更ごとに、変更案を生成し、ファイルごとにまとめて変更前／変更後のブロックとして提示します。

### skills/{name}/SKILL.md

**{Section name} -- before:**
> {exact current content of the section being changed}

**{Section name} -- after:**
> {proposed new content for this section}

### skills/{name}/references/EXAMPLE.md

**{Section name} -- before:**
> {exact current content}

**{Section name} -- after:**
> {proposed new content}

プレビューのルール：

• すべての変更をファイルごとにまとめます。各ファイルは一度だけ表示し、そのファイルのすべての変更を含めます。
• ユーザーが変更内容を理解できるよう、周辺のコンテキストを十分に表示します。
• 小規模な編集（数行程度）では、変更前と変更後のセクション全体を表示します。
• 大規模な編集（セクションの大部分を書き換える場合）では、変更前はセクション見出しと冒頭・末尾の数行を表示し、変更後は全体を表示します。
• 変更しないファイルは表示しないでください。

「これらの変更を適用しますか？［yes / no］」と尋ねます。

ユーザーが no と答えた場合は、調整する内容を尋ね、ステップ 3 またはステップ 4 に戻ります。

ステップ 5：変更を適用する（古いプレビューの防止）

ファイルを書き込む前に、各対象ファイルを再読み込みし、その内容をステップ 2 で記録した内容と比較します。

対象ファイルのいずれかがステップ 2 から変更されている場合：

• ファイルを書き込まないでください。
• 次のように報告します：「ファイル {path} はプレビューの生成後に変更されています。現在の内容でプレビューを再生成します。」
• 同じ意図する変更リストを使ってステップ 2 に戻ります。

すべての対象ファイルが一致する場合：

• 各対象ファイルに変更を書き込みます。
• SKILL.md のフロントマターにある updated フィールドを今日の日付に更新します。（updated フィールドは、バージョンの変更が適用されたかどうかにかかわらず、ファイルが最後に変更された日付を記録します。）
• バイト 0 の保持： 書き換えた各ファイルで、ファイルのバイト 0 に --- があること（前に何もないこと）を確認します。以前の内容でバイト 0 の配置に違反していた場合（例：1 行目に HTML 帰属コメントがある場合）は、他の変更を適用する前にその旨を明示し、同じ書き込みの一部として配置を修正することを提案します。参照： library/skill-output-samples/SAMPLE_CREATION.md のセクション 5。
• 書き込んだ内容を報告します。各ファイルと、変更内容の概要を 1 行ずつ記載します。

ステップ 6：バージョン更新を提案する

変更の適用後、全体的な変更を分類し、バージョン更新の種類を提案します。バージョン番号を自動で書き換えてはいけません。

分類ルール（docs/internal/skill-versioning.md に基づく）：

変更の種類	更新クラス	例
表現を明確化、例を改善、誤字を修正	patch	チェックリスト項目の言い換え、より適切な例のシナリオ、説明の拡充
任意の機能またはセクションを追加	minor	任意の出力セクションの追加、より多くのシナリオへの対応、新しい品質チェック
必須の契約を変更、やり取りのパターンを破壊	major	コマンド名の変更、必須セクションの削除、「完了」の定義を狭める

判断に迷った場合： スキルの必須契約に準拠し続けるためにユーザーが新たな対応をする必要がある場合は、major に分類します。新しい動作が追加的または任意の場合は、minor に分類します。必須の動作に変更がなく、明確化のみの場合は、patch に分類します。

次の提案を提示します。

Suggested bump: {class} ({reason}).
Current version: {current}.
Bump to {suggested}? [yes / override / skip]

• yes：SKILL.md のフロントマターに新しいバージョンを書き込みます。
• override：希望するバージョンを尋ね、有効な SemVer で現在のバージョンより高いことを確認してから書き込みます。
• skip：バージョンを変更しません。ユーザーはリリース準備の際に更新できます。

Step 7: HISTORY.md の更新を提案する

バージョンを決定した後、変更の概要を作成し、現在の状態に応じて HISTORY.md を処理します。

HISTORY.md が存在し、バージョンを上げた場合：

1. HISTORY.md を読み、次の形式になっていることを検証します。
   • | Version | Date | Release | ... というヘッダーの概要テーブルがある
   • テーブル内のバージョンが新しい順に並んでいる
   • テーブル内の各バージョンに対応する ## X.Y.Z セクションが下にある
2. 形式が有効な場合：追記するかどうかを確認します。 「このバージョンを HISTORY.md に追加しますか？ [yes / no]」 yes の場合：概要テーブルに新しい行を（新しい順に）追加し、変更の概要を記載した 新しい ## X.Y.Z セクションを追加します。
3. 形式が無効な場合：警告を表示し、書き込みは行わず、追加案を提示します。 「HISTORY.md が想定される形式に従っていません。追加する内容は次のとおりです。 手動で貼り付けてください。」 その後、提案するテーブル行とバージョンセクションを表示します。

HISTORY.md が存在せず、スキルが 1.0.0 以降の場合： 変更でバージョンを上げるかどうかにかかわらず、ファイルがありません。 1.0.0 以降のすべてのスキルには、最初のバージョンから HISTORY.md が含まれます （docs/internal/skill-versioning.md の「作成するタイミング」を参照）。 作成するかどうかを確認します。 「このスキルには HISTORY.md がありません。作成しますか？ [yes / no]」 yes の場合：そのドキュメントの形式で HISTORY.md を作成し、スキルをリリースした バージョンのベースライン行（リリース履歴または作業概要から取得）を追加します。 今回の変更でバージョンを上げる場合は、新しいバージョンの行も追加します。

HISTORY.md が存在せず、スキルがまだ 0.x の場合：

• 今回の変更でバージョンを上げる場合（通常は 1.0.0 へ）：新しいバージョンの 最初の行を追加して HISTORY.md を作成するか確認します。その行には、契約が 安定した理由を記載します。0.x バージョンの行を後から追加してはいけません。
• 今回の変更でバージョンを上げない場合：提案しません。0.x のスキルは契約前の 状態であり、ファイルは最初のバージョン更新時に作成されます。

HISTORY.md が存在するが、バージョンを上げなかった場合（スキップ）： 提案しません。変更の概要は、ユーザーが必要に応じて利用できるよう会話内にあります。

Step 8: 概要を報告する

最終的な概要を提示します。

## Iteration Complete: {skill-name}

**Files changed:**
- skills/{name}/SKILL.md -- {summary}
- skills/{name}/references/EXAMPLE.md -- {summary}

**Version:** {current} -> {new} ({class}) | or: unchanged (skipped)
**HISTORY.md:** updated | created | skipped | not applicable

**Next steps:**
- Run `utility-pm-skill-validate {name}` to verify the changes pass
- Run local CI: `bash scripts/lint-skills-frontmatter.sh`
- If satisfied, commit the changes

機能縮退モード

スキルファイルを直接読み取れない場合（MCP 経由で実行している場合や、 ファイルシステムにアクセスできない埋め込み環境など）は、次のようにします。

1. このモードでは、検証レポートに基づく反復を優先します。 レポートにはコンテキスト（チェック ID、対象パス、アクション）が含まれています。
2. 自由記述による反復の場合、変更を提案する前に、関連する各ファイルの内容を ユーザーに貼り付けてもらいます。
3. 古いプレビューのガード（ステップ 5）は実行できません。概要に次のように記載します。 「古いプレビューのチェックなしで適用しました（ファイルシステムを利用できません）。」
4. HISTORY.md の操作では、現在のファイル内容を貼り付けるか、ファイルが存在しないことを 確認するようユーザーに求めます。

出力要件

イテレーター MUST:

• 編集前に、入力を構造化された変更予定リストに正規化する
• 提案する変更をすべて、ファイルごとにまとめた変更前／変更後のプレビューとして提示する
• ファイルを書き込む前に、ユーザーの明示的な確認を必須とする
• 古いプレビューを検出するため、書き込み前に対象ファイルを再読み込みする
• 適用のたびに updated フロントマターのフィールドを更新する
• バージョン番号を自動で書き込まず、バージョン更新の種類を提案する
• ステップ 7 のルールに従って HISTORY.md を処理する

イテレーター MUST NOT:

• プレビューを先に表示せずにファイルを書き込む
• ユーザーの確認なしにファイルを書き込む
• 明示的な確認なしにバージョン番号を自動で増やす
• 今回の変更でバージョンを上げない 0.x のスキルに HISTORY.md を作成する
• 形式を先に検証せずに HISTORY.md に追記する

品質チェックリスト

イテレーションを完了する前に、次の項目を確認してください。

• 編集前に、入力を変更予定の一覧に正規化した
• 提案した変更をすべて変更前／変更後のプレビューで示した
• ファイルを書き込む前にユーザーの確認を得た
• 書き込み前に古いプレビューのガードを実行した（または、利用できない旨を記録した）
• SKILL.md のフロントマターにある updated の日付を今日の日付に設定した
• 適切な根拠を添えて、バージョンの更新区分を提案した
• ユーザーから明示的な確認を得た後にのみ、バージョンを書き込んだ
• ステップ 7 のルールに従って HISTORY.md を適切に処理した
• 次のステップを含む最終的な概要を提示した

例

実際にリリースされたスキルを検証レポートに基づいて改善したイテレーションの完了例については、references/EXAMPLE.md を参照してください。