jira-sprint-dashboard

Jira 冲刺仪表板

构建一个重点明确的仪表板，帮助工程经理、技术负责人或高级工程师快速了解当前的 Jira 工作，并据此判断哪些事项需要关注。输出应为仪表板，而不是文字报告，也不是泛泛的健康度评分。

此技能默认只读。除非用户查看仪表板后明确要求执行写入操作，否则不得创建、更新、转换状态、分配或评论 Jira 工作项。

输出模式

使用当前环境支持的功能最丰富的仪表板渲染器。不同渲染器中的仪表板内容、结论、计数和来源附录必须保持一致；只有呈现方式可以不同。

按以下顺序选择渲染器：

1. 如果在支持 Canvas 的 Cursor 中运行，使用 Cursor Canvas。
2. 如果当前 Agent 支持 HTML、React 或类似的制品输出，使用交互式制品。
3. 如果支持创建文件且这样做有用，使用静态 HTML 文件。
4. 如果没有更丰富的可视化渲染器，使用 Markdown 仪表板。
5. 仅当无法进行可视化渲染时，使用结构化 JSON 加简短摘要。

除非用户明确要求使用 Cursor Canvas，否则不要提及 Cursor Canvas 不可用。如果用户只是笼统地要求仪表板，则使用当前环境可用的最佳渲染器，不要为环境限制致歉。

Cursor Canvas 渲染器

仅在支持 Canvas 的 Cursor 中运行时使用本节。

编写 Canvas 代码前，先阅读 ~/.cursor/skills-cursor/canvas/SKILL.md。如果需要了解准确的导出项或属性类型，请阅读 ~/.cursor/skills-cursor/canvas/sdk/ 中的文件。

Canvas 限制：

• 在 Cursor canvases 目录中创建一个 .canvas.tsx 文件。
• 仅从 cursor/canvas 导入。不要导入 react、CSSProperties、JSX、Atlaskit 或其他包。
• 将 Jira 数据直接嵌入 Canvas；不要从 Canvas 发起数据获取。
• 优先使用 Stack、Grid、Card、Stat、Table、Pill、Callout、UsageBar、BarChart、LineChart、PieChart 和 Code 等 Canvas 原语，而不是原始 HTML。
• 使用 useHostTheme() 设置自定义样式。不要硬编码十六进制颜色、渐变、阴影、ADS 变量、不受支持的 CSS 框架或 @atlaskit/*。
• 除非用户要求，否则不要发布或分享 Canvas。

便携式渲染器

Cursor Canvas 不可用时使用本节。

交互式制品渲染器：

• 将相同的仪表板模型渲染为交互式制品。
• 优先使用表格、紧凑图表、统计行和可折叠的来源详情。
• 保持交互轻量：筛选、展开详情或切换图表／表格视图均可；不要要求制品实时获取 Jira 数据。

静态 HTML：

• 创建一个内嵌数据的独立仪表板文件。
• 使用响应式布局、易访问的表格；如果没有可用的图表库，则使用简单的类图表视觉元素。
• 不要从 HTML 文件获取 Jira 数据。

Markdown：

• 保持仪表板内容的顺序。
• 使用紧凑表格展示统计数据、负责人工作量、风险、最高优先级工作和来源附录。
• 只有在如实表达的情况下，才使用文本图表替代项，例如计数、百分比和简单条形图。
• 避免将输出写成长篇文字报告。

JSON 备用方案：

• 返回规范化的仪表板模型。
• 附上简短的易读摘要，说明最值得关注的风险和来源范围。

获取范围

不要猜测 Jira 范围。如果用户没有提供项目键、空间键、看板、冲刺、筛选器、JQL、工作项键或 Jira URL，请停止并向用户索要。随机选取一个可见项目的仪表板或猜测团队背景，都不如没有仪表板。

如果用户提供了项目键或空间键，但没有提供冲刺、看板或筛选器，请从 Jira JQL 的 project 字段和用户提供的键开始：

project = "SPACE_KEY" AND sprint in openSprints() ORDER BY Rank ASC

如果开放冲刺的结果为空、已过时或具有误导性，请切换到快照模式，并在顶部栏下方添加简短说明：

project = "SPACE_KEY" AND statusCategory != Done ORDER BY priority DESC, updated ASC
project = "SPACE_KEY" AND updated >= -60d ORDER BY updated DESC

除非用户要求其他时间段，否则默认使用最近 60 天的动态窗口。

并非所有看板都支持冲刺。类型为 simple 的团队管理型看板完全没有冲刺：sprint in openSprints() 不会返回任何结果，查询看板冲刺也会失败，并显示“The board does not support sprints”。请将此视为直接切换到快照模式的信号，而不是值得重试的错误。

查询 Jira

使用只读 Jira 搜索。只请求仪表板所需的字段，并允许字段缺失。

有用的字段：key、summary、status、statusCategory、assignee、 priority、issuetype、created、updated、resolutiondate、duedate、 parent、issuelinks、labels、components、fixVersions、sprint，以及 任何可用的估算值／故事点字段。

Sprint 和故事点存储在自定义字段中，默认响应会省略这些字段。 Jira 搜索默认采用精简视图，因此基于该视图构建的 Sprint 仪表板看起来会缺少 Sprint 信息，即使 Sprint 处于活动状态也是如此。如需获取这些信息，可传入 view: "evidence"（或 "full"），也可以显式请求此站点的 customfield_* ID——这些 ID 因 Cloud 站点而异。自定义字段值会返回在 fields.customFields 下，而不是顶层的 customfield_* 键中。

从 maxResults: 100 开始。对于完整的 Sprint、看板或筛选器仪表板， 请分页获取数据，直到覆盖完整范围，或数据量大到不适合有效地逐项呈现工作项。

默认使用一次完整的分页范围查询。根据返回的工作项集合在本地推导常规仪表板 信号，而不是为每个信号单独执行 JQL 查询。

如果范围查询返回了所需字段，请在本地推导以下信息：

• 最近完成的工作项：根据 statusCategory = Done 和 resolutiondate 判断。
• 长期未完成的工作项：根据 statusCategory != Done 和 updated 判断。
• 未分配负责人且未完成的工作项：根据 statusCategory != Done 和空的 assignee 判断。
• 高优先级且未完成的工作项：根据 statusCategory != Done 和 priority 判断。
• 状态或标签阻塞项：根据 status、statusCategory 和 labels 判断。
• 负责人工作量、长期未更新的工作、截止日期风险和规划缺口：根据规范化后的范围数据集判断。

仅在以下情况下使用定向补充查询：需要支持无法根据范围数据安全推导的可见结论； 范围太大，不适合在本地有效处理；或用户要求提供每个信号的精确证据，进行审计式仪表板分析。

经验法则：

• 小型或中型 Sprint 仪表板：优先使用一次完整的分页范围查询；必要时最多再进行一次针对阻塞文本或依赖状态的定向补充查询。
• 大范围仪表板：如果拉取并处理完整的工作项集合会很慢或价值不高，则使用范围更窄的补充查询。
• 需要大量证据的审查：如果精确的 JQL 证据比减少调用次数更重要，可以接受执行多个聚焦查询。

仅在有充分理由时，使用以下定向补充查询示例：

• 最近完成的工作项：<scope> AND statusCategory = Done ORDER BY resolutiondate DESC
• 长期未完成的工作项：<scope> AND statusCategory != Done AND updated <= -3d ORDER BY updated ASC
• 未分配负责人且未完成的工作项：<scope> AND statusCategory != Done AND assignee is EMPTY ORDER BY priority DESC, updated ASC
• 高优先级且未完成的工作项：<scope> AND statusCategory != Done AND priority in (Highest, High) ORDER BY priority DESC, updated ASC
• 阻塞信号：<scope> AND statusCategory != Done AND (status = Blocked OR text ~ "blocked" OR labels in (blocked, blocker)) ORDER BY priority DESC, updated ASC

除非来源附录展示了支持该结论的查询或返回字段覆盖情况，否则不要作出“没有阻塞项”或“没有依赖项”等否定性结论。如果检查阻塞项时只检查了状态和标签，就应说明未发现状态或标签阻塞项，而不是声称不存在任何阻塞项。如果未检查某个信号，请明确说明。

对于推导出的信号，请在来源附录中引用基础范围 JQL 和字段覆盖情况，不要臆造单独的支持性查询。仅当实际执行了定向补充查询时，才附上额外 JQL。

对于工作项链接（issuelinks），请尽可能获取所链接工作项的状态／类别。如果无法获取链接项的详细信息，则将依赖项状态显示为未知，而不是已解决。

规范化

设计输出之前，先创建一个紧凑且独立于渲染器的工作项模型，其中包含：

• 键、URL、摘要、类型、状态、状态类别、优先级
• 经办人显示名称，或 Unassigned
• 所有者状态：active、inactive、unknown 或 unassigned
• 创建时长、更新时间、完成后的解决时长、距截止日期的时间
• 父项／史诗／工作流、迭代、估算值、组件、版本、标签
• 关联工作项的键、方向、关联类型，以及可用时的关联状态

派生信号应能根据 Jira 中的事实加以解释：已完成、进行中、尚未开始、长期未更新、长期未更新（严重）、受阻、无所有者、所有者已停用、时间敏感、影响支持、跨空间依赖，以及规划数据缺失。将仅根据文本得出的弱信号标记为推断。

仪表板模型

渲染之前先创建仪表板模型。所有渲染器都应使用同一个模型。

包括：

• 上下文元数据：标题、项目或空间、迭代、看板、筛选器、JQL、时间范围、查询时间戳和模式
• 四项顶部统计：已承诺或范围总量、已完成、进行中，以及需关注
• 范围说明；仅当缺少迭代数据、数据混杂或过时，或与近期项目动态混合时提供
• 可选的容量或承诺分段，仅在存在真实数据时提供
• 可选的图表数据，仅在类别、数值、单位和时间范围均可用时提供
• 所有者负载和缺口
• 风险和关注事项
• 优先级最高的工作项表格
• 最近完成的工作
• 来源附录，包含准确的 JQL、字段覆盖情况、假设，以及 Needs attention 的构成

不要为了填充模型而编造数据。空白或不受支持的部分应省略。

仪表板结构

保持可见的仪表板简洁且确定。当数据可用时，大体遵循以下顺序：

1. 简洁的上下文标题

   • 显示标题以及项目、空间、看板、迭代或时间窗口元数据。
   • 保持简短。不要在顶部放置查询、字段覆盖情况或概述性文字。

2. 顶部四项统计栏

   • 恰好显示四项统计值。
   • 默认显示承诺/总量、已完成/完成、进行中/处理中以及需要关注。
   • 没有故事点时，使用工作项数量。
   • 需要关注 应综合最重要的风险信号：受阻、长期未更新、未分配、时限紧迫或尚未解决的关联工作。
   • 只有在次要数量会改变整体判断时，才将它们放在首屏以下。

3. 范围说明，仅在需要时显示

   • 当迭代数据缺失、混杂、过时或与近期项目动态混在一起时，在顶部统计栏下方添加一条简短说明。
   • 限制为 1 到 2 个简短句子。

4. 容量或承诺进度条

   • 仅当容量、承诺或分配分段数据可用时，才显示容量或承诺可视化。
   • 不要臆造容量、分段或缓冲值；没有数据时直接跳过。

5. 迭代图表

   • 如果有可用数据，以折线图显示随时间变化的剩余工作量。
   • 在旁边以饼图或紧凑的状态可视化显示状态分布。
   • 在下方以柱状图显示每个工作日解决/完成的数量。
   • 类别、数值、单位或时间范围缺失时，跳过对应图表。绝不显示占位、示例、空白或猜测得出的图表。

6. 负责人负载与缺口

   • 按受指派人显示进行中、长期未更新、受阻、影响支持工作和已完成的数量。
   • 包括未分配、负责人不活跃和负责人状态未知的分类。
   • 保持简洁；优先使用小型表格或柱状图，而非为每位负责人单独制作卡片。

7. 风险与关注事项

   • 放在负责人负载下方。
   • 仅包括最可能需要经理或负责人关注的工作项。
   • 每项显示键、原因、依据、负责人、持续时间和下一步问题。
   • 如果存在明显的最高交付风险，使用提示框或高亮行突出显示。

8. 最高优先级工作项表

   • 添加紧凑表格，列出迭代中优先级最高的工作项或最需要关注的事项。
   • 默认不显示所有信号较弱的工作项。

9. 近期完成项和可选详情

   • 如果近期有已完成的工作，将其放入折叠区域或紧凑表格中，置于主要概览下方。
   • 仅当工作流分组和依赖关系会改变查看者接下来应检查的内容时，才显示这些信息。
   • 默认仅显示尚未解决或状态未知的关联工作。

10. 来源附录

    • 在底部列出确切的 JQL、查询时间戳、字段覆盖情况、假设，以及 需要关注 的构成。

如果无法获取完整数据集，仍应保持大致相同的顺序，并省略无法如实呈现的章节或图表。

内容与风格

• 优先使用图表和表格，而非大段文字。
• 数据支持时遵循参考布局顺序；跳过缺乏数据支持的图表，不要因此改变整个页面结构。
• 工作项摘要应简短；除非需要引用简短摘录来说明影响，否则避免显示完整描述。
• 每条建议或下一步问题都应对应工作项键或汇总数量。
• 将 Jira 中的事实与推导或推测出的信号分开。
• 渲染器支持时，使用语义化色调：success 表示已完成，warning 表示长期未更新/截止日期风险，danger 表示受阻/逾期/严重风险，info 表示说明/关联工作，neutral 表示信号较弱的事实。
• 颜色应搭配标签。优先使用工作项键链接，而非大型按钮。
• 首屏应聚焦状态和关注事项，而非流程说明。

特定渲染器的样式

对于 Cursor Canvas：

• 使用 Canvas 组件和宿主主题样式。
• 保持顶部区域紧凑：上下文标题后紧接恰好四项统计数据。
• 优先使用 Canvas 表格和图表，而非自定义布局代码。

对于交互式制品或静态 HTML：

• 使用克制的仪表盘布局，搭配紧凑的卡片、表格和简单图表。
• 确保文本在移动设备和桌面设备上都清晰易读。
• 为图表替代内容和状态颜色使用无障碍标签。
• 将来源详情放在主仪表盘下方。

对于 Markdown：

• 使用简短的章节标题。
• 优先使用表格，而非段落。
• 保持注意事项和建议简洁。
• 将来源查询放在底部。

自检

返回前：

• 范围来自用户或所提供的 URL；如果范围缺失或含糊不清，应在查询前先进行澄清。
• 所选渲染器符合当前环境的能力。
• 仅在 Cursor Canvas 可用时使用 Cursor Canvas 指令。
• 如果使用了 Cursor Canvas，画布只能从 cursor/canvas 导入内容。
• 顶部区域是紧凑的上下文标题，后接恰好四项统计数据。
• 顶栏上方没有查询列表、字段覆盖情况或执行摘要。
• 尽可能根据分页范围查询得出常规信号；仅当有针对性的后续查询能够支持范围数据无法可靠支持的可见声明时，才使用此类查询。
• 计数与所查询的工作项集合相符。
• 省略空章节。
• 仅在类别、数值、单位和时间范围都可用时才呈现图表。
• 风险标签可根据可见的 Jira 数据进行解释。
• 来源附录包含精确的 JQL，以及可见声明所涉及的字段覆盖情况。
• 未使用 Jira 写入工具。