Utility Pm Skill Iterate

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 2abfbb961d31 · 19 Oct 2026Report an issue or request a re-scan

• Publisherproduct-on-purpose GitHub organizationOwner of the repository this skill is read from
• Source folderproduct-on-purpose/pm-skills/skills/utility-pm-skill-iterateThe exact folder we audited
• LicenceApache-2.0As the repository states it
• Commit pinned for this verdict2abfbb961d31A new audit runs when the source changes
• Repository statusNot archivedLast push 1 day ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its 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…

---
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.1.0"
  updated: 2026-10-16
  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

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/product-on-purpose/pm-skills
git -C pm-skills checkout 2abfbb961d31

Works in

1. 2026-10-19
   ✓SAFE B 89 / 100

   first audit · source 2abfbb961d31

Questions about Utility Pm Skill Iterate

• github.com/product-on-purpose/pm-skills/tree/main/skills/utility — the audited source at commit 2abfbb961d31 and every finding aboveObserved · 19 Oct 2026

Spotted something wrong? Report a correction · Methodology