jira

JIRA Ticket Management

Interact with JIRA using the Atlassian CLI (acli).

Prerequisites

Before creating tickets, verify acli is installed and authenticated:

acli --version

If not installed or authenticated, direct the user to:

• Install: https://developer.atlassian.com/cloud/acli/guides/introduction
• Run acli --help for authentication setup

Finding the Project Key

1. Check the repo's AGENTS.md or CLAUDE.md for a jira_project_key or similar

2. If not found, ask the user for the project key

3. After the user provides it, add it to the project's CLAUDE.md for future reference:

   ## JIRA
   
   Project Key: PROJ
   

Creating Tickets

Always put a ticket under an appropriate Initiative. If there are no existing initiatives that make sense, stop and ask the user.

Use --from-json with ADF (Atlassian Document Format) for proper formatting:

cat > /tmp/ticket.json << 'EOF'
{
  "projectKey": "PROJECT_KEY",
  "type": "Story",
  "summary": "Implement Configuration Validation",
  "description": {
    "version": 1,
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "Description text here." }]
      },
      {
        "type": "heading",
        "attrs": { "level": 2 },
        "content": [{ "type": "text", "text": "Definition of Done" }]
      },
      {
        "type": "bulletList",
        "content": [
          { "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "Outcome 1" }] }] },
          { "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "Outcome 2" }] }] }
        ]
      }
    ]
  }
}
EOF
acli jira workitem create --from-json /tmp/ticket.json

Important: The --description flag only accepts plain text (no formatting). Use --from-json with ADF for headings, bullets, etc. Markdown and wiki syntax do NOT work.

ADF Quick Reference

// Paragraph
{ "type": "paragraph", "content": [{ "type": "text", "text": "..." }] }

// Heading (level 1-6)
{ "type": "heading", "attrs": { "level": 2 }, "content": [{ "type": "text", "text": "..." }] }

// Bullet list
{ "type": "bulletList", "content": [
  { "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "..." }] }] }
]}

// Bold text
{ "type": "text", "text": "...", "marks": [{ "type": "strong" }] }

Docs: https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/

Editing Tickets

Use --from-json with issues array:

cat > /tmp/edit.json << 'EOF'
{
  "issues": ["PROJ-123"],
  "description": { "version": 1, "type": "doc", "content": [...] }
}
EOF
acli jira workitem edit --from-json /tmp/edit.json --yes

Ticket Types

Type	Use For
Story	Code changes, new features
Task	Documentation, config, non-code work
Bug	Defects in existing functionality

Ticket Template

Title

• Imperative verb + specific object + context
• Under 60 characters
• Examples:
  • ✅ Implement Configuration Validation with Pydantic
  • ✅ Switch Auto Loader to File Notification Mode
  • ❌ Configuration (no verb)
  • ❌ URGENT: CRITICAL BUG (use Priority field instead)

Common verbs: Implement, Add, Switch, Remove, Update, Fix, Migrate, Refactor

Description

1-3 sentences covering what and why.

✅ Good:

Implement Pydantic models for config files to catch validation errors at startup. Currently getting silent failures on typos.

❌ Bad:

Add validation (no context)

Definition of Done

Bullet list of specific, measurable outcomes (not implementation steps).

✅ Good (outcomes):

• Config files validate on startup
• Invalid configs produce clear error with field name
• All existing configs pass validation
• Unit tests cover each config type

❌ Bad (implementation steps):

• Use Pydantic BaseModel
• Create schema for each file
• Add try/catch blocks

DoD guidelines:

• 3-7 items (if more, split the story)
• Outcome-focused, not prescriptive
• Include code, tests, and docs where relevant
• Specific enough to verify completion

Implementation Details (Optional)

Use for context that helps but doesn't belong in DoD:

• Documentation links
• Technical constraints
• Permission requirements
• Related tickets

✅ Good:

See Databricks docs: [link] Requires S3:PutBucketNotification permission Related: FOO-823

❌ Bad:

Step 1: Create the file. Step 2: Add imports...

Sizing Check

Before creating, verify the story fits one sprint. If the DoD has more than 7 items or the scope feels large, suggest splitting into multiple tickets.

Other Commands

Discover additional commands via:

acli jira --help
acli jira workitem --help