SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsdefine-roadmap

define-roadmap

General & other

View repository

Updated 10-16 01:35

About this skill

Skill: Define Roadmap (Production v3.0.0)

Purpose

Derive a "decision-driving roadmap" from strategic goals, rather than a task list. A roadmap is not a collection of milestones, but apath expression。

Core Objective

Primary Objective: Generate a user-confirmed, decision-driving roadmap document, where each phase explicitly includes milestones, key initiatives, success metrics, and promotion criteria.

Success Criteria(all requirements must be met):

  1. ✅ Complete core model: Each phase must include Milestone, Strategic Bets, Metrics, and Promotion Criteria.
  2. ✅ Ordered structure and sense of path: Use Now / Next / Later to divide phases, reflecting the evolution path.
  3. ✅ Outcome- and metric-oriented: Success metrics should be quantified first; milestones should be outcome-oriented, and must never be mixed with feature lists or TODOs.
  4. ✅ Avoid false precision: The Later phase only states direction,without specific dates。
  5. ✅ Goal traceability and constraints: Establish goal mapping, and clearly define the constraint that "Backlog must map to the roadmap; requirements not belonging to the roadmap are by default not done."
  6. ✅ User confirmation and persistence: Explicit user approval, and write to the agreed path (default docs/process-management/roadmap.md or according to the specification milestones.md）。
  7. ✅ Capacity allocation by strategic_goal: The roadmap must declare the percentage of the current cycle capacity occupied by each strategic_goal, and the sum of all goal percentages must be 100%. The percentages are finalized by the user and must not be inferred by this skill (based on ADR 20260417-unified-value-driven-prioritization-model decision 3.4).

Acceptance Test: Can the reader see the evolution path at a glance (including promotion criteria)? Can they verify phase outcomes through success metrics, rather than merely checking a task list?

Handoff Point: After the roadmap is approved and persisted, hand off to backlog planning (capture-work-items) or routing diagnosis (plan-next）。

Scope Boundaries

This skill is responsible for：

  • Deriving and dividing phases (Now / Next / Later) from strategic goals.
  • Defining milestones, key initiatives (2–5), success metrics, and promotion criteria for each phase.
  • Organizing and generating a structured roadmap document.
  • Adhering to the project's agreed path.

This skill is not responsible for：

  • Defining the mission, vision, North Star, or strategic goals (use define-mission、define-vision、define-north-star、design-strategic-goals）。
  • Writing specific requirements (use capture-work-items); task breakdown is handled by runtime platforms such as AgentFabric.
  • Creating specific Backlog items (use capture-work-items）。

Use Cases

  • After strategic goals are established: Need to translate high-level strategic goals into specific phases, key initiatives, and metrics.
  • Phase transition assessment: Use "promotion criteria" (Next → Now) to decide whether the team can enter the next phase.
  • Planning and alignment meetings: Provide the team and stakeholders with a clear path expression and decision basis, and eliminate cluttered requirements that do not fit the current path.

Behavior

Interaction Policy

  • Default: output to docs/process-management/roadmap.md or follow the project's existing conventions. Automatically read docs/project-overview/strategic-goals.md as the input basis.
  • Inference and Confirmation: distill key initiatives and metrics based on the existing project state or context; before involving core decisions or overwriting existing documents, request explicit confirmation from the user.

Execution Process

  1. Load Strategic Goals: read the existing strategic goals and project background.
  2. Divide into Phases: structure into the Now / Next / Later perspective.
  3. Define Milestones: ensure they are outcome-oriented.
  4. Distill Key Initiatives: distill 2–5 key initiatives (Strategic Bets) for each phase.
  5. Define Success Metrics: set validation criteria for phase outcomes, prioritizing quantification.
  6. Define Advancement Conditions: clarify the prerequisites for entering the next phase (e.g., the switch conditions for Next → Now).
  7. Establish Goal Mapping: ensure that phase goals and the Backlog can be mapped to the strategy.
  8. Finalize Capacity Allocation: ask the user what percentage of capacity each strategic_goal occupies in the current cycle.
    • Present the strategic-goals list, asking item by item or requesting the user to provide the allocation all at once
    • Verify that the percentages sum to 100%; if not, halt and prompt for correction
    • Suggest a default layering (example: user value 60% / market expansion 20% / engineering health 20%), but let the user finalize it
    • The engineering health goal must not be 0%(based on ADR 1 Decision 3.5: engineering health must have capacity)
  9. Generate the Roadmap Document: generate a document draft according to the output structure template (including a "Capacity Allocation" section).
  10. Confirm and Persist: after user confirmation, persist the write and mark the last updated date.

Output Structure Template (Embedded Contract)

# 路线图

## 路线概览

Now / Next / Later（含推进条件简述）

## 容量分配（当前 cycle）

| Strategic Goal | 百分比 | 说明 |
| 目标 1（用户价值） | 60% | 核心交付 |
| 目标 2（市场扩张） | 20% | 邻近扩展 |
| 目标 3（工程健康） | 20% | 治理与技术债，不得为 0 |

> 本分配由 `promote-roadmap-items` 技能在容量护栏中消费（ADR 20260417 决策 3.4）。
> 百分比之和必须为 100%；工程健康目标不得为 0%。
> 战略刷新或容量调整需重跑本技能。

---

## Now

### 里程碑
- ...

### 关键举措
- ...

### 成功指标
- ...

---

## Next

### 推进条件
- ...

### 里程碑
- ...

### 关键举措
- ...

---

## Later

仅方向，不写时间

---

## 里程碑详情（附录）

| Milestone | Scope | Metrics | Goals |

Input & Output

Input：

  • Required: strategic goals (document or path); project background.
  • Optional: vision/north star metric; time range or phase preference.

Output：

  • Artifact: decision-level roadmap document.
  • Location：docs/process-management/roadmap.md or milestones.md(per project conventions).
  • Content: includes roadmap overview and Now/Next/Later details (milestones, key initiatives, metrics, advancement conditions).
  • Lifecycle: living (continuously updated as phases advance).

Restrictions

Hard Boundaries

  • Roadmap Mapping Constraint: clarify that "the Backlog must be mapped to the roadmap; requirements not belonging to the roadmap are by default not done".
  • Structural Enforcement: each phase must include the core model (milestones, key initiatives, success metrics, advancement conditions); none may be missing.
  • Capacity Allocation Must Not Be Omitted: each strategic_goal must have a percentage, and the sum = 100%; the engineering health goal must not be 0%.
  • Capacity allocation must not be inferred by this skill: Must be finalized by the user; suggestions may be made but nothing is written automatically.
  • No overwrite: Without explicit user confirmation, do not overwrite an existing roadmap file.

Anti-patterns (avoid)

  • Feature list: Degrading the roadmap into a pile of features.
  • TODO mixed in: Mixing in tasks at the concrete execution level.
  • No metrics: Unable to verify whether milestones have been achieved.
  • No key initiatives: Only goals without corresponding strategic actions.
  • False precision: Writing specific dates/times in the Later phase.

Skill Boundaries (avoid overlap)

Do not do these (other skills are responsible)：

  • Define strategic goals: Use design-strategic-goals。
  • Break down specific requirements: Use capture-work-items; task breakdown is handled by runtimes such as AgentFabric.
  • Write to-dos: Use capture-work-items。

When to stop and hand off：

  • User replies "approved/confirmed", etc. → roadmap complete, persist the document and hand off to plan-next or to-do planning.

Self-Check

Core success criteria (all criteria must be met)

  • Complete core model: The document includes milestones, key initiatives, success metrics, and advancement conditions.
  • Ordered structure and sense of path: The roadmap shows the evolution path based on Now / Next / Later.
  • Outcome- and metric-oriented: The content is outcome-oriented, with no feature or TODO lists.
  • Avoid false precision: The Later phase does not include specific times, only directions.
  • Goal traceability and constraints: It reflects the mapping relationship from the roadmap to strategic goals and constrains the Backlog.
  • Complete capacity allocation: Each strategic_goal has a percentage, the sum = 100%, and engineering health ≠ 0%.
  • User confirmation and persistence: The user has approved it, and it is written to the agreed path.

Acceptance test

Can the reader see the evolution path at a glance (including advancement conditions)? Can stage outcomes be verified through success metrics rather than simply checking a task list?

  • If not: success metrics or advancement conditions need to be added, and functional TODO lists removed.
  • If yes: the roadmap meets production-grade requirements; continue the handoff.

Examples

Example 1: Generate a production-grade roadmap based on strategic goals

Context: There is already a strategic goal containing 3 metrics, and an evolution path needs to be formulated. Process：

  1. Read the goals and divide them from the Now / Next / Later perspective.
  2. Define clear 3 key initiatives and quantified success metrics for Now.
  3. Define the "advancement conditions" for the Next phase (e.g., "when core architecture validation reaches 10k QPS, start the Next phase").
  4. List long-term exploration themes in Later (no dates).
  5. Present the document draft and, after approval, write it to docs/process-management/roadmap.md。 Result: The roadmap is persisted, clearly driving the next step of resource allocation and decision-making.

Example 2: Correct the task-list anti-pattern

Context: The user requests "help me turn these Backlog tasks into a roadmap with scheduling". Process：

  1. Explain to the user the principle of this skill: a roadmap is a path expression and decision model, not a task list.
  2. Abstract the specific Backlog into corresponding key initiatives and phased milestones.
  3. Add success metrics and advancement conditions for each phase, and remove fragmented TODOs.
  4. Provide a draft and confirm with the user. Result: Successfully convert the requirements list into a production-grade decision roadmap.

Example 3: Capacity allocation required (edge case)

Background: The user drafts a roadmap but skips the capacity allocation section and requests direct persistence. Process：

  1. Detected that the roadmap is missing "capacity allocation".
  2. halt and explain: "Capacity allocation is the guardrail basis for promote-roadmap-items (ADR 20260417 Decision 3.4); its absence will make promotion impossible to control according to strategic goals."
  3. Present the strategic-goals list:
    • Goal 1 (user value): ? %
    • Goal 2 (market expansion): ? %
    • Goal 3 (engineering health): ? %
  4. The user gives 70/20/10.
  5. Checksum = 100 ✓; engineering health 10% is not 0 ✓.
  6. Write the "capacity allocation" section and persist. Result: The roadmap contains capacity allocation consumable by promote-roadmap-items, closing the loop.