twg-jira

twg-jira

当 Jira 是事实来源或需要修改 Jira 时，与根目录中的 twg skill 配合使用。此 skill 负责 Jira 语义和安全；命令语法以实时的 twg help 为准。

CLI 启动器回退方案

运行 twg <command>。如果 shell 提示 command not found，则使用 $HOME/.local/bin/twg（macOS/Linux）/ $env:LOCALAPPDATA\Programs\twg\bin\twg.exe（PowerShell），然后告知用户将该目录添加到 PATH。不要将身份验证或命令错误视为 PATH 故障。

适用场景

• Jira 键、问题 URL、项目键、看板、冲刺、筛选器或仪表板是主要锚点。
• 用户要求创建、更新、转换状态、评论、关联、关注或删除 Jira 工作项。
• 用户要求查找或审核重复的 Jira 工作项。
• 需要发现并填写必填字段或自定义字段。
• 工作流 skill 需要权威的 Jira 字段或状态。

不要仅仅因为 Jira 是跨产品回答中的一个辅助资料，就加载此 skill。

首选路由

意图	路由
已知工作项	原生工作项 get
多个已知工作项	使用包含所有键的单次 get/bulk-get
仅限 Jira 的模糊文本搜索	工作项 search（基于 JQL）
精确的 Jira 筛选	使用 JQL 的工作项 query
语义化 Jira 搜索	rovo search --app jira
检测重复工作项	references/duplicates.md
相关资料或人员	原生读取并结合 context
关联实现资料	jira workitem link
创建或更新	先获取字段元数据，再执行修改
更改工作流状态	先发现可用转换，再执行转换
看板或冲刺排序	看板/待办列表/冲刺命令
Jira 配置	Jira 管理命名空间

遇到不熟悉或影响重大的修改前，先运行一次针对性明确的 twg help describe "<exact path>"。

Jira 语义

• 在用户语言中，“Issue”和“workitem”指的是同一个 Jira 对象。
• Jira 项目/空间并非 Atlas 项目。问题容器、方案、看板、版本、组件、筛选器和仪表板应使用 Jira。
• JSM 请求底层对应一个 Jira 工作项，但审批、门户、队列、请求类型和 SLA 属于 JSM。
• 搜索结果只是候选锚点；最终字段和状态应使用原生工作项读取来确认。普通的 get 不会补充其他数据；可添加 --comments 和/或 --remote-links，或使用 --full 获取所有字段及两者。
• 对于“接下来该选什么”，应查询实际未关闭的 Jira 工作或指定看板的待办列表。不要仅根据宽泛的活动记录进行排序。
• 一次调用即可读取一组工作项：jira workitem get、jira workitem bulk-get 和 context jira workitem 都接受多个键。切勿对键列表循环调用 get。如果字段可查询，请使用 jira workitem query --jql <jql> --fields <fields>，无需再补充读取。

安全读取与写入

• 在执行变更前，先解析站点和工作项键。
• 在更新、转换、关联、评论或删除前，先读取当前状态。
• 在提供必填字段或自定义字段前，先发现创建/更新字段元数据。
• 写入时使用返回的 customfield_* ID，而非显示名称。
• 发现可用的转换，而不是猜测转换名称或 ID。
  • 运行 twg jira workitem transition --id <KEY> --site <SITE> -o json，不带 --transition-id，以发现可用的转换及其所需的界面字段。
  • 选择一个转换，并使用其 requirements 收集字段值，然后再通过 --transition-id 调用。
  • 将必填字段视为需要用户决定的输入。如果用户未提供必填值，不要推断或选择允许的值；请在转换前询问用户。这包括 Resolution：用户要求取消并不代表应选择 Won't Do、Declined、Duplicate 或其他 Resolution。
  • 此发现调用为只读操作，不会转换工作项。
• 将 Jira 全局字段管理与工作项字段值分开处理。
• 使用类型化的工作项工件关联，为 PR、仓库、部署、构建、分支、提交、Loom 视频或会议添加 Jira 远程链接。这些不是 Jira Software devinfo/provider 写入。
• 使用原生读取验证变更，并报告生成的键和 URL。

交接

• 加载 twg-context-discovery，以查找依赖项、相关文档或实现链接；加载 twg-responsibility-routing，以查找负责人、专家、权限或升级路径。
• 加载 twg-status-rollups，以汇总项目、冲刺、团队或领导层信息。
• 当需要将 Jira 锚点追溯到 PR 或仓库时，加载 twg-engineering-work。
• 对于事件、PIR 或可靠性工作流，加载 twg-operational-health。

参考资料

• references/workitems.md - 工作项读取、写入、评论和关联
• references/fields-and-transitions.md - 以元数据为先的字段和工作流变更
• references/querying.md - JQL 和看板/待办事项选择
• references/duplicates.md - 由提示词驱动的重复项检测与审查
• references/rich-content.md - 描述、评论和提及
• references/administration.md - Jira 配置与工作项数据