Prompt
Create an operating checklist
Turn a recurring process into a clear checklist with ownership and exception handling.
ClaudeChatGPTGeminiOperations
Dave AI
pm-restructure
Execute structural recommendations from pm-reflect's reflection report — splits, merges, removals, and coverage gap fills — with explicit user approval for each change. Use after reviewing a pm-reflect report and deciding which recommendations to act on.
instructions.md
---
name: pm-restructure-ac3c43c8293b
description: |
Execute structural recommendations from pm-reflect's reflection report —
splits, merges, removals, and coverage gap fills — with explicit user
approval for each change. Use after reviewing a pm-reflect report and
deciding which recommendations to act on.
---
# pm-restructure
## Purpose
Close the gap between `pm-reflect` (analysis-only) and `pm-update` (content changes to existing units). This skill handles structural operations on PM units: splitting one unit into multiple, merging multiple into one, archiving obsolete units, and creating new units for uncovered areas. Each change requires explicit user approval.
## Preconditions
- PM has been initialized (`.agents/pm/pm-index.md` exists).
- A reflection report exists at `.agents/pm/reflection-report.md`, produced by `pm-reflect`.
## Required Reads
1. `.agents/pm/reflection-report.md` [required] -- the reflection report driving this session.
2. `.agents/pm/pm-index.md` [required] -- current unit registry.
3. `.agents/pm/pm-current-state.md` -- current project state summary.
4. The unit files named in the recommendations you will act on (read on demand, not all at once).
## Procedure
1. **Check for reflection report.** If `.agents/pm/reflection-report.md` does not exist, stop
with: "No reflection report found. Run `/pm-reflect` first to generate recommendations."
2. **Parse recommendations.** Read the reflection report and extract each recommendation as a
discrete action item. Classify each as one of:
- **split** -- divide a unit into two or more new units.
- **merge** -- combine two or more units into one.
- **archive** -- remove an obsolete unit (move to `.agents/pm/archive/`).
- **create** -- create a new unit for an uncovered work area.
Skip recommendations that describe content-level changes (e.g., "move this statement to a
workflow packet", "add negative knowledge about X"). Those are `pm-update` operations —
note them in the output as deferred to `pm-update`.
3. **Present recommendations.** Show the user a numbered summary of all structural
recommendations with their type and affected units. Example:
```
Structural recommendations from reflection report:
1. [split] template-engine -- covers 4 unrelated topics (layout, content, skills, adapters)
2. [merge] auth-core + auth-middleware -- both cover authentication
3. [archive] legacy-migration -- referenced by 0 recent workflows
4. [create] ci-pipeline -- no PM unit covers CI/CD
Content-level items deferred to pm-update: 2 items (see reflection report)
```
4. **Process each recommendation.** For each structural recommendation, in order:
a. **Present the proposed change.** Show what will happen:
- For **split**: which unit will be split, what the new units will be named, and how
sections will be distributed.
- For **merge**: which units will be combined, what the merged unit will be named, and
how conflicting content will be resolved.
- For **archive**: which unit will be moved to `.agents/pm/archive/` and why.
- For **create**: what the new unit will cover, its name, and which schema it will use
(infrastructure 8-section or code-navigation 10-section).
b. **Wait for user approval.** Use AskUserQuestion to ask the user whether to proceed.
Options: "Approve", "Skip", "Modify" (let the user adjust the proposed change).
If the user skips, move to the next recommendation.
c. **Execute the approved change.** Perform the structural operation:
**Split:**
- Read the source unit fully.
- Create the new unit files, distributing sections according to the approved plan.
Every section from the original must appear in exactly one of the new units.
- Verify no content was lost: every non-empty section in the original must have its
content present in one of the new units.
- Remove the original unit file.
- Update `pm-index.md`: remove the old row, add rows for each new unit, populating
**every** column including `Type` and `Always-Load` (see the column rules below).
- **Reconsider `Always-Load`.** If the unit being split carried `Always-Load: true`,
decide which of the new units inherits it — and it is at most one. A split is exactly
the moment an architecture overview gets carved out of a larger unit, and if nobody
decides, the flag is silently lost and every future session stops loading it.
**Merge:**
- Read all source units fully.
- Create the merged unit file. For each section, combine content from all sources.
If two units have conflicting statements in the same section, present the conflict
to the user and ask which to keep (or keep both with a note).
- Verify no content was lost: every non-empty section from every source must have its
content present in the merged unit.
- Remove the source unit files.
- Update `pm-index.md`: remove the old rows, add one row for the merged unit, populating
**every** column including `Type` and `Always-Load` (see the column rules below).
- **Reconsider `Always-Load`.** If any source unit carried `Always-Load: true`, the merged
unit almost certainly should. A merge is the mirror of the split case: an overview gets
absorbed, and the flag is dropped by default unless someone carries it across.
**Archive:**
- Create `.agents/pm/archive/` if it does not exist.
- Move the unit file to `.agents/pm/archive/`.
- Remove the unit's row from `pm-index.md`.
**Create:**
- Determine the appropriate schema:
- If the unit covers a software subsystem with source files: use the code-navigation
schema (10 sections: Responsibility, Key Source Files, Key Types and Classes,
Key Functions and Entry Points, Data Flow, Invariants, Dependencies, Negative
Knowledge, Open Questions, Last Verified).
- Otherwise: use the infrastructure schema (8 sections: Purpose, Current Truth,
Boundaries and Dependencies, Anchors/References, Negative Knowledge, Open
Questions, Related Workflows, Last Verified).
- Create the unit file with all required sections. Populate sections with known facts
from the reflection report and any context available. Mark unpopulated sections as
"None yet."
- Add a row to `pm-index.md`, populating **every** column including `Type` and
`Always-Load` (see the column rules below).
**Column rules for every `pm-index.md` row this skill writes.** The index is eight columns
wide — `Unit`, `Type`, `Purpose`, `Status`, `Facet`, `Always-Load`, `When To Load`,
`Dependencies`. Read the header; do not infer the shape from the row above, which is how the
two newest columns stopped being written after they were added.
- **`Type`**: `arch-overview`, `code-nav`, `infra` or `domain`. Read by `pm-load` and
`pm-validate`.
- **`Always-Load`**: `true` only for a unit that must be read in **every** session before
anything else — in practice the architecture overview, usually exactly one per project.
Default `false`. Every `true` is paid for on every session, so when unsure, `false`.
`Always-Load` is the flag this skill is most likely to be the only writer of. Splitting and
merging is precisely when an overview is carved out or absorbed, and no other skill revisits
the flag on an existing unit.
d. **Report the result.** After each operation, confirm what was done:
"Done: split `template-engine` into `template-layout` and `template-content`."
5. **Update cross-references.** After all approved operations are complete:
- Scan `pm-current-state.md` for references to renamed or removed units. Update them.
- Scan remaining unit files' Boundaries/Dependencies sections for references to changed
units. Update them.
- Update `pm-index.md` metadata (purpose, facet, load guidance) for any units that
absorbed content from other units.
6. **Append Last Verified.** For every unit file that was created or modified, append a
`Last Verified` entry dated today with a note like "Created by pm-restructure" or
"Merged from X + Y." The section is an append-only list; on a merged unit, carry the
source units' entries across rather than discarding their verification history.
7. **Produce summary.** Output a summary of all changes made:
```
PM Restructure Summary:
Executed:
- [split] template-engine → template-layout + template-content
- [archive] legacy-migration → .agents/pm/archive/
Skipped:
- [merge] auth-core + auth-middleware (user declined)
Deferred to pm-update:
- 2 content-level items (transient noise cleanup)
Cross-references updated: pm-current-state.md, auth-core.md
```
## Output
- Modified/created/archived files in `.agents/pm/units/` and `.agents/pm/archive/`.
- Updated `.agents/pm/pm-index.md`.
- Updated `.agents/pm/pm-current-state.md` (cross-references only).
- Summary delivered to the user in conversation.
## Completion Criteria
- Every structural recommendation from the reflection report has been presented to the user.
- Approved changes have been executed with no content loss.
- `pm-index.md` accurately reflects the current unit set on disk.
- Cross-references in `pm-current-state.md` and other unit files have been updated.
- A summary of all changes (executed, skipped, deferred) has been delivered.
## Error Handling
- If `.agents/pm/reflection-report.md` does not exist, stop: "No reflection report found. Run `/pm-reflect` first to generate recommendations."
- If the reflection report contains no structural recommendations (only content-level items), report: "No structural changes recommended. Use `/pm-update` for the content-level items in the report."
- If a split or merge would lose content (a non-empty section has no destination), stop the operation, show the orphaned content, and ask the user where it should go.
- If a unit file referenced in a recommendation does not exist on disk, skip that recommendation with a warning: "Unit `<name>` not found on disk — skipping."
- Do not modify units that are not part of an approved recommendation. Content corrections belong in `pm-update`.
---
name: pm-restructure-ac3c43c8293b
description: |
Execute structural recommendations from pm-reflect's reflection report —
splits, merges, removals, and coverage gap fills — with explicit user
approval for each change. Use after reviewing a pm-reflect report and
deciding which recommendations to act on.
---
# pm-restructure
## Purpose
Close the gap between `pm-reflect` (analysis-only) and `pm-update` (content changes to existing units). This skill handles structural operations on PM units: splitting one unit into multiple, merging multiple into one, archiving obsolete units, and creating new units for uncovered areas. Each change requires explicit user approval.
## Preconditions
- PM has been initialized (`.agents/pm/pm-index.md` exists).
- A reflection report exists at `.agents/pm/reflection-report.md`, produced by `pm-reflect`.
## Required Reads
1. `.agents/pm/reflection-report.md` [required] -- the reflection report driving this session.
2. `.agents/pm/pm-index.md` [required] -- current unit registry.
3. `.agents/pm/pm-current-state.md` -- current project state summary.
4. The unit files named in the recommendations you will act on (read on demand, not all at once).
## Procedure
1. **Check for reflection report.** If `.agents/pm/reflection-report.md` does not exist, stop
with: "No reflection report found. Run `/pm-reflect` first to generate recommendations."
2. **Parse recommendations.** Read the reflection report and extract each recommendation as a
discrete action item. Classify each as one of:
- **split** -- divide a unit into two or more new units.
- **merge** -- combine two or more units into one.
- **archive** -- remove an obsolete unit (move to `.agents/pm/archive/`).
- **create** -- create a new unit for an uncovered work area.
Skip recommendations that describe content-level changes (e.g., "move this statement to a
workflow packet", "add negative knowledge about X"). Those are `pm-update` operations —
note them in the output as deferred to `pm-update`.
3. **Present recommendations.** Show the user a numbered summary of all structural
recommendations with their type and affected units. Example:
```
Structural recommendations from reflection report:
1. [split] template-engine -- covers 4 unrelated topics (layout, content, skills, adapters)
2. [merge] auth-core + auth-middleware -- both cover authentication
3. [archive] legacy-migration -- referenced by 0 recent workflows
4. [create] ci-pipeline -- no PM unit covers CI/CD
Content-level items deferred to pm-update: 2 items (see reflection report)
```
4. **Process each recommendation.** For each structural recommendation, in order:
a. **Present the proposed change.** Show what will happen:
- For **split**: which unit will be split, what the new units will be named, and how
sections will be distributed.
- For **merge**: which units will be combined, what the merged unit will be named, and
how conflicting content will be resolved.
- For **archive**: which unit will be moved to `.agents/pm/archive/` and why.
- For **create**: what the new unit will cover, its name, and which schema it will use
(infrastructure 8-section or code-navigation 10-section).
b. **Wait for user approval.** Use AskUserQuestion to ask the user whether to proceed.
Options: "Approve", "Skip", "Modify" (let the user adjust the proposed change).
If the user skips, move to the next recommendation.
c. **Execute the approved change.** Perform the structural operation:
**Split:**
- Read the source unit fully.
- Create the new unit files, distributing sections according to the approved plan.
Every section from the original must appear in exactly one of the new units.
- Verify no content was lost: every non-empty section in the original must have its
content present in one of the new units.
- Remove the original unit file.
- Update `pm-index.md`: remove the old row, add rows for each new unit, populating
**every** column including `Type` and `Always-Load` (see the column rules below).
- **Reconsider `Always-Load`.** If the unit being split carried `Always-Load: true`,
decide which of the new units inherits it — and it is at most one. A split is exactly
the moment an architecture overview gets carved out of a larger unit, and if nobody
decides, the flag is silently lost and every future session stops loading it.
**Merge:**
- Read all source units fully.
- Create the merged unit file. For each section, combine content from all sources.
If two units have conflicting statements in the same section, present the conflict
to the user and ask which to keep (or keep both with a note).
- Verify no content was lost: every non-empty section from every source must have its
content present in the merged unit.
- Remove the source unit files.
- Update `pm-index.md`: remove the old rows, add one row for the merged unit, populating
**every** column including `Type` and `Always-Load` (see the column rules below).
- **Reconsider `Always-Load`.** If any source unit carried `Always-Load: true`, the merged
unit almost certainly should. A merge is the mirror of the split case: an overview gets
absorbed, and the flag is dropped by default unless someone carries it across.
**Archive:**
- Create `.agents/pm/archive/` if it does not exist.
- Move the unit file to `.agents/pm/archive/`.
- Remove the unit's row from `pm-index.md`.
**Create:**
- Determine the appropriate schema:
- If the unit covers a software subsystem with source files: use the code-navigation
schema (10 sections: Responsibility, Key Source Files, Key Types and Classes,
Key Functions and Entry Points, Data Flow, Invariants, Dependencies, Negative
Knowledge, Open Questions, Last Verified).
- Otherwise: use the infrastructure schema (8 sections: Purpose, Current Truth,
Boundaries and Dependencies, Anchors/References, Negative Knowledge, Open
Questions, Related Workflows, Last Verified).
- Create the unit file with all required sections. Populate sections with known facts
from the reflection report and any context available. Mark unpopulated sections as
"None yet."
- Add a row to `pm-index.md`, populating **every** column including `Type` and
`Always-Load` (see the column rules below).
**Column rules for every `pm-index.md` row this skill writes.** The index is eight columns
wide — `Unit`, `Type`, `Purpose`, `Status`, `Facet`, `Always-Load`, `When To Load`,
`Dependencies`. Read the header; do not infer the shape from the row above, which is how the
two newest columns stopped being written after they were added.
- **`Type`**: `arch-overview`, `code-nav`, `infra` or `domain`. Read by `pm-load` and
`pm-validate`.
- **`Always-Load`**: `true` only for a unit that must be read in **every** session before
anything else — in practice the architecture overview, usually exactly one per project.
Default `false`. Every `true` is paid for on every session, so when unsure, `false`.
`Always-Load` is the flag this skill is most likely to be the only writer of. Splitting and
merging is precisely when an overview is carved out or absorbed, and no other skill revisits
the flag on an existing unit.
d. **Report the result.** After each operation, confirm what was done:
"Done: split `template-engine` into `template-layout` and `template-content`."
5. **Update cross-references.** After all approved operations are complete:
- Scan `pm-current-state.md` for references to renamed or removed units. Update them.
- Scan remaining unit files' Boundaries/Dependencies sections for references to changed
units. Update them.
- Update `pm-index.md` metadata (purpose, facet, load guidance) for any units that
absorbed content from other units.
6. **Append Last Verified.** For every unit file that was created or modified, append a
`Last Verified` entry dated today with a note like "Created by pm-restructure" or
"Merged from X + Y." The section is an append-only list; on a merged unit, carry the
source units' entries across rather than discarding their verification history.
7. **Produce summary.** Output a summary of all changes made:
```
PM Restructure Summary:
Executed:
- [split] template-engine → template-layout + template-content
- [archive] legacy-migration → .agents/pm/archive/
Skipped:
- [merge] auth-core + auth-middleware (user declined)
Deferred to pm-update:
- 2 content-level items (transient noise cleanup)
Cross-references updated: pm-current-state.md, auth-core.md
```
## Output
- Modified/created/archived files in `.agents/pm/units/` and `.agents/pm/archive/`.
- Updated `.agents/pm/pm-index.md`.
- Updated `.agents/pm/pm-current-state.md` (cross-references only).
- Summary delivered to the user in conversation.
## Completion Criteria
- Every structural recommendation from the reflection report has been presented to the user.
- Approved changes have been executed with no content loss.
- `pm-index.md` accurately reflects the current unit set on disk.
- Cross-references in `pm-current-state.md` and other unit files have been updated.
- A summary of all changes (executed, skipped, deferred) has been delivered.
## Error Handling
- If `.agents/pm/reflection-report.md` does not exist, stop: "No reflection report found. Run `/pm-reflect` first to generate recommendations."
- If the reflection report contains no structural recommendations (only content-level items), report: "No structural changes recommended. Use `/pm-update` for the content-level items in the report."
- If a split or merge would lose content (a non-empty section has no destination), stop the operation, show the orphaned content, and ask the user where it should go.
- If a unit file referenced in a recommendation does not exist on disk, skip that recommendation with a warning: "Unit `<name>` not found on disk — skipping."
- Do not modify units that are not part of an approved recommendation. Content corrections belong in `pm-update`.
Platform guidance
Imported from the listed AgentSkill.sh category. Complete supplied package files and notices are retained. Required external tools and credentials are not installed. No bundled code was executed during import. Individual agent task behavior has not been tested.