ma-agents 3.4.8 → 3.5.0

package/lib/bmad-extension/skills/prioritize-backlog/SKILL.md

@@ -1,194 +1,216 @@
 ---
 name: prioritize-backlog
-description: Reprioritize backlog items using multiple criteria — severity, business value, dependencies, type, age
+description: Reprioritize backlog items in sprint-status.yaml using multiple criteria -- severity, business value, dependencies, type, age
 type: skill
 triggers:
   - "prioritize backlog"
-  - "reorder backlog"
-  - "reprioritize"
+  - "reprioritize backlog"
+  - "sort backlog"
 ---
 
-# Prioritize-Backlog Workflow
+# Prioritize Backlog
 
-Reprioritize backlog items using multiple criteria — severity, business value, dependencies, type, and age.
+Reprioritize backlog items in `sprint-status.yaml` using multiple criteria: severity, business value, dependencies, type, and age.
 
 <workflow>
 
-<step n="1" goal="Load backlog and dependency data">
-  <action>Read `_bmad-output/implementation-artifacts/backlog.yaml`</action>
-  <check if="file missing or empty (no items)">
-    <output>No backlog found or backlog is empty. Nothing to prioritize.</output>
-    <action>Exit workflow</action>
+<step n="0" goal="Load configuration and validate file existence">
+  <action>Determine the path to `sprint-status.yaml`:
+  1. Check `_bmad/bmm/config.yaml` for an `artifacts_path` or `sprint_status_path` override.
+  2. If not set, default to `_bmad-output/implementation-artifacts/sprint-status.yaml`.
+  </action>
+  <action>Read the resolved `sprint-status.yaml` path.</action>
+  <check if="sprint-status.yaml does not exist">
+    <output>No sprint-status.yaml found. Run sprint planning first to initialize the file.</output>
+    <action>Exit workflow — do not create any file.</action>
+  </check>
+  <action>Parse the full file: read `epics`, `backlog`, and `sprints` sections plus all metadata fields (`generated`, `last_updated`, `project`, `project_key`, `tracking_system`, `story_location`). Store the entire parsed structure as {{file_data}} for later atomic write.</action>
+  <check if="legacy backlog.yaml exists in the same directory as sprint-status.yaml">
+    <output>Note: Legacy backlog.yaml detected. Run migration to consolidate.</output>
+    <action>Continue — do NOT read from or write to the legacy file. Operate on sprint-status.yaml only.</action>
+  </check>
+  <check if="{{file_data.backlog}} is empty or null">
+    <output>Backlog is empty. Nothing to prioritize.</output>
+    <action>Exit workflow — do not modify the file.</action>
   </check>
-  <action>Store all backlog items as {{backlog_items}}</action>
-  <action>Infer implicit dependencies: stories belonging to the same epic are assumed to be sequential (lower story number before higher)</action>
-  <action>Read `_bmad-output/implementation-artifacts/epics.md` (or equivalent epics source) for any explicitly declared dependencies</action>
-  <action>Build {{dependency_map}} — for each item, list the IDs it depends on (must be completed before it can start)</action>
+  <action>Store {{backlog_items}} = {{file_data.backlog}} (the array of items to work with).</action>
+  <action>Store {{original_order}} = copy of {{backlog_items}} with their current priority values, for use in the change summary later.</action>
 </step>
 
-<step n="2" goal="Display current backlog ordering">
+<step n="1" goal="Display current backlog order">
+  <action>Read {{backlog_items}} in their current array order (position 0 = highest priority).</action>
   <output>
-## Current Backlog
+## Current Backlog ({{backlog_items.length}} items)
 
-| # | Priority | ID | Title | Type | Epic | Status | Sprint | Severity | Dependencies |
-|---|---|---|---|---|---|---|---|---|---|
+| Priority | ID | Title | Type | Epic | Severity | Status |
+|---|---|---|---|---|---|---|
 {{#each backlog_items}}
-| {{@index+1}} | {{priority}} | {{id}} | {{title}} | {{type}} | {{epic}} | {{status}} | {{sprint}} | {{severity}} | {{dependencies}} |
+| {{priority}} | {{id}} | {{title}} | {{type}} | {{#if epic}}epic-{{epic}}{{else}}—{{/if}} | {{severity or "—"}} | {{status}} |
 {{/each}}
 
-*Total: {{backlog_items.length}} items*
+*Note: Items assigned to sprints are not shown — only unassigned backlog items are listed here.*
   </output>
 </step>
 
-<step n="3" goal="Choose prioritization mode">
-  <ask>Choose prioritization mode:
-1. **Full reprioritization** — enter items in desired order, remaining appended at end
-2. **Quick adjust** — move individual items up/down
-3. **Auto-suggest** — AI analysis with weighted criteria
-4. **Cancel**
+<step n="2" goal="Choose prioritization mode">
+  <ask>Select a prioritization mode:
+
+**[f] Full** — Interactive: generates a suggested order, presents current vs proposed side-by-side. You review and approve (or adjust) before any write occurs.
+**[q] Quick** — Automated: applies default multi-criteria rules immediately, then shows a summary of what moved.
+**[a] Auto-suggest** — Read-only: shows the suggested order with per-item rationale. No file is modified.
+**[x] Cancel** — Exit without changes.
 
 Choice:</ask>
-  <check if="choice == 4">
-    <output>Cancelled. No changes made.</output>
-    <action>Exit workflow</action>
+  <check if="user selects 'x'">
+    <output>Cancelled — no changes made.</output>
+    <action>Exit workflow.</action>
   </check>
+  <action>Store {{selected_mode}} = user choice.</action>
 </step>
 
-<step n="3a" goal="Full reprioritization" if="choice == 1">
-  <ask>Enter item numbers in your desired priority order (comma-separated). Items not listed will be appended in their current relative order:</ask>
-  <action>Resolve entered numbers against the backlog table from step 2</action>
-  <action>Build {{new_order}}: user-specified items first (in given order), then remaining items appended in their original relative order</action>
-  <goto step="4" />
-</step>
+<step n="3" goal="Multi-criteria prioritization analysis">
+  <action>For each item in {{backlog_items}}, compute a composite priority score using the following weighted criteria (highest weight listed first):</action>
 
-<step n="3b" goal="Quick adjust" if="choice == 2">
-  <action>Initialize {{new_order}} as a copy of the current {{backlog_items}} list (preserving current ordering)</action>
-  <ask>Select item number to move:</ask>
-  <action>Store selected item as {{item_to_move}}</action>
-  <ask>Move to:
-- Enter a position number (1 = top, N = bottom)
-- Or enter 'u' to move up one position, 'd' to move down one position
-
-Target:</ask>
-  <action>Move {{item_to_move}} to the specified position in {{new_order}}</action>
-  <output>Moved "{{item_to_move.title}}" to position {{new_position}}.</output>
-  <ask>Continue? [m] Move another item / [d] Done adjusting:</ask>
-  <check if="user selects 'm'">
-    <action>Display current ordering</action>
-    <goto step="3b" />
-  </check>
-  <check if="user selects 'd'">
-    <goto step="4" />
-  </check>
-</step>
+  <action>**1. Severity weight (highest impact):**
+  - `severity: critical` → +40 points
+  - `severity: high`     → +30 points
+  - `severity: medium`   → +10 points
+  - `severity: low`      → +5 points
+  - `severity: null`     → +0 points (no adjustment for stories)
+  </action>
+
+  <action>**2. Business value weight:**
+  - Use the item's existing `priority` value as a signal for current business value ranking. Items with lower `priority` values (higher priority) receive a proportional boost: score += max(0, ({{backlog_items.length}} - current_priority + 1) * 2). This preserves existing prioritization signals while allowing other criteria to override.
+  - Items from lower-numbered epics (or `epic: null`) receive a slight additional boost: score += max(0, (20 - epic_number)) * 1, treating null as epic 0.
+  </action>
 
-<step n="3c" goal="Auto-suggest prioritization" if="choice == 3">
-  <action>Analyze all backlog items using weighted criteria:
-    1. **Blocking dependencies** (highest weight) — items that block other items should come first
-    2. **Severity** (bugs only) — critical > high > medium > low
-    3. **Business value** — infer from epic priority, item description, and type
-    4. **Type priority** — bugs generally before stories of equal value
-    5. **Age** — older items (lower story numbers, earlier creation) get slight priority boost
+  <action>**3. Dependency weight:**
+  - Read `_bmad-output/planning-artifacts/epics.md` if it exists to identify explicit inter-story dependencies.
+  - Within the same epic, items with lower story numbers are assumed to be prerequisites for higher-numbered stories. Items that block others get a +15 point boost.
+  - Items that are explicitly blocked by other UNASSIGNED backlog items get a -10 point adjustment (they cannot proceed anyway).
+  - If epics.md cannot be read or does not define explicit dependencies, use only the intra-epic ordering heuristic.
   </action>
-  <action>Generate {{suggested_order}} with rationale for each item's position</action>
+
+  <action>**4. Type weight (tiebreaker):**
+  - `type: bug` → +3 points (bugs receive a slight boost over stories at equal composite score)
+  - `type: story` → +0 points
+  </action>
+
+  <action>**5. Age weight (starvation prevention — weakest signal):**
+  - Items from epics with lower epic numbers receive +1 point per 5 epic numbers below the maximum epic in the backlog (e.g., if max epic is 17, epic-12 gets +1, epic-7 gets +2).
+  - Items with `epic: null` are treated as oldest (receive the maximum age boost among all items).
+  - This is a tiebreaker only — it prevents starvation but does not override higher-priority signals.
+  </action>
+
+  <action>Compute {{composite_score}} for each item = severity_score + business_value_score + dependency_score + type_score + age_score.</action>
+  <action>Sort items by {{composite_score}} descending (highest score = priority 1). Break ties by current `priority` value (lower = higher priority stays higher).</action>
+  <action>Store {{suggested_order}} = sorted list of items. Store {{rationale_map}} = per-item map of score breakdown and reason summary.</action>
+</step>
+
+<step n="3a" goal="Full mode: present comparison and get approval" condition="{{selected_mode}} == 'f'">
   <output>
-## Auto-Suggested Priority Order
+## Prioritization Analysis: Current vs Suggested
 
-| New # | ID | Title | Type | Rationale |
+| Current Priority | ID | Suggested Priority | Change | Key Rationale |
 |---|---|---|---|---|
-{{#each suggested_order}}
-| {{@index+1}} | {{id}} | {{title}} | {{type}} | {{rationale}} |
+{{#each original_order}}
+| {{priority}} | {{id}} | {{suggested_position}} | {{change_indicator}} | {{rationale}} |
 {{/each}}
+
+*Items highlighted with ↑ move up, ↓ move down, = stay in place.*
   </output>
   <ask>Options:
-- [a] Accept this ordering
-- [m] Modify (switch to full reprioritization with this as starting point)
-- [r] Reject (return to mode selection)
+- **[a]** Accept the suggested order as-is
+- **[m]** Manually adjust — enter item IDs in your preferred order (comma-separated)
+- **[c]** Cancel — exit without changes
 
 Choice:</ask>
+  <check if="user selects 'c'">
+    <output>Cancelled — no changes made.</output>
+    <action>Exit workflow.</action>
+  </check>
   <check if="user selects 'a'">
-    <action>Set {{new_order}} = {{suggested_order}}</action>
-    <goto step="4" />
+    <action>Set {{final_order}} = {{suggested_order}}.</action>
   </check>
   <check if="user selects 'm'">
-    <action>Set current backlog display to {{suggested_order}}</action>
-    <goto step="3a" />
-  </check>
-  <check if="user selects 'r'">
-    <goto step="3" />
+    <ask>Enter item IDs in your preferred priority order (highest priority first), comma-separated. You MUST include all {{backlog_items.length}} items — no duplicates or omissions allowed:
+Example: 17-10-rework-generate-backlog, 17-11-rework-add-to-sprint, ...</ask>
+    <action>Parse the user-provided list into {{manual_order_ids}}.</action>
+    <action>Validate:
+    - Count must equal {{backlog_items.length}} (no missing items)
+    - All IDs must exist in {{backlog_items}} (no unknown IDs)
+    - No duplicate IDs
+    </action>
+    <check if="validation fails">
+      <output>Invalid input: {{validation_error}}. Please re-enter the complete list of all {{backlog_items.length}} item IDs in your preferred order.</output>
+      <action>Repeat the manual-entry prompt until valid input is received or user cancels.</action>
+    </check>
+    <action>Reorder {{backlog_items}} to match {{manual_order_ids}} sequence. Set {{final_order}} = reordered list.</action>
   </check>
+  <action>Proceed to Step 4 with {{final_order}}.</action>
 </step>
 
-<step n="4" goal="Dependency validation">
-  <action>For each item in {{new_order}}, check if it appears before any item it depends on</action>
-  <check if="dependency violations found">
-    <output>
-**Dependency Warning:** The following items appear before their dependencies:
-
-{{#each violations}}
-- **{{item.id}}** (position {{item.position}}) depends on **{{dependency.id}}** (position {{dependency.position}})
-{{/each}}
-    </output>
-    <ask>How to proceed?
-- [o] Override — keep current order despite dependency warnings
-- [f] Fix — automatically reorder to satisfy dependencies
-- [c] Cancel — return to mode selection
-
-Choice:</ask>
-    <check if="user selects 'f'">
-      <action>Reorder {{new_order}} to satisfy dependency constraints (move dependency items before their dependents, preserving relative order otherwise)</action>
-      <output>Dependencies fixed. Updated ordering applied.</output>
-    </check>
-    <check if="user selects 'c'">
-      <goto step="3" />
-    </check>
-    <!-- if 'o', proceed with current order -->
-  </check>
+<step n="3b" goal="Quick mode: apply suggested order automatically" condition="{{selected_mode}} == 'q'">
+  <action>Set {{final_order}} = {{suggested_order}}.</action>
+  <action>Proceed to Step 4 with {{final_order}}.</action>
 </step>
 
-<step n="5" goal="Confirm and persist new ordering">
+<step n="3c" goal="Auto-suggest mode: display suggestions without writing" condition="{{selected_mode}} == 'a'">
   <output>
-## Old vs New Priority Order
+## Suggested Backlog Order (Read-Only — No Changes Written)
 
-| Position | Old | New |
-|---|---|---|
-{{#each comparison}}
-| {{position}} | {{old_id}} — {{old_title}} | {{new_id}} — {{new_title}} |
+| New Priority | ID | Title | Old Priority | Change | Rationale |
+|---|---|---|---|---|---|
+{{#each suggested_order}}
+| {{new_priority}} | {{id}} | {{title}} | {{old_priority}} | {{change_indicator}} | {{rationale}} |
 {{/each}}
+
+**Summary:**
+- Items that would move up: {{move_up_count}}
+- Items that would move down: {{move_down_count}}
+- Items unchanged: {{unchanged_count}}
+
+Suggestions displayed. No changes written. Run again in Full or Quick mode to apply.
   </output>
-  <ask>Provide a brief reason for this reprioritization:</ask>
-  <action>Store as {{reason}}</action>
-  <ask>Confirm? [y] Apply / [n] Cancel / [e] Edit order:</ask>
-  <check if="user selects 'n'">
-    <output>Cancelled. No changes made.</output>
-    <action>Exit workflow</action>
-  </check>
-  <check if="user selects 'e'">
-    <goto step="3" />
-  </check>
-  <check if="user input is not 'y', 'n', or 'e'">
-    <output>Unrecognized option: "{{user_input}}". Please enter [y], [n], or [e].</output>
-    <goto step="5" />
-  </check>
+  <action>Exit workflow — do NOT proceed to Step 4.</action>
+</step>
 
-  <action>Update `_bmad-output/implementation-artifacts/backlog.yaml`:
-    - Rewrite items in {{new_order}} sequence
-    - Set priority fields sequentially: 1, 2, 3, ..., N
-    - Add or update header comment: `# Reprioritized: {{current_date}} — {{reason}}`
-    - Preserve all other item fields unchanged
-  </action>
+<step n="4" goal="Apply reordering and persist">
+  <action>Take {{final_order}} (from Full or Quick mode).</action>
+  <action>Renumber `priority` field on each item sequentially: position 0 in the array gets `priority: 1`, position 1 gets `priority: 2`, and so on through position N-1 gets `priority: N`. This keeps the denormalized index in sync with array position (schema section 3.3).</action>
+  <action>Get the current ISO-8601 timestamp (format: YYYY-MM-DDTHH:MM:SS). Update {{file_data.last_updated}} to this timestamp.</action>
+  <action>Preserve {{file_data.generated}} unchanged.</action>
+  <action>Preserve {{file_data.epics}} section unchanged — do NOT modify any epic entries.</action>
+  <action>Preserve {{file_data.sprints}} section unchanged — do NOT modify any sprint entries or items within sprints.</action>
+  <action>Set {{file_data.backlog}} = {{final_order}} (the reordered array with renumbered priorities).</action>
+  <action>Write the complete updated {{file_data}} back to the resolved sprint-status.yaml path in a single atomic write (read-modify-write pattern). This single write replaces the file entirely — no partial updates.</action>
+</step>
+
+<step n="5" goal="Display summary output">
+  <action>Compute change summary by comparing {{original_order}} (old positions) against {{final_order}} (new positions).</action>
   <output>
 ## Reprioritization Complete
 
-**Items reordered:** {{new_order.length}}
-**Reason:** {{reason}}
-**Date:** {{current_date}}
+**Mode:** {{mode_label}} ({{current_datetime}})
+**Items reordered:** {{backlog_items.length}} total
+
+### Changes Made
+
+| ID | Title | Old Priority | New Priority | Direction |
+|---|---|---|---|---|
+{{#each changed_items}}
+| {{id}} | {{title}} | {{old_priority}} | {{new_priority}} | {{direction}} |
+{{/each}}
+
+{{#if unchanged_items.length > 0}}
+**Unchanged ({{unchanged_items.length}} items):** {{unchanged_ids_list}}
+{{/if}}
 
-Updated priorities written to `_bmad-output/implementation-artifacts/backlog.yaml`.
+**sprint-status.yaml updated successfully.**
 
-**Next Steps:**
-- Use `/sprint-status-view` to review sprint assignments
-- Use `/add-to-sprint` to assign top-priority items to a sprint
+**Next steps:**
+- `/add-to-sprint` — Assign the top-priority backlog items to the current sprint
+- `/sprint-status-view` — View overall sprint progress and capacity
   </output>
 </step>