Roadmap Gen

Roadmap Generator

Generate or update docs/roadmap.md from GitHub Milestones, Issues, and PRs. Use live gh queries or a user-supplied, dated github_reader_data export. For an export, preserve its repository, capture time, completeness signals, current release context, and raw milestone/issue fields; do not invent missing live state.

This skill has two modes:

1. Generate: create a fresh roadmap from current GitHub state
2. Update: read existing docs/roadmap.md, sync with latest GitHub data, preserve manual annotations

Reader-Facing Writing Composition

For substantial reader-facing prose, co-load human-writing even on direct invocation; use the same context, not a later pass. This Skill retains evidence, facts, required structure, paths, gates, and verification. Skip code-, config-, schema-, lockfile-, and data-only output.

Mandatory Roadmap Classification

Classify roadmap position from milestone semantics, dependencies, release signals, and maintainer intent—not merely dates or version-like names. An undated or unmatched milestone remains pending maintainer classification and must not be silently placed in “unscheduled.” Identify release blockers only from explicit labels or equivalent GitHub evidence. Every roadmap still includes its required status/progress artifacts and Mermaid timeline; unknown dates may use semantic phases or clearly marked placeholders without inventing calendar commitments. Preserve every included issue's number, title, state, milestone or backlog classification, labels, link, and assignee state; explicitly write unassigned when the source has no assignee rather than dropping the field.

Step 1 — Establish repo context

If the request supplies a local GitHub status export, read it first and use the active installed github-reader skill's feed-mode contract as the evidence schema. Missing repository identity, capture time, milestone completeness, or issue state/label evidence must remain unknown in the roadmap.

gh repo view --json nameWithOwner,url,description

Capture OWNER, REPO, REPO_URL. If the user specified a repo, use that; otherwise use the current directory's remote.

Step 2 — Check for existing roadmap

cat docs/roadmap.md 2>/dev/null

• If exists → Update mode: preserve manual sections (marked with <!-- manual --> comments), update data-driven sections
• If not exists → Generate mode: create from scratch

Step 3 — Fetch GitHub data

Milestones (open + recently closed)

# Open milestones
gh api repos/{OWNER}/{REPO}/milestones \
  --jq '.[] | {title, state, open_issues, closed_issues, due_on, html_url, description}' \
  -X GET -f state=open -f sort=due_on -f direction=asc

# Recently closed milestones (for "已完成" section)
gh api repos/{OWNER}/{REPO}/milestones \
  --jq '.[] | {title, state, open_issues, closed_issues, due_on, html_url}' \
  -X GET -f state=closed -f sort=due_on -f direction=desc -f per_page=5

Issues per milestone

gh issue list \
  --json number,title,state,labels,assignees,milestone \
  --state all --milestone "{MILESTONE_TITLE}" --limit 100

Open issues without milestone (backlog candidates)

gh issue list \
  --json number,title,labels,assignees,createdAt \
  --state open --search "no:milestone" --limit 50

Labels for categorization

gh label list --json name,color,description --limit 100

Use labels to categorize issues into roadmap themes. Common patterns:

• feature / enhancement → 功能
• bug → 修复
• tech-debt / refactor → 技术优化
• docs → 文档
• Priority labels (P0, P1, priority:high) → 排序依据

Step 4 — Build roadmap structure

Organize milestones into timeline phases:

Phase classification rules

Semantic inference for no-date milestones

When due_on is null, infer the planning horizon from semver semantics: patch releases are near-term, minor releases are medium-term, and versions clearly beyond the repository's current release horizon are far-future. Milestones explicitly named Backlog, Unplanned, or 未排期 are self-evidently unscheduled and need no confirmation. List other milestones that cannot be matched by these semantics and ask the user to confirm their phase; do not automatically place them in an unscheduled fallback.

Apply semantic inference only when due_on is null. If due_on exists, always use date-based classification.

Issue grouping within each milestone

Step 1: Always surface release blockers first. If any issues have a release-blocker label, create a dedicated section at the top of the milestone:

**🚨 发布阻塞项**
- [ ] [#{N} 标题](URL)

Step 2: Group remaining issues by domain area. Infer domain groups from the repository's label semantics, preferring the most specific domain label when an issue has several labels. List labels whose domain meaning cannot be matched and ask the user to confirm their grouping; do not automatically place them in an “other” fallback.

Step 5 — Format the output

Write to docs/roadmap.md using this structure:

# 项目路线图

> 最后更新：{TODAY}
> 数据来源：[{OWNER}/{REPO}]({REPO_URL}) GitHub Milestones & Issues
> 自动生成，手动标注区域请用 `<!-- manual -->` 包裹以防覆盖

---

## 🔴 当前冲刺

### [{MILESTONE_TITLE}]({MILESTONE_URL}) — 截止 {DUE_DATE}

进度：██████████░░░░░░ 65% ({CLOSED}/{TOTAL})

**✨ 新功能**
- [x] [#{N} 标题]({URL}) @assignee
- [ ] [#{N} 标题]({URL}) @assignee

**🐛 修复**
- [x] [#{N} 标题]({URL})
- [ ] [#{N} 标题]({URL})

**🔧 技术优化**
- [ ] [#{N} 标题]({URL})

---

## 🟡 近期计划

### [{MILESTONE_TITLE}]({MILESTONE_URL}) — 截止 {DUE_DATE}

进度：████░░░░░░░░░░░░ 25% ({CLOSED}/{TOTAL})

**✨ 新功能**
- [ ] [#{N} 标题]({URL})

---

## 🔵 远期规划

### [{MILESTONE_TITLE}]({MILESTONE_URL})

{MILESTONE_DESCRIPTION}

- [ ] [#{N} 标题]({URL})

---

## ⚪ 未排期（仅显式未排期或经用户确认的条目）

### [{MILESTONE_TITLE}]({MILESTONE_URL})

- [ ] [#{N} 标题]({URL})

---

## ✅ 已完成

### [{MILESTONE_TITLE}]({MILESTONE_URL}) — {CLOSED_DATE}

{CLOSED}/{TOTAL} 完成

---

## 📋 Backlog（未关联 Milestone）

> 以下 issue 尚未分配到任何 milestone，可作为后续版本的候选。

| # | 标题 | 标签 | 创建时间 |
|---|------|------|---------|
| [#{N}]({URL}) | 标题 | `label1`, `label2` | {DATE} |

Progress bar generation rules

Generate a text-based progress bar (16 chars wide):

0%:   ░░░░░░░░░░░░░░░░
25%:  ████░░░░░░░░░░░░
50%:  ████████░░░░░░░░
75%:  ████████████░░░░
100%: ████████████████

Formula: filled = round(percentage / 100 * 16), use █ for filled, ░ for empty.

Mandatory formatting rules

[强制规则] Issue 状态映射：

• Issue state=closed → - [x]（已完成）
• Issue state=open → - [ ]（待完成）
• 每个 issue 必须带 GitHub 链接 [#{N} 标题]({URL})

[强制规则] Assignee 显示：

• 有 assignee → 在行尾加 @{login}
• 无 assignee → 不显示，但在 milestone 级别汇总 "🙋 {N} 个 issue 无 assignee"

[强制规则] 空 milestone 处理：

• 如果 milestone 下没有 issue → 仍然显示 milestone 标题和描述，注明 "暂无关联 issue"

[强制规则] Backlog 截断：

• 最多显示 20 条，超出写汇总行 "还有 {N} 个未关联 issue 未列出"

Step 6 — Update mode specifics

When updating an existing roadmap:

1. Preserve manual sections: any content between <!-- manual --> and <!-- /manual --> is kept as-is
2. Merge strategy:
   • New milestones → insert into correct phase
   • Closed milestones → move to "已完成" section
   • Issue state changes → update checkbox [x] / [ ]
   • New issues in existing milestones → append
   • Removed issues (closed + removed from milestone) → remove from list
3. Update header timestamp: always refresh "最后更新" date

Step 7 — Generate Mermaid timeline

If the repo has 2+ milestones with due dates, append a Mermaid gantt chart:

## 📊 时间线视图

```mermaid
gantt
    title 项目路线图
    dateFormat YYYY-MM-DD

    section 当前冲刺
    {MILESTONE_1} :active, m1, {START}, {DUE}

    section 近期计划
    {MILESTONE_2} :m2, {START}, {DUE}

    section 远期规划
    {MILESTONE_3} :m3, {START}, {DUE}
```​

Gantt chart rules:

• start = milestone creation date or earliest issue creation date
• end = milestone due_on
• Milestones without due_on are excluded from the chart
• Completed milestones use :done tag
• Current sprint uses :active tag

If no milestone has a reliable date, do not generate a Gantt chart. Append a Mermaid flowchart or timeline that shows only semantically supported phases and a separate “pending maintainer classification” branch; it must not contain fabricated calendar dates.

Edge cases

• No milestones: skip milestone sections, only output Backlog section, suggest user create milestones
• No issues: output milestone titles with descriptions only, note "暂无关联 issue"
• No due dates on any milestone: skip Mermaid chart; apply semver semantic inference and list unmatched milestones for user confirmation instead of blanket-classifying as 未排期
• Mixed: some milestones have dates, some don't: dated ones go into timeline phases; undated ones go through semantic inference, with unmatched ones listed for user confirmation
• Very large backlog (100+ unassigned issues): cap at 20, show count summary
• Update mode with no existing roadmap: fall back to Generate mode silently
• No GitHub auth: surface error clearly, tell user to run gh auth login