jira-ticket-prioritizer

JIRA 工单优先级排序器

分析一组 JIRA 工单，根据依赖关系、优先级和分组确定最佳执行顺序。生成分组层级，可独立使用，也可作为 implement/forge 之前的预处理步骤。

输入

原始参数：$ARGUMENTS

根据参数推断：

• TICKET_INPUT：逗号分隔的工单键，或 JQL 查询（通过是否包含 =、AND、OR 判断）
• EXTRA_CONTEXT：（可选）用于确定优先级的补充背景信息

系统要求

• 已安装并配置 jira CLI（https://github.com/ankitpokhrel/jira-cli）
• 已设置环境变量 JIRA_API_TOKEN，且其值为有效的 Jira API 令牌。重要： 检查此变量时，至少验证 2 次后再判定其未设置。绝不要泄露该值——仅检查变量是否存在。

执行

步骤 1 — 解析输入

• 检查 TICKET_INPUT 是否包含 =、AND 或 OR（不区分大小写），以判断是否为 JQL
• 如果检测到 JQL：运行 jira issue list --jql "TICKET_INPUT" --plain --columns key,status --no-headers，解析出工单键及其状态
• 如果是逗号分隔的输入：按 , 拆分并去除空白
• 验证每个键是否匹配 [A-Z]+-\d+
• 如果有效工单少于 2 个，报告该单个工单并退出

步骤 2 — 分类并获取所有工单

• 创建临时目录：mkdir -p .jira-ticket-prioritizer-tmp/tickets
• 对每个工单键，通过 jira CLI 获取：

  jira issue view {KEY} --raw > .jira-ticket-prioritizer-tmp/tickets/{KEY}.json
  

• 使用 jira-ticket-viewer 解析脚本解析每个工单：

  node ${CLAUDE_SKILL_DIR}/../jira-ticket-viewer/scripts/parse-ticket.js < .jira-ticket-prioritizer-tmp/tickets/{KEY}.json > .jira-ticket-prioritizer-tmp/tickets/{KEY}-parsed.json
  

• 将所有解析结果收集到一个 JSON 数组中，并写入 .jira-ticket-prioritizer-tmp/all-tickets.json
• 按状态对工单分类——获取并解析所有工单，然后分成两组：
  • pending = 状态为 "To Do" 或 "Backlog" 的工单——这些工单会评分、分组并放入输出层级
  • context = 状态为其他任意值（"In Progress"、"In Review"、"Done"、"Closed"、"Resolved"）的工单——这些工单不会放入层级，但会在步骤 3–5 中用于解析依赖关系

步骤 3 — 构建依赖关系图

• 运行：node ${CLAUDE_SKILL_DIR}/scripts/build-dependency-graph.js < .jira-ticket-prioritizer-tmp/all-tickets.json > .jira-ticket-prioritizer-tmp/graph.json
• 检查图的输出，查看是否存在循环或警告
• 关系映射规则请参阅 references/dependency-analysis.md
• 图中包含所有工单（pending + context），因此可以查看对进行中或已完成工单的依赖关系

步骤 4 — 语义依赖关系分析与父工单评估

• 根据 references/dependency-analysis.md 评估父级/容器工单和语义依赖关系
• 向图中添加带有置信度等级（high/medium/low）的软边
• 如果添加了新边，则重新运行拓扑排序：
  • 使用额外的 softEdges 更新 all-tickets.json，并重新运行 build-dependency-graph.js

第 4b 步 — 冗余检测

• 阅读 references/redundancy-analysis.md，了解完整的检测规则
• 查看每一对待处理工单，并评估它们的范围重叠程度——考虑摘要、描述、组件、标签、工单类型以及任何明确的 JIRA 重复链接
• 对每一对工单，判断它们描述相同工作的可能性有多大：为重叠程度分配权重，并标注置信度
• 当两张工单明显重叠时，确定哪张是主工单——优先选择得分较高的工单；若得分相同，则选择编号较小的工单
• 当重叠程度足以采取行动时（高置信度，或中置信度且权重较高），将次要工单从待处理集合中移出，并放入 skipped。用通俗易懂的语言说明具体发现——哪些字段重叠、文本相似度如何，以及为何判定一张工单的范围已由另一张覆盖。证据字符串的编写指南请参阅 references/redundancy-analysis.md
• 当重叠较弱时（低置信度，或中置信度且权重较低），将工单视为相互独立——将两者都保留在层级中，不要标记它们
• 在此处移至 skipped 的工单不得出现在后续的评分或分组步骤中

第 5 步 — 优先级评分与分组

• 仅对 pending 工单评分——context 工单不评分，也不放入层级
• 对于依赖层级相同的工单，使用 references/priority-weights.md 中的权重评分
• 在每个层级内按得分降序排序
• 将 EXTRA_CONTEXT 上下文作为平分时的决胜因素或加分项
• 在同一层级内对相关工单分组——参阅 references/dependency-analysis.md 中的分组规则。每组中的第一张工单（得分最高）为主工单。
• 解决跨层级依赖关系：
  • 如果待处理工单依赖的 context 工单状态为 "Done"/"Closed"/"Resolved" → 依赖已解决，工单正常继续处理
  • 如果待处理工单依赖的 context 工单处于其他任何状态（例如 "In Progress"）→ 将其标记为 skipped，并在原因中注明依赖键及其状态
  • 如果待处理工单依赖另一张位于不同层级的 pending 工单 → 按正常层级处理（第 N+1 层依赖第 N 层）
• 状态为 "Done"/"Closed"/"Resolved" 的工单 → excluded
• 没有可实施工作的容器型／父级故事 → excluded

第 5a 步 — 仓库分配

阅读 references/repo-assignment.md，了解完整规则。根据这些规则，为每张工单确定 repos、branch、complexity 和 hasFrontend。

第 6 步 — 生成输出

• 报告架构和 JSON 结构请参阅 references/output-format.md
• 写入 .jira-ticket-prioritizer-tmp/detailed-report.json——包含完整详情，包括得分、理由、依赖关系图、已跳过的工单、已排除的工单和警告
• 写入 .jira-ticket-prioritizer-tmp/output.json——包含 layers、skipped 和 excluded 数组的分组层级对象
• 仅向用户展示 output.json。详细报告保存供参考，但不显示。

第 7 步 — 清理

• 移除临时目录：rm -rf .jira-ticket-prioritizer-tmp

参考文件

名称	何时阅读
references/priority-weights.md	步骤 5 — 评分规则和因素权重
references/output-format.md	步骤 6 — 报告模板和 JSON 架构
references/dependency-analysis.md	步骤 3-5 — 依赖检测和分组规则
references/redundancy-analysis.md	步骤 4b — 冗余检测、权重/置信度规则、跳过条目格式
references/repo-assignment.md	步骤 5a — 仓库理解、分配规则、分支/复杂度/hasFrontend