twg-jira

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

twg-jira

Use with the root

twg

skill whenever Jira is the source of truth or a Jira mutation is required. This skill owns Jira semantics and safety; exact command grammar comes from live

twg help

搭配根技能

twg

使用，当Jira作为事实来源或需要对Jira进行变更操作时启用。本技能负责处理Jira的语义规范与安全逻辑；具体命令语法可查看实时的

twg help

。

CLI launcher fallback

CLI启动器回退方案

Run

twg <command>

. On shell

command not found

, use

$HOME/.local/bin/twg

(macOS/Linux) /

$env:LOCALAPPDATA\Programs\twg\bin\twg.exe

(PowerShell), then tell user to add that directory to PATH. Do not treat auth or command errors as PATH failures.

运行

twg <command>

。若shell提示

command not found

，请使用

$HOME/.local/bin/twg

（macOS/Linux系统）或

$env:LOCALAPPDATA\Programs\twg\bin\twg.exe

（PowerShell环境），然后告知用户将该目录添加到PATH中。请勿将认证错误或命令错误视为PATH配置问题。

Use When

使用场景

A Jira key, issue URL, project key, board, sprint, filter, or dashboard is the primary anchor.
The user asks to create, update, transition, comment on, link, watch, or delete Jira work.
The user asks to find or review duplicate Jira workitems.
Required or custom fields must be discovered and populated.
A workflow skill needs authoritative Jira fields or status.

Do not load this skill merely because Jira appears as one supporting artifact inside a cross-product answer.

以Jira问题键、问题URL、项目键、看板、迭代、过滤器或仪表盘为核心锚点时
用户要求创建、更新、流转状态、评论、链接、关注或删除Jira工作项时
用户要求查找或审核重复的Jira工作项时
需要发现并填充必填字段或自定义字段时
工作流技能需要获取权威的Jira字段或状态信息时

请勿仅因Jira作为跨产品回答中的一个辅助工件就加载本技能。

First Route

优先路由

Intent	Route
Known workitem	Native workitem `get`
Jira-only fuzzy text discovery	Workitem `search` (JQL-backed)
Exact Jira filtering	Workitem `query` with JQL
Semantic Jira discovery	`rovo search --app jira`
Duplicate workitem detection	`references/duplicates.md`
Related artifacts or people	Native read plus `context`
Link implementation artifacts	`jira workitem link`
Create or update	Field metadata, then mutation
Change workflow state	Discover transitions, then transition
Board or sprint ordering	Board/backlog/sprint command
Jira configuration	Jira administration namespace

Run one focused

twg help describe "<exact path>"

before an unfamiliar or consequential mutation.

意图	路由方式
已知工作项	原生工作项 `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 Semantics

Jira语义规范

"Issue" and "workitem" refer to the same Jira object in user language.
Jira projects/spaces are not Atlas projects. Use Jira for issue containers, schemes, boards, versions, components, filters, and dashboards.
JSM requests have an underlying Jira workitem, but approvals, portals, queues, request types, and SLAs belong to JSM.
Search results are candidate anchors. Use the native workitem read for final fields and status. Plain
```
get
```
avoids supplemental hydration; add
```
--comments
```
for complete comments or
```
--remote-links
```
for Jira remote links. The two enrichment flags may be combined. Use
```
--full
```
by itself for all fields and both enrichments.
For "what should I pick next," query actual open Jira work or the requested board backlog. Do not rank from broad activity alone.

在用户语境中，“Issue”和“workitem”指代同一个Jira对象。
Jira项目/空间并非Atlas项目。Jira用于管理问题容器、方案、看板、版本、组件、过滤器和仪表盘。
JSM请求有对应的底层Jira工作项，但审批流程、门户、队列、请求类型和SLA属于JSM范畴。
搜索结果为候选锚点。最终字段和状态信息请使用原生工作项读取命令获取。普通的
```
get
```
命令不会补充额外数据；添加
```
--comments
```
参数可获取完整评论，添加
```
--remote-links
```
参数可获取Jira远程链接。这两个扩展参数可组合使用。单独使用
```
--full
```
参数可获取所有字段及两种扩展数据。
当用户询问“我接下来应该处理什么”时，请查询实际的未完成Jira工作项或指定看板的待办事项。请勿仅通过宽泛的活动记录进行排序。

Safe Reads And Writes

安全读写规则

Resolve the site and workitem key before mutation.
Read current state before update, transition, link, comment, or delete.
Discover create/update field metadata before supplying required or custom fields.
Use returned
```
customfield_*
```
IDs rather than display names in writes.
Discover available transitions instead of guessing a transition name or ID.
- Run
```
twg jira workitem transition --id <KEY> --site <SITE> -o json
```
  without
```
--transition-id
```
  to discover available transitions, their screen field requirements, and required fields.
- Select a transition from the result and use its
```
requirements
```
  to gather the screen-required field values before calling with
```
--transition-id
```
  .
- Treat required fields as user-decision inputs. If the user did not supply a required value, do not infer or choose an allowed value; ask the user before transitioning. This includes Resolution: a request to cancel does not imply
```
Won't Do
```
  ,
```
Declined
```
  ,
```
Duplicate
```
  , or another Resolution.
- This discovery call is read-only and does not transition the workitem.
Keep global Jira field administration separate from workitem field values.
Use typed workitem artifact links when the request is to add Jira remote links to PRs, repos, deployments, builds, branches, commits, Loom videos, or meetings. These are not Jira Software devinfo/provider writes.
Verify mutations with a native read and report the resulting key and URL.

在执行变更操作前，先解析站点和工作项键。
在执行更新、状态流转、链接、评论或删除操作前，先读取当前状态。
在提供必填字段或自定义字段值前，先获取创建/更新的字段元数据。
在写入操作中使用返回的
```
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。

Handoffs

交接规则

Load
```
twg-context-discovery
```
for dependencies, related documents, or implementation links; load
```
twg-responsibility-routing
```
for owners, experts, authority, or escalation.
Load
```
twg-status-rollups
```
for project, sprint, team, or leadership synthesis.
Load
```
twg-engineering-work
```
when the Jira anchor must be traced to PRs or repositories.
Load
```
twg-operational-health
```
for incident, PIR, or reliability workflows.

若需获取依赖项、相关文档或实现链接，请加载
```
twg-context-discovery
```
技能；若需获取负责人、专家、权限或升级流程，请加载
```
twg-responsibility-routing
```
技能。
若需进行项目、迭代、团队或领导层的状态汇总，请加载
```
twg-status-rollups
```
技能。
若需将Jira锚点追踪到PR或仓库，请加载
```
twg-engineering-work
```
技能。
若需处理事件、PIR或可靠性工作流，请加载
```
twg-operational-health
```
技能。

References

参考文档

```
references/workitems.md
```
- workitem reads, writes, comments, and links
```
references/fields-and-transitions.md
```
- metadata-first fields and workflow changes
```
references/querying.md
```
- JQL and board/backlog selection
```
references/duplicates.md
```
- prompt driven duplicate detection and review
```
references/rich-content.md
```
- descriptions, comments, and mentions
```
references/administration.md
```
- Jira configuration versus workitem data

```
references/workitems.md
```
- 工作项的读写、评论与链接操作
```
references/fields-and-transitions.md
```
- 基于元数据的字段与工作流变更
```
references/querying.md
```
- JQL与看板/待办事项选择
```
references/duplicates.md
```
- 基于提示的重复项检测与审核
```
references/rich-content.md
```
- 描述、评论与提及功能
```
references/administration.md
```
- Jira配置与工作项数据的区别