PM Skill Iterate

Try it: /pm-skills:utility-pm-skill-iterate "Your context here"

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

How to Use

Invoke the skill by name (/pm-skills:utility-pm-skill-iterate on Claude Code, $utility-pm-skill-iterate on Codex):

/pm-skills:utility-pm-skill-iterate "Your context here"

Or reference the skill file directly: skills/utility-pm-skill-iterate/SKILL.md

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 updated field in SKILL.md frontmatter to today’s date. (The updated field tracks when the file was last modified, regardless of whether a version bump is accepted.)
Byte-0 preservation: verify each rewritten file still has --- at byte 0 of the file (no preceding content). If the previous content violated byte-0 placement (e.g., HTML attribution comment on line 1), surface this defensively before applying other changes and offer to fix the placement as part of the same write. Reference: library/skill-output-samples/SAMPLE_CREATION.md Section 5.
Report what was written: list each file and a one-line summary of what changed.

Step 6: Suggest Version Bump

After changes are applied, classify the overall change and suggest a version bump class. Do NOT auto-write the version number.

Classification rules (from docs/internal/skill-versioning.md):

Change type	Bump class	Examples
Wording clarified, examples improved, typos fixed	patch	Reworded checklist item, better example scenario, description expanded
New optional capability or section added	minor	New optional output section, handles more scenarios, new quality check
Required contract changed, interaction pattern breaks	major	Command renamed, required section removed, “done” definition narrowed

Tie-breaker: If a user must do something new to stay compliant with the skill’s required contract, classify as major. If the new behavior is additive or optional, classify as minor. If the required behavior is unchanged and only clarified, classify as patch.

Present the suggestion:

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

yes: Write the new version to SKILL.md frontmatter.
override: Ask for the desired version, validate it’s valid SemVer and higher than current, then write it.
skip: Leave the version unchanged. The user may bump it later during release prep.

Step 7: Offer HISTORY.md Update

After the version decision, produce a change summary and handle HISTORY.md based on the current state:

If HISTORY.md exists and version was bumped:

Read HISTORY.md and validate its format:
- Has a summary table with | Version | Date | Release | ... header
- Versions are newest-first in the table
- Each table version has a corresponding ## X.Y.Z section below
If format is valid: offer to append. “Would you like me to add this version to HISTORY.md? [yes / no]” On yes: add a new row to the summary table (newest-first) and a new ## X.Y.Z section with the change summary.
If format is invalid: warn and show the proposed content without writing. “HISTORY.md doesn’t follow the expected format. Here’s what I would add — you can paste it manually:” Then show the proposed table row and version section.

If HISTORY.md does not exist and this is the skill’s second version: Offer to create it. “This is the second version of this skill. Would you like me to create HISTORY.md with entries for both versions? [yes / no]” On yes: create HISTORY.md with the format from docs/internal/skill-versioning.md, including entries for both the original version (from release history or effort brief) and the new version.

If HISTORY.md does not exist and version was not bumped: No offer. HISTORY.md is premature until the skill has shipped a second version.

If HISTORY.md exists but version was not bumped (skip): No offer. The change summary is available in the conversation for the user to use at their discretion.

Step 8: Report Summary

Present a final summary:

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

Degraded Mode

If you cannot read skill files directly (e.g., running via MCP or in an embedded environment without file system access):

Validation-report-driven iteration is preferred in this mode. The report carries the context (check IDs, target paths, actions).
For free-text iteration, ask the user to paste the content of each relevant file before proposing changes.
The stale-preview guard (Step 5) cannot run — note in the summary: “Applied without stale-preview check (file system not available).”
HISTORY.md operations require the user to paste the current file content or confirm it does not exist.

Output Contract

The iterator MUST:

Normalize input into a structured intended-changes list before editing
Present all proposed changes as before/after previews grouped by file
Require explicit user confirmation before writing any file
Re-read target files before writing to guard against stale previews
Update the updated frontmatter field on every apply
Suggest a version bump class without auto-writing the version number
Handle HISTORY.md according to the rules in Step 7

The iterator MUST NOT:

Write files without showing a preview first
Write files without user confirmation
Auto-increment the version number without explicit confirmation
Create HISTORY.md for a skill still on its first version
Append to HISTORY.md without validating its format first

Examples

See references/EXAMPLE.md for a completed iteration demonstrating a validation-report-driven improvement to a real shipped skill.

Output Template

Iteration Change Summary: {skill-name}

Intended Changes

{Normalized list of changes extracted from input.}

Target: {file-path} -> {section} Change: {what will change} Source: {validation report check ID | user feedback | convention change}

Proposed Changes

{Before/after previews grouped by file.}

{file-path}

{Section name} — before:

{current content}

{Section name} — after:

{proposed content}

Applied Changes

{Summary of what was actually written after user confirmation.}

File	Change
{file-path}	{one-line summary}

Version

Current: {version} Suggested bump: {class} ({reason}) New version: {new-version | unchanged}

HISTORY.md

{One of: updated | created | skipped | not applicable}

{If updated or created, show the content that was written.}

Example Output

Iteration Example: deliver-prd

This example shows a validation-report-driven iteration of deliver-prd. The input is the WARN finding from the F-10 validation report example (output-contract-coverage).

Step 1: Identify the Target Skill

Target: skills/deliver-prd/ Resolved from user input: utility-pm-skill-iterate deliver-prd

Step 2: Read Current Skill Files

Read and recorded:

skills/deliver-prd/SKILL.md (72 lines)
skills/deliver-prd/references/TEMPLATE.md (10 sections)
skills/deliver-prd/references/EXAMPLE.md (212 lines)
HISTORY.md does not exist

Step 3: Normalize Input into Intended Changes

Input: validation report from utility-pm-skill-validate deliver-prd

Parsed ## Recommendations section (Report schema: v1):

Intended changes:
1. Target: skills/deliver-prd/SKILL.md -> Output Format section
   Change: Enumerate template sections explicitly instead of generic reference
   Source: validation report, check output-contract-coverage

The INFO finding (when-not-to-use) was excluded from the intended changes list because the user did not request it. INFO findings are optional and only included if the user explicitly asks for them.

“Proceed with this change? [yes / no]”

User: yes

Step 4: Preview Proposed Changes

skills/deliver-prd/SKILL.md

Output Format section — before:

Output Format
Section titled “Output Format”

Use the template in references/TEMPLATE.md to structure the output.

Output Format section — after:

Output Format
Section titled “Output Format”

Use the template in references/TEMPLATE.md to structure the output. The output MUST include these sections:

Overview

Goals & Success Metrics

User Stories

Scope

Solution Design

Technical Considerations

Dependencies & Risks

Timeline & Milestones

Open Questions

Appendix

No changes to references/TEMPLATE.md or references/EXAMPLE.md.

“Apply these changes? [yes / no]”

User: yes

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

Re-read skills/deliver-prd/SKILL.md — content matches Step 2 recording. No stale-preview conflict.

Changes applied:

skills/deliver-prd/SKILL.md — expanded Output Format section with explicit template section enumeration
updated field changed from 2026-01-26 to 2026-04-03

Step 6: Suggest Version Bump

The change clarifies the output contract by making implicit requirements explicit. Users who previously followed the template were already producing compliant output — nothing new is required. This is a patch change.

Suggested bump: patch (output contract clarification -- makes template
section requirements explicit without adding new requirements).
Current version: 2.0.0.
Bump to 2.0.1? [yes / override / skip]

User: yes

Version updated: 2.0.0 -> 2.0.1 in SKILL.md frontmatter.

Step 7: Offer HISTORY.md Update

HISTORY.md does not exist. This is the skill’s second version (2.0.0 -> 2.0.1).

“This is the second version of this skill. Would you like me to create HISTORY.md with entries for both versions? [yes / no]”

User: yes

Created skills/deliver-prd/HISTORY.md:

# deliver-prd -- Version History

| Version | Date | Release | Effort | Type | Summary |
|---------|------|---------|--------|------|---------|
| 2.0.1 | 2026-04-03 | TBD | -- | changed | Output contract clarification |
| 2.0.0 | 2026-01-26 | v2.0.0 | -- | added | v2.0 restructure |

## 2.0.1 (2026-04-03)

Release: TBD.

Expanded the Output Format section to explicitly enumerate all 10 template
sections instead of a generic "use the template" reference. No new
requirements -- existing compliant output remains valid.

### Changes
- Output Format section now lists all 10 TEMPLATE.md sections by name
- Clarifies which sections are required in the output

## 2.0.0 (2026-01-26)

Released in v2.0.0.

Restructured as part of the v2.0 flat-extensions migration. Established
the current skill structure with frontmatter, instructions, output contract,
and quality checklist.

### Contract established
- Command: deliver-prd
- Phase: deliver
- Output: Product Requirements Document following TEMPLATE.md structure

Step 8: Report Summary

## Iteration Complete: deliver-prd

**Files changed:**
- skills/deliver-prd/SKILL.md -- expanded Output Format with explicit section list
- skills/deliver-prd/HISTORY.md -- created (first iteration, two-version history)

**Version:** 2.0.0 -> 2.0.1 (patch)
**HISTORY.md:** created

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

Example Notes

This example demonstrates:

Validation-report-driven iteration: the input is a structured report from utility-pm-skill-validate, parsed by ## Recommendations and pipe-delimited fields
INFO findings excluded by default: the when-not-to-use INFO was not included in the intended changes because the user did not request it
Before/after preview: the Output Format section shown in full before and after, grouped under the target file heading
Stale-preview guard: Step 5 explicitly re-reads the target file and confirms it matches the Step 2 recording before writing
Patch classification: making implicit requirements explicit is a clarification, not a new requirement — users who followed the template were already producing compliant output
HISTORY.md creation at second-version trigger: the skill moved from 2.0.0 to 2.0.1, triggering the governance rule to create HISTORY.md with entries for both versions
The iteration did NOT modify TEMPLATE.md or EXAMPLE.md: the change was confined to SKILL.md’s Output Format section

Real-World Examples

See this skill applied to three different product contexts:

Storevine (B2B): Storevine B2B ecommerce platform . iterating on campaign-analytics skill after validation findings

Prompt:

utility-pm-skill-iterate

Skill: campaign-analytics
Path: skills/measure-campaign-analytics/

Apply fixes from validation report:
1. Q-01: Expand EXAMPLE.md Attribution Model section to reach 150+ lines
2. Q-04: Add "When NOT to Use" section to SKILL.md

Output:

Iteration Change Summary: campaign-analytics

Quality Checklist

Before completing the iteration, verify:

Input was normalized into an intended-changes list before editing
All proposed changes were shown as before/after previews
User confirmed before any files were written
Stale-preview guard ran before writing (or noted as unavailable)
updated date was set to today in SKILL.md frontmatter
Version bump class was suggested with correct reasoning
Version was only written after explicit user confirmation
HISTORY.md was handled correctly per Step 7 rules
Final summary was presented with next steps