/utility-pm-skill-iterate

name: utility-pm-skill-iterate
description: Applies targeted improvements to an existing pm-skills skill based on feedback, validation reports, or convention changes. Reads current files, previews proposed changes, writes on confirmation, and suggests a version bump. Use when improving a skill after validation or feedback.
license: Apache-2.0
metadata:
  classification: utility
  version: "1.0.0"
  updated: 2026-04-03
  category: coordination
  frameworks: [triple-diamond]
  author: product-on-purpose

PM Skill Iterate

This skill improves an existing pm-skills skill by applying targeted changes based on input you provide. It reads the current skill files, proposes changes as before/after previews grouped by file, and writes them on your confirmation. After applying changes, it suggests a version bump class and offers to update HISTORY.md.

The iterator accepts any of these as input:

• A validation report from `utility-pm-skill-validate`
• Direct feedback ("the template is missing section X")
• A convention change ("all skills now need a Limitations section")
• A general improvement request ("make the example more realistic")

When to Use

• After running `utility-pm-skill-validate` and getting a report with findings
• When you have specific feedback on a skill and want to apply it
• When a repo convention changes and a skill needs to conform
• When a skill's example, template, or instructions need improvement
• When iterating on a skill before a release

When NOT to Use

• To create a new skill from scratch -> use `utility-pm-skill-builder`
• To audit a skill before making changes -> use `utility-pm-skill-validate` first
• To make bulk convention changes across many skills -> run `utility-pm-skill-validate --all` first to triage, then iterate one skill at a time

Instructions

When asked to iterate on a skill, follow these steps:

Step 1: Identify the Target Skill

Accept the skill name in any form:

• Directory name: `deliver-prd`
• Full path: `skills/deliver-prd/SKILL.md`
• Slash command: `deliver-prd`

Resolve to the canonical directory path: `skills/{name}/`.

If the skill directory does not exist, stop and report: "Skill directory `skills/{name}/` does not exist. Use `utility-pm-skill-builder` to create it."

Step 2: Read Current Skill Files

Read all files in the skill directory:

| File | Required | Purpose | |------|----------|---------| | `SKILL.md` | yes | Frontmatter + instructions (the primary edit target) | | `references/TEMPLATE.md` | yes | Output template | | `references/EXAMPLE.md` | yes | Worked example | | `HISTORY.md` | no | Version history (needed for Step 7) |

Record the exact content of each file at this point. You will compare against this content before writing in Step 5 (stale-preview guard).

If reading files is not possible (MCP/embedded environment), ask the user to paste the relevant file contents before proceeding (see Degraded Mode).

Step 3: Normalize Input into Intended Changes

Regardless of input type, extract a structured list of intended changes before generating any edits. This normalization step is what makes the unified flow work consistently across all input types.

**If the input is a validation report** (from `utility-pm-skill-validate`):

• Check for `Report schema: v1` in the header. If absent or a different

schema version, warn: "This report uses an unrecognized schema. I'll do my best but may miss structured fields."

• Parse the `## Recommendations` section.
• Split each recommendation line on `|` to extract:
• Position 1: severity (FAIL, WARN, INFO)
• Position 2: check ID
• After `Target:`: file path
• After `Action:` (next line): what to change
• Build the intended changes list from these fields.

**If the input is free text** (feedback, convention change, improvement request):

• Read the input and identify what needs to change.
• Map each change to a specific target file and section.
• If the input is vague, ask ONE clarifying question before proceeding.

Present the normalized list for user confirmation:

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}

If the user wants to modify the list (add, remove, or change items), adjust and re-present before proceeding.

Step 4: Preview Proposed Changes

For each intended change, generate the proposed edit and present it as a before/after block grouped by file:

### 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}

**Preview rules:**

• Group all changes by file. Show each file once, with all its changes.
• Show enough surrounding context for the user to understand the change.
• For small edits (a few lines), show the full section before and after.
• For large edits (rewriting most of a section), show the section header

and the first/last few lines of before, then the full after.

• Do NOT show files that are not being changed.

Ask: "Apply these changes? [yes / no]"

If the user says no, ask what to adjust and return to Step 3 or Step 4.

Step 5: Apply Changes (with Stale-Preview Guard)

**Before writing any file**, re-read each target file and compare its content to what you recorded in Step 2.

**If any target file has changed since Step 2:**

• Do NOT write any files.
• Report: "File `{path}` has changed since the preview was generated.

Regenerating preview with current content."

• Return to Step 2 with the same intended changes list.

**If all target files match:**

• Write the changes to each target file.
• Update the