Compare the JIRA ticket associated with the current branch against the actual changes made, and propose updates to keep the ticket accurate. Edits the description for missing information, adds comments for unrelated changes or implementation decisions, or both.
Usage:
/update-jira-ticket - Analyze branch changes and propose JIRA ticket updates
Instructions:
-
Check prerequisites:
- Atlassian CLI (
acli): Run acli auth status to check if the CLI is installed and authenticated.
- If the command is not found, display the following message and STOP:
- If the command fails with an authentication error, display the following message and STOP:
-
Extract the JIRA ID from the current branch name:
- Run
git branch --show-current to get the current branch name
- Extract the JIRA ID by matching the pattern
[A-Z][A-Z0-9]+-[0-9]+ (e.g., PROJ-123, AB-1, MYAPP-4567)
- The JIRA ID can appear anywhere in the branch name (e.g.,
fix/PROJ-123, feat/PROJ-123, PROJ-123-some-description)
- The match should be case-insensitive — normalize the extracted ID to uppercase for the JIRA API lookup
- If no JIRA ID is found, display the following message and STOP:
-
Fetch the JIRA ticket:
- Use the Atlassian CLI to retrieve the issue by its JIRA ID:
- Parse all available fields: summary, description, issue type, priority, comments, acceptance criteria, custom fields, etc.
- Store the original description for comparison — this is the baseline
- If the fetch fails, display the error and STOP
-
Determine the base branch:
- Check if a
.agent file exists in the current directory
- If it exists, read it and look for a
baseBranch=<value> line to extract the base branch
- If no
.agent file or no baseBranch key, default to main
-
Analyze the branch changes:
- Run
git log <base-branch>..HEAD --oneline to get the commit history on this branch
- Run
git diff <base-branch>...HEAD --stat to get a summary of files changed
- Run
git diff <base-branch>...HEAD to get the full diff
- Read key modified files to understand the nature of the changes
- Build a comprehensive understanding of:
- What was implemented — new features, bug fixes, refactors, etc.
- How it was implemented — technical approach, patterns used, key decisions
- What was changed beyond the original scope — any additions, adjustments, or deviations from the ticket description
-
Compare changes to the ticket description:
For each significant change or aspect of the implementation, categorize it into one of three types:
a) Missing from description — EDIT the description:
- Information that should have been in the ticket but wasn't (e.g., missing acceptance criteria that were implemented, undocumented requirements discovered during implementation, scope that was implicit but should be explicit)
- The description should be edited to include this information for documentation and tracking
b) Unrelated to the ticket — ADD a comment:
- Changes that were made alongside the ticket work but aren't part of the ticket's scope (e.g., opportunistic refactors, small fixes in adjacent code, dependency updates)
- These should be documented as comments so the ticket history captures what happened, without polluting the description
c) Implementation decision — EDIT the description AND ADD a comment:
- Changes where a deliberate technical or product decision was made that affects the ticket (e.g., choosing approach A over approach B, adjusting acceptance criteria based on technical constraints, scope adjustments agreed during implementation)
- The description should be updated to reflect the final state, and a comment should explain the reasoning behind the decision
Skip silently any changes that are:
- Already accurately reflected in the current description
- Trivial implementation details that don't affect the ticket's documentation value (e.g., variable names, minor formatting)
-
Prepare the list of proposed edits:
Present all proposed changes as a numbered list, grouped by action type:
If there are no proposed changes (the ticket is already accurate), display:
And STOP.
-
Get developer confirmation:
Use AskUserQuestion to ask the developer to review and approve the proposed updates:
- "Apply all" — apply all proposed edits and comments
- "Let me choose" — the developer will specify which items to apply (by number)
- "Skip" — cancel, don't update the ticket
If "Let me choose":
- Use
AskUserQuestion to ask which item numbers to apply (e.g., "1, 3, 4")
- Only apply the selected items
-
Apply the approved updates:
a) Description edits:
- Read the current ticket description
- Apply all approved description edits, integrating them naturally into the existing description structure
- Preserve the original description's tone, formatting, and structure — don't rewrite sections that aren't being updated
- Write the description as an ADF (Atlassian Document Format) JSON payload and use
--from-json to update:
The JSON file must contain the full edit payload with the description as an ADF object (see ADF Format Reference below).
- If the update fails, show the error and provide the proposed description as copyable text
b) Comments:
- For each approved comment, use the Atlassian CLI:
- Each comment should be self-contained and clearly explain the context
- Prefix implementation decision comments with "Implementation note:" for clarity
- If a comment fails to post, show the error and provide the comment text as copyable text
-
Show results:
Display a summary of what was applied:
-
Handle edge cases:
- If the ticket description is empty, all implementation details count as "missing from description" — propose a complete description based on the changes
- If there are no commits on the branch yet, display "No changes found on this branch compared to ." and STOP
- If the diff is too large to analyze in full, focus on the most significant changes (new files, large modifications) and note that some minor changes were not reviewed
- If the JIRA update fails partially (e.g., description updated but a comment failed), report what succeeded and what failed
- If the branch has changes from multiple tickets (e.g., cherry-picks), only propose updates for the ticket matching the branch name
JIRA does not render Markdown. Descriptions must use Atlassian Document Format (ADF) — a JSON-based document format. The --description-file flag treats file content as a plain text string, so it cannot be used for rich descriptions. Use --from-json instead.
Important: --from-json expects a structured JSON file with the full edit payload. The description field must be an ADF object, not a string. You can run acli jira workitem edit --generate-json to see the expected schema.
Edit payload format (--from-json):
Common ADF node types:
| Markdown | ADF type | Notes |
|---|
## Heading | heading with attrs.level | Levels 1–6 |
| Plain text | paragraph with text children | |
**bold** | text with marks: [{"type": "strong"}] | |
*italic* | text with marks: [{"type": "em"}] | |
- item | bulletList > listItem > paragraph | |
1. item | orderedList > listItem > paragraph | |
- [ ] task | taskList > taskItem (state: TODO/DONE) | |
`code` | text with marks: [{"type": "code"}] | Inline code |
| Code block | codeBlock with attrs.language | |
--- | rule | Horizontal rule |
[link](url) | text with marks: [{"type": "link", "attrs": {"href": "url"}}] | |