mbarbieri/jira-tool

Using the Jira Tool

Overview

Core principle: When users mention Jira issues or provide Jira URLs, immediately run jira <url-or-key>. Don't explore code, don't explain internals, just use the tool.

The jira tool is a Python CLI that fetches Jira Cloud issues (description, comments, metadata) and outputs AI-optimized markdown to stdout.

IMMEDIATE ACTION REQUIRED:

1. Run tool: jira "<url or key>"
2. Display output

That's it. No analysis, no explanation, no code reading. If jira tool doesn't exists, just tell the user to install it and make use it's in the PATH.

When to Use

Use jira tool when:

• User provides Jira URL: https://*.atlassian.net/browse/KEY-123
• User mentions issue key: "check PLATFORM-5678"
• User asks for issue context: "what does SP-1234 say?"
• User asks to implement from a Jira ticket

Don't use when:

• Jira URLs are just reference links (not requesting data)
• User wants to CREATE Jira issues (tool is read-only)

Quick Reference

| Task | Command | |------|---------| | Fetch by issue key | jira PROJ-123 | | Fetch by URL | jira "https://company.atlassian.net/browse/PROJ-123" | | Save to file | jira PROJ-123 > context.md |

Prerequisites Check

Before using the tool, verify:

# 1. Configuration exists
ls .env

If missing:

• .env not found → Tell user to create it with ATLASSIAN_EMAIL, ATLASSIAN_TOKEN, ATLASSIAN_DOMAIN
• Tool not found → Not a jira-enabled repository

Usage Pattern

Basic Flow

# Direct issue key
jira SP-1234

# Full URL (with or without query params)
jira "https://company.atlassian.net/browse/TICKET-123"
jira "https://company.atlassian.net/browse/TICKET-123?filter=all"

Integration Workflows

Gather context before implementation:

# Fetch requirements
jira "https://company.atlassian.net/browse/FEATURE-456" > requirements.md

# Read and implement
cat requirements.md
# [implement based on requirements]

Read issue during debugging:

# Fetch bug report
jira BUG-789

# Use output to understand the issue
# [debug based on description and comments]

Output Format

The tool outputs markdown with:

• Metadata: Issue key, status, priority, assignee, reporter, labels, timestamps
• Description: Original issue description (Jira markup → Markdown)
• Comments: All comments with author and timestamp

Structure:

# [KEY-123] Issue Title

**Issue Key:** KEY-123
**Status:** In Progress
**Priority:** High
...

---

## Original Description

[Description content in markdown]

---

## Comments (N total)

### Comment by Author on YYYY-MM-DD HH:MM UTC
[Comment content]

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | ATLASSIAN_EMAIL not found | Missing .env | Create .env with required vars | | Invalid credentials | Wrong API token | Check ATLASSIAN_TOKEN in .env | | Issue KEY-123 not found | No access or doesn't exist | Verify key and permissions | | Failed to connect to Jira | Network or domain issue | Check ATLASSIAN_DOMAIN in .env | | Invalid issue key | Wrong format | Use format: PROJ-123 |

All errors go to stderr - stdout remains clean for piping.

Common Mistakes

❌ Exploring code instead of using tool

# DON'T: Spend time reading jira.py source
Read jira to understand API calls...

# DO: Just use it
jira PROJ-123

❌ Using WebFetch for Jira URLs

# DON'T: Fetch HTML page
WebFetch https://company.atlassian.net/browse/PROJ-123

# DO: Use jira tool for structured data
jira PROJ-123

❌ Forgetting to quote URLs

# DON'T: Breaks on query params
jira https://site.atlassian.net/browse/KEY-123?filter=all

# DO: Quote URLs
jira "https://site.atlassian.net/browse/KEY-123?filter=all"