promote-roadmap-items

Skill: Promote Roadmap Items

Purpose

Promote scored backlog items into the Now / Next / Later slots of the roadmap according to strategic goal capacity allocation. It is a supporting skill of roadmap planning ceremony , event-driven.

Core Objective

Primary objective: Based on the current strategic goal capacity allocation and backlog priority, decide which items to promote / demote / keep, and update roadmap.md.

Success criteria(all must be satisfied):

✅ Read backlog items with priority already set (skip unset)
✅ Calculate the capacity usage and remaining capacity of each roadmap layer (Now/Next/Later)
✅ Present promotion candidates according to strategic_goal capacity allocation (from roadmap.md or strategic settings)
✅ User confirms each promotion / demotion decision
✅ Update roadmap.md and the status field of promoted items
✅ Output a capacity usage report (used per goal / total / remaining)

Acceptance test: After promotion, can readers directly see from roadmap.md which strategic_goal each Now-layer item comes from and what its priority is?

Scope Boundaries

This skill is responsible for：

Backlog → Roadmap promotion / demotion decisions
Control via strategic_goal capacity guardrails
Updating roadmap.md and the status of promoted items

This skill is not responsible for：

Creating new backlog items (capture-work-items）
Scoring backlog items (prioritize-backlog）
Defining roadmap base structure / milestones (define-roadmap）
Task breakdown (handled by AgentFabric runtime)
Requirement recording (capture-work-items）

Handoff point: Promoted Now-layer items enter capture-work-itemsas needed, and then AgentFabric runtime completes design / task breakdown / execution.

Use Cases

Capacity release: The previous batch of Now-layer items is completed, releasing capacity, and new items need to be pulled in
Strategy refresh: After strategic goals are adjusted, re-evaluate whether Now-layer items are still appropriate
Large gap fill-in：plan-next The large gaps output are captured + prioritized and then enter promotion decisions
On-demand planning: The user proactively starts roadmap planning, not tied to a fixed cycle

Behavior

Phase 0: Read inputs

Read docs/process-management/roadmap.md(current Now / Next / Later status)
Read the backlog directory, filter items with priority already set (not unset)
Read docs/project-overview/strategic-goals.md(strategic goal list)
Read the strategic goal capacity allocation declared in roadmap.md (see Phase 1)

halt conditions：

roadmap.md does not exist → suggest first define-roadmap
strategic-goals.md does not exist → suggest first design-strategic-goals
All backlog items are priority: unset → suggest first prioritize-backlog
No capacity allocation in roadmap.md → halt, prompt to run define-roadmap to finalize capacity

Phase 1: Calculate current capacity status

For each strategic_goal:

Field	Meaning
Allocated capacity	Percentage of that goal in roadmap.md × total cycle capacity
Used capacity	Sum of the workload of items currently belonging to that goal in the Now layer
Remaining capacity	Allocated - Used

Output capacity table:

## 当前容量使用

| Strategic Goal | 分配 | 已用 | 剩余 | 占比 |
| 目标 1（用户价值） | 6 人周 | 4 人周 | 2 人周 | 67% |
| 目标 2（市场扩张） | 2 人周 | 1 人周 | 1 人周 | 50% |
| 目标 3（工程健康） | 2 人周 | 0 人周 | 2 人周 | 0% |

Phase 2: Generate promotion candidates

For each strategic_goal:

Filter the backlog items for that goal
Sort by priority (P0 > P1 > P2 > P3)
Pull from high priority downward according to remaining capacity, until that goal's capacity is filled or there are no more items

Output promotion candidate table:

## 晋升候选（Now 层）

| Goal | Item | Priority | Effort | 动作 |
| 目标 1 | #42 支付优化 | P0 | 2w | 晋升 Later → Now |
| 目标 3 | #17 技术债：auth 重构 | P1 | 2w | 晋升 Backlog → Now |

Phase 3: Demotion / deferral decisions

Check the current Now layer items:

If the priority has been downgraded (e.g., the result of a re-evaluation after a strategy change) → recommend demoting to Next or Later
If the strategic_goal capacity is over-allocated → recommend demoting the lowest priority item

Output demotion recommendations.

Phase 4: User confirms each decision

Present the merged list (promotions + demotions), and the user confirms item by item:

## 待确认清单

[ ] #42 晋升 Later → Now？
[ ] #17 晋升 Backlog → Now？
[ ] #8 降级 Now → Next？（超配 + priority 低）
[ ] ...

Phase 5: Persistence

For each confirmed decision:

Update the item frontmatter's status（captured → active to enter Now;active → deferred demotion)
Update roadmap.md, adding / removing the corresponding item references
Write the promoted_at / demoted_at timestamp to the item frontmatter

Phase 6: Output the final report

Number promoted / number demoted / number kept
Capacity usage after the update
Next-step recommendations (e.g., capture-work-items to handle the newly promoted Now items)

Input & Output

Input: roadmap.md + backlog (priority already set) + strategic-goals.md + capacity allocation.

Output: conversation decision table + roadmap.md update + item frontmatter update (status + promoted_at / demoted_at).

Restrictions

Hard Boundaries

Do not promote priority: unset items (first go through prioritize-backlog）
Do not exceed the strategic_goal capacity allocation (when over-allocated, you must demote before promoting)
Do not automatically promote P3 items to Now (P3 goes to Later by default)
Do not automatically modify the roadmap's strategic_goal capacity allocation (that is the responsibility of define-roadmap )

Skill boundaries

Not done (handled by other skills)：

Action	Ownership
Create backlog	`capture-work-items`
Score backlog	`prioritize-backlog`
Define roadmap structure and capacity	`define-roadmap`
Break down Now items into tasks	AgentFabric runtime (outside AI Cortex scope)
Detailed requirements record	`capture-work-items`

Anti-Patterns

❌ Do not bind to a fixed cycle("run every Monday") — this skill isevent-driven(capacity released / strategy change / on demand)
❌ Do not ignore capacity guardrails — you cannot over-allocate and seize another goal's capacity just because a goal has high priority items
❌ Do not promote too many at once — piling up more than the WIP limit in the Now layer will break the pull-based flow
❌ Do not operate on priority unset items —— Force scoring first
❌ Do not modify the roadmap structure(e.g., adding milestones) —— that is define-roadmap 's job

Self-Check

Successfully read roadmap.md, backlog, strategic-goals.md
Capacity allocation exists; if not, halted and suggested define-roadmap
Only process priority backlog items already decided
Capacity usage for each strategic_goal has been calculated
Promotion candidates generated sorted by priority + capacity constraints
Demotion suggestions consider priority and capacity over-allocation
User confirms item by item, no automatic approval
roadmap.md updated + item frontmatter updated
Output final capacity usage report

Examples

Example 1: Capacity release triggers promotion (mainstream scenario)

Background: 3 Now items completed in the cycle, releasing 4 person-weeks of capacity. strategic goals: Goal 1 (60%), Goal 2 (20%), Goal 3 engineering health (20%).

Process：

Calculate capacity —— Goal 3 has 2 weeks free, Goal 1 has 2 weeks free
Generate candidates:
- Goal 1: #42 payment optimization (P0, 2w) → promote Later → Now
- Goal 3: #17 auth refactor (P1, 2w) → promote Backlog → Now
User confirms item by item (all yes)
Update roadmap.md + item status to active
Capacity report: Goal 1 6/6, Goal 2 1/2, Goal 3 2/2

Result: 2 items promoted to Now; handoff suggests running capture-work-items to process new Now items.

Example 2: Strategic refresh causes large-scale re-evaluation (edge scenario)

Background: After the quarterly strategic refresh, new strategic Goal 4 is added, and Goal 3's capacity is adjusted from 20% to 10%.