jira-progress

name	jira-progress
description	將當前 Claude Code session 的工作內容整理成 Jira ticket 的進度更新 comment。 當使用者說「整理成 jira 進度」、「寫 jira comment」、「更新 jira」、「整理進度」、 「幫我寫 comment」、「記錄到 ticket」等類似意圖時觸發此 skill。 也適用於使用者完成一段工作後想記錄進度的場景，即使沒有明確提到 Jira。

Jira 進度更新 Comment 產生器

你的任務是將這次 session 的工作內容，整理成一段可以直接貼到 Jira ticket comment 的進度更新。

核心原則

這份進度報告的讀者不只是工程師，還包括 PM 和主管。寫的時候請站在「使用者要在會議上用這份內容報告進度」的角度思考：

• 用中文撰寫
• 產出的格式是 Jira wiki markup，放在 codeblock 中讓使用者可以直接複製
• 要能展現工作的實質內容與複雜度：不需要寫到具體的函式名稱或實作細節，但應該讓讀者感受到這項工作涉及哪些面向、需要處理哪些考量。如果寫得太草率（例如「修好了一個 bug」），會讓人誤以為任務很簡單或不花時間。適當描述問題的背景、牽涉的範圍、採取的方向，可以讓讀者理解工作的份量
• 避免過度 specific 的技術細節：使用者需要能夠對報告中的每一點在會議上進行口頭說明。如果內容太 specific（例如具體的程式碼改動、特定的除錯步驟），使用者在被追問時可能無法回答，因為這些細節是你在執行過程中才知道的

簡單來說：讓讀者知道「做了什麼、為什麼要做、涉及哪些面向、目前狀態如何」，而非「每一步具體怎麼改的」。

撰寫要領

每一項工作描述都應該讓讀者理解因果脈絡，而不只是列出結論。

• 只在必要時提供背景說明：團隊日常使用的工具和概念不需要額外解釋，讀者本身就知道。但如果提到某個比較 specific 的內部機制或元件，而這個東西不是每個讀者都清楚它的角色，就值得用一句話簡短說明它是做什麼的
• 避免空泛的描述，具體說明怎麼做的：不要用「進一步分析」「交叉驗證」「深入調查」這類空泛的描述帶過。讀者會想知道你怎麼分析的、怎麼驗證的。用一兩句話說明實際的做法，讓讀者能理解驗證方法是否合理
• 解釋因果關係：當描述差異或問題時，補充「為什麼」。不要只說結果不同，要讓讀者理解造成差異的原因
• 描述問題的本質而非技術名稱：用「做什麼用的」來描述技術概念，而非直接丟出只有實作者才看得懂的術語。但描述要夠具體，讓讀者能理解實際發生了什麼，避免太過抽象含糊的說法

文風注意事項

• 中文一律使用全形標點符號（，。、：；「」（）！？），不要用半形的逗號、句號、冒號、括號。技術符號、程式碼、檔名、指令參數（如 --scanner fortify、.fpr）維持原樣，不要把裡面的半形標點轉成全形
• 不要使用「——」（全形破折號），這在中文技術文件中顯得不自然。使用逗號、句號來分隔語句，或直接拆成獨立的 bullet point
• 標題（h3.）不要加 ticket 號碼前綴（例如不要寫 h3. [PDMS-123] 標題，直接寫 h3. 標題）

Jira Wiki Markup 格式運用

不要只用純文字，適當使用 Jira wiki markup 的格式標記來提升可讀性：

• {*}粗體{*}：用於強調重要的結論、關鍵發現、或需要注意的事項
• {{monospace}}：用於技術名詞、工具名稱、檔案名稱、設定值、程式碼片段等
• {color:red}文字{color}：用於標記警告或需要特別注意的風險

容易搞錯的語法（Jira wiki markup 跟 markdown 不同）：

• 粗體：用 {*}...{*}，不是 markdown 的 **...** 或 *...*（後者在 bullet list 開頭會被當成 list marker）
• 等寬字 / 程式碼：只有 {{...}}，Jira wiki markup 沒有 backtick（`...`）語法，用了不會渲染成 monospace，只會原樣顯示反引號字元。檔名、設定值、程式碼片段、技術名詞都用 {{...}}

適當的格式修飾可以讓讀者更快速地掃讀重點，避免整篇都是同樣樣式的文字。

工作流程

1. 取得 Ticket 號碼

使用者必須提供 Jira ticket 號碼，絕對不要自己猜測或推斷。如果使用者沒有提供，請直接詢問。

2. 讀取既有 Comments（如果有 Jira MCP 可用）

如果有 jira_get_issue 或 jira_add_comment 等 Jira MCP 工具可用：

• 讀取該 ticket 最近的 comments，了解目前記錄到哪裡、語氣和風格如何
• 你產出的 comment 應該與既有 comments 的風格保持一致
• 注意 MCP 的格式限制：透過 Jira MCP 讀回來的既有 comment 會被轉成 markdown 的樣子（h3. 標題顯示成 ###、{{...}} 顯示成反引號、||表格|| 顯示成 markdown 表格）。這是 MCP 抓取時的轉譯，不是使用者原本寫的格式。不要因此誤判使用者是用 markdown 寫 comment，產出時一律使用 Jira wiki markup。既有 comment 只拿來參考語氣、結構與詳略程度，不要模仿它被轉譯後的語法

如果沒有 Jira MCP 工具，跳過這步，直接根據下方格式撰寫。

3. 回顧 Session 內容

回顧這次 session 中做了哪些事情，包括：

• 討論了什麼問題或需求
• 實作了什麼功能或修復
• 遇到了什麼困難、牽涉哪些面向
• 目前的狀態（完成、進行中、待辦）

4. 撰寫 Comment

根據內容的複雜度彈性決定結構：

簡單任務（單一問題修復、小調整）：

h3. 修復 XXX 問題

* 描述描述，{*}結論是 XXX{*}
* 確認 {{某個設定}} 已正確配置

較複雜的任務（多個面向、較長的工作過程）：

h3. 實現 XXX 功能

描述這次工作的整體概況（一兩句話）

h4. 子主題 A
* 描述描述描述
* {*}關鍵發現{*}：描述描述

h4. 子主題 B
* 描述描述描述

結構不是固定的，根據內容自然地組織即可。重點是讓讀者能快速掌握進度。

5. 輸出格式

將最終的 Jira wiki markup 內容包在 markdown codeblock 中輸出，讓使用者可以直接複製：

```
h3. 標題

* 內容
* 內容
```

輸出 comment 內容後，簡短提示使用者可以直接複製貼到 Jira。如果有 Jira MCP 可用，也可以詢問使用者是否要直接透過 MCP 發佈 comment。