Jira Workitem Comment
Add comments to Jira tickets using the acli CLI with support for both simple text and rich Atlassian Document Format (ADF).
Prerequisites
aclimust be installed and authenticated (acli jira auth)
Implementation
Step 1: Verify ACLi Setup
Before proceeding, verify that acli is installed and authenticated by invoking the acli-setup-check skill:
/acli-setup-check
If the setup check fails, stop execution and guide the user to fix the issue.
Step 2: Determine Ticket Key and Comment Content
-
Ticket Key:
- If provided by user, use it
- Otherwise, search conversation history for ticket references matching the pattern
[A-Z]+-\d+ - If not found, ask: "Which ticket should I comment on?"
-
Comment Content:
- If the user provides comment text, use it
- If the user wants to document a conversation or finding, infer the content from context
- If unclear, ask: "What would you like to say in the comment?"
-
Comment Type:
- Simple text: Default for straightforward comments
- Rich format: Use when comment includes code blocks, lists, or structured content
Step 3a: Add Simple Text Comment (Default)
For plain text comments, write the comment text to a temporary file and use acli to create the comment:
# Validate ticket key format (PROJECT-NUMBER)
TICKET_KEY="<ticket-key-from-step-2>"
if [[ ! "$TICKET_KEY" =~ ^[A-Z]+-[0-9]+$ ]]; then
echo "Error: Invalid ticket key format. Expected PROJECT-NUMBER (e.g., AIPCC-1234)"
exit 1
fi
# Write comment to temp file (uses system temp directory)
TMPFILE=$(mktemp -t acli-comment-XXXX.txt)
cat > "$TMPFILE" << 'EOF'
<comment text goes here>
EOF
# Create the comment with validated ticket key
acli jira workitem comment create --key "$TICKET_KEY" --body-file "$TMPFILE"
# Clean up
rm -f "$TMPFILE"
Step 3b: Add Rich ADF Comment (For Formatted Content)
For comments that need rich formatting (code blocks, lists, mentions, links), construct an ADF JSON structure.
ADF Structure Examples
Basic text with formatting:
{
"version": 1,
"type": "doc",
"content": [
{
"type": "paragraph",
"content": [
{"type": "text", "text": "This is "},
{"type": "text", "text": "bold text", "marks": [{"type": "strong"}]},
{"type": "text", "text": " and "},
{"type": "text", "text": "italic text", "marks": [{"type": "em"}]}
]
}
]
}
Code block:
{
"version": 1,
"type": "doc",
"content": [
{
"type": "paragraph",
"content": [
{"type": "text", "text": "Here's the fix:"}
]
},
{
"type": "codeBlock",
"attrs": {"language": "python"},
"content": [
{
"type": "text",
"text": "def hello():\n print('Hello, world!')"
}
]
}
]
}
Bullet list:
{
"version": 1,
"type": "doc",
"content": [
{
"type": "bulletList",
"content": [
{
"type": "listItem",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "First item"}]
}
]
},
{
"type": "listItem",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Second item"}]
}
]
}
]
}
]
}
Link:
{
"version": 1,
"type": "doc",
"content": [
{
"type": "paragraph",
"content": [
{"type": "text", "text": "See "},
{
"type": "text",
"text": "the documentation",
"marks": [
{
"type": "link",
"attrs": {"href": "https://example.com/docs"}
}
]
}
]
}
]
}
User mention:
{
"version": 1,
"type": "doc",
"content": [
{
"type": "paragraph",
"content": [
{
"type": "mention",
"attrs": {
"id": "557058:12345678-abcd-1234-abcd-123456789012",
"text": "@code-samurai"
}
},
{"type": "text", "text": " please review"}
]
}
]
}
Write the ADF JSON to a temporary file and create the comment:
# Validate ticket key format (PROJECT-NUMBER)
TICKET_KEY="<ticket-key-from-step-2>"
if [[ ! "$TICKET_KEY" =~ ^[A-Z]+-[0-9]+$ ]]; then
echo "Error: Invalid ticket key format. Expected PROJECT-NUMBER (e.g., AIPCC-1234)"
exit 1
fi
# Write ADF JSON to temp file (uses system temp directory)
TMPFILE=$(mktemp -t acli-comment-XXXX.json)
cat > "$TMPFILE" << 'EOF'
{
"version": 1,
"type": "doc",
"content": [...]
}
EOF
# Create comment with ADF and validated ticket key
acli jira workitem comment create --key "$TICKET_KEY" --body-file "$TMPFILE"
# Clean up
rm -f "$TMPFILE"
Step 4: Confirm Comment Content (Optional)
For important or lengthy comments, show a preview to the user:
I'll add this comment to <TICKET-KEY>:
---
<comment preview>
---
Should I proceed?
Wait for confirmation before creating the comment.
Step 5: Report Success
After successfully creating the comment, report to the user:
Comment added to <TICKET-KEY>
View: https://redhat.atlassian.net/browse/<TICKET-KEY>
When to Use Rich Formatting
Use ADF (Step 3b) when the comment includes:
- Code snippets or blocks: Error messages, logs, code examples
- Structured lists: Action items, requirements, test cases
- Links: References to PRs, documentation, external resources
- Mentions: Tagging specific users for attention
- Mixed formatting: Bold headers, italic emphasis, inline code
Use simple text (Step 3a) for:
- Brief updates or status notes
- Simple questions or answers
- Acknowledgments or confirmations
Error Handling
- acli not found: Delegate to
acli-setup-checkskill - Authentication failure: Delegate to
acli-setup-checkskill - Invalid ticket key: Verify format and ticket existence
- Permission denied: Check user has permission to comment on the ticket
- Invalid ADF: Verify JSON structure matches ADF schema
- Comment too long: Jira has a 32,767 character limit per comment; suggest breaking into multiple comments
Examples
Simple Text Comment
User: Add a comment to AIPCC-1234 saying the fix is ready for review
Assistant: [Creates simple text comment]
Comment added to AIPCC-1234
View: https://redhat.atlassian.net/browse/AIPCC-1234
Code Block Comment
User: Comment on AIPCC-5678 with this error message: [paste error]
Assistant: [Creates ADF comment with code block]
Comment added to AIPCC-5678 with formatted code block
View: https://redhat.atlassian.net/browse/AIPCC-5678
Structured Update
User: Add a status update to AIPCC-910 with these action items:
- Fix merged to main
- QA testing in progress
- Deployment scheduled for Friday
Assistant: [Creates ADF comment with bullet list]
Comment added to AIPCC-910
View: https://redhat.atlassian.net/browse/AIPCC-910