jira-cr

Jira Change Request (CR) Skill

This skill guides the agent in generating a Change Request (CR) summary for a provided Jira ticket and publishing it as a comment when requested. Resolve the repository and Jira site from the current task; this skill can be installed and used independently.

Trigger

User-invoked: /jira-cr — use this skill explicitly when asked to create a CR summary for a Jira ticket (e.g., "Create a CR for PROJ-001", "run jira-cr for [Ticket ID]").

Workflow Instructions

1. Fetch Jira Ticket Information:

   • Discover the available Jira tools by capability: site discovery, issue retrieval, comment listing, and comment creation. Tool names vary by agent; use the configured equivalents rather than assuming a fixed MCP namespace or shell-tool name.
   • Resolve the intended site and issue key from the user and project context. If multiple sites remain plausible, ask before selecting one.
   • Fetch the issue and existing comments. Follow comment pagination until the relevant prior summaries are found or all available comments have been checked. If access is incomplete, state that limitation and do not claim no prior summary exists.
   • Extract the Summary, Description, and Acceptance Criteria (AC) from the issue.

2. Detect Previous CR Summary:

   • Scan the existing comments for a previously posted CR summary — detect it by its banner line ("AI-generated CR summary" for a first summary, "Updated CR summary" for an update) or by a Story & CR heading at any level. Comment bodies may come back in a different markup, so do not rely on a literal # prefix. If several match, use the most recent one.
   • Note the previous summary's comment ID, posted date, language, and any details it carries that cannot be regenerated from the diff (e.g., screenshots).

3. Resolve and Read the Change Scope:

   • Inspect repository instructions, Git status, branch, and remotes. Follow the user's explicit staged/commit/branch/MR/PR scope first.
   • For staged work, read git diff --cached; for a specific commit, inspect its patch and parents; for a commit range, inspect all requested commits and the resulting diff; for a branch, verify its base and compare the complete branch diff; for an MR/PR, read its verified source/target refs and full diff after fetching relevant refs.
   • If no scope was named, infer it from the current task, matching ticket branch, and existing MR/PR. An empty staged diff is not evidence that the implementation is missing. If multiple plausible scopes would produce different summaries, ask one focused question.
   • Record repository, scope mode, base/head SHAs where applicable, and changed-file count. Staged work has no new commit SHA; identify the staged snapshot and current HEAD without implying it is committed.
   • Read relevant surrounding code, callers, and tests to understand behavior. Do not stage or commit files merely to generate this summary. Exclude unrelated changes and sensitive values.

4. Analyze and Compare:

   • Compare the selected code changes against the Acceptance Criteria defined in the Jira ticket.
   • Map every AC to evidence and a status: implemented and verified, implemented but unverified, partially implemented, not implemented in the inspected scope, or unknown. Distinguish an absent change from functionality already present in surrounding code.
   • Preserve prior AC status/history as historical evidence; explain changes in status rather than silently replacing them.
   • Identify the affected areas in the codebase (Configurations, Modules, Features, Components) and describe them in product terms, as the team template examples do: Modules are module names (for example Order), Features are on-screen feature names, Components are a screen or widget path (for example Worklist > Inpatients widget), and Configurations are config toggle names with the site they apply to. Leave file and class names out of the template.
   • Report checks actually run, their results, and checks not run. Code inspection alone does not establish runtime correctness or full acceptance.
   • For API work, describe the endpoint/method, relevant request fields, authorization, processing and source-data resolution, duplicate behavior, response statuses, and scope when supported by the code. Mark unknown contracts explicitly.

5. Summarize using Template:

   • Keep the headings and tables of the CR template below and add no other sections. Put each row's status, result, and a short scope in the table. Report the commands and logs behind them to the user in your reply, not in the comment:

   # Story & CR
   
   **Summary** - [Brief one-line summary of what was implemented, noting if it fully meets AC.]
   
   **Affected Areas** - [Comma-separated list of major areas impacted]
   
   | Summary                   | Screenshots |
   | :------------------------ | :---------- |
   | 1. [What the change does for this criterion, with status] | [Image or evidence status] |
   | 2. [What the change does for this criterion, with status] | [Image or evidence status] |
   
   | Affected Areas | Descriptions     |
   | :------------- | :--------------- |
   | Configurations | [Details or N/A] |
   | Modules        | [Details or N/A] |
   | Features       | [Details or N/A] |
   | Components     | [Details or N/A] |
   

   • Number the rows but do not write AC1 or AC2 labels. The team examples describe each criterion directly.
   • Atlassian Document Format (ADF) is the publishing format. The Markdown template defines content and order, not the literal body syntax. Build a JSON document with version: 1, type: "doc", and ordered content nodes.
     • Use heading and paragraph nodes for sections. Use table, tableRow, tableHeader, and tableCell nodes for both tables, with one numbered criterion per Summary table row.
     • Apply both strong and textColor marks to the level-1 Story & CR heading, using #36b37e.
     • Keep table-cell content in valid ADF block nodes. See ADF document structure, ADF table node, and ADF textColor mark.
   • Publish through Atlassian MCP with ADF: use the Atlassian MCP comment tool whose contentFormat accepts adf (for example addCommentToJiraIssue). Inspect its live schema first, set contentFormat: "adf", and pass the ADF document in the shape commentBody expects; when commentBody is a string, send the serialized JSON document.
     • Do not use a comment tool that offers only markdown or html (for example addOrEditJiraIssueComment) for this summary.
     • If no available Atlassian MCP comment tool accepts ADF, do not publish. Return the ADF draft and tell the user which tools were checked.
   • Write for the whole team (developers, BA, QA). A reader should understand each row without reading the code:
     • Describe each row from the user's side: what the user does and what they see, using screen names. Explain any technical term you cannot avoid.
     • Write each status in plain language, in the summary's language. In Thai use ทำแล้ว ทดสอบผ่าน, ทำแล้ว ทดสอบไม่ผ่าน, ทำแล้ว ยังไม่ได้ทดสอบ, ทำบางส่วน, มีอยู่เดิมก่อนการ์ดนี้, or ยังยืนยันไม่ได้. Use a tested status only when a check was actually run or reported, and always state the result. Add the scope in a few words, and the source when someone else ran it, for example ทดสอบผ่านบน UAT โดย QA (comment 170406). Never write a bare ทดสอบแล้ว. Reading the code is not a test.
     • Put a before and after screenshot pair in the Screenshots cell when both exist.
     • In the Features cell, add a ควรทดสอบซ้ำ: line naming the nearby screens or features the change can affect, found by checking the callers. Leave the line out when no callers were checked.
     • Mark behavior the ticket did not ask for with (เพิ่มนอกเกณฑ์) in the Features cell so BA and QA can confirm it.
     • Before posting, reread the comment and cut filler, repeated points, and wording that sounds machine-written.

6. Draft and Publish:

   • First CR summary on the ticket: add a brief line at the top stating that this is an AI-generated CR summary based on the inspected change scope.

   • A previous CR summary already exists: the new comment must reference the old one so readers can follow the update history:

     • Open with an update banner instead of the first-time line, e.g. > 🔄 Updated CR summary — supersedes the previous summary posted on 2026-08-19 (comment 400128). Link to the previous comment when possible: https://<site>.atlassian.net/browse/<TICKET>?focusedCommentId=<commentId>#comment-<commentId>.
     • Do not add a changes section. Update the tables in place. If the previous summary says something the current code contradicts, correct it in the table and name the correction in the banner line.
     • Carry forward still-valid information from the previous summary that the diff cannot regenerate (e.g., screenshots) — if they still apply, state so explicitly instead of silently dropping them.
     • Keep the same language as the previous summary unless the user asks for a different language.

   • Language and screenshots: for a first summary, use the language of the team template examples (Thai, with English product and UI names) unless the user or repository instructions say otherwise. Add an image when there is one: a screenshot, or for a change with no screen, test output, an API response, or a database record before and after. An image is not required on every row, but do not leave the cell empty. When an image is expected but not attached yet, write รอแนบภาพ and name what to attach, such as รอแนบภาพ: ผลรัน test. When no image is needed, write ไม่มีภาพ. Write ภาพเดิมใน comment <id> when the image is carried forward. Keep the pass or fail result in the Summary cell, and do not color this text.

   • Prepare the complete comment first. A request to summarize or review ends with a local draft unless publication was explicitly requested. If the user already asked to post it, continue without asking again. If publication is needed but not yet authorized, request approval only for the completed, reviewable draft.

   • Before publishing, confirm the issue and re-read relevant prior summaries to avoid duplicates or superseding a newer update. If the selected changes moved since analysis, refresh the evidence and draft first.

   • Preserve existing comments; this workflow creates a linked follow-up comment rather than deleting or overwriting history.

   • Publish the ADF comment to the verified issue through the Atlassian MCP comment tool selected above.

7. Verify the Result:

   • After publication, retrieve the created comment and verify its issue, body, and link. If the write result is uncertain, inspect existing comments before retrying to avoid duplicate posts.
   • Return the comment link and publication status, or label the result as a draft. Report inspection/test limitations explicitly; do not claim publication succeeded without evidence.