Jira Read — Execution Rules

Quickly read downloaded Jira data from local cache — no network access required.

Configuration

Set the cache directory environment variable before use (recommend adding to .zshrc / .bashrc):

export JIRA_CACHE_DIR="$HOME/.cache/jira"

Defaults to ~/.cache/jira/ if not set.

Triggers & Parameters

Primary trigger: jira-read [JIRA-ID] — case-insensitive (auto-converted to uppercase)

Storage Paths

• Main file: $JIRA_CACHE_DIR/{JIRA-ID}.md
• Field mapping cache: $JIRA_CACHE_DIR/.field-mapping.json

On first use, automatically calls jira_search_fields to build field ID mapping; subsequent reads use the cache directly. --force refreshes the mapping.

Execution Flow

Step 1: Parse Jira ID

Extract (regex: ([A-Za-z]+-\d+)) and convert to uppercase, build the local file path.

Step 2: Check File Existence

File exists: continue to step 3

File does not exist:

• Resolve the PAT via the credential chain (below) before any API call
• Default: call jira_get_issue(issue_key="{JIRA-ID}", fields="*all", comment_limit=50) → on success, format and save, then continue; on failure, classify per Error Handling
• --no-download: prompt only, don't auto-download
• --live: skip local check, fetch from API and update cache
• --force: fetch from API and overwrite local cache

Step 3: Read, Parse, Output

Read Markdown → parse YAML front matter and body → output as structured Markdown.

Parsed fields: jira_id, title, priority, status, reporter, assignee, created_at, updated_at, downloaded_at, source_url; body contains issue description, reproduction steps, expected/actual results, comment history.

Attachment handling: Never read attachment content into the Agent context. If the issue has attachments (logs, screenshots), note them at the end of the output. When the user needs the actual attachment (logs), follow the "Attachment Download" section below.

Output format examples for each scenario: see reference.md

Credential resolution (before any live fetch)

Run this chain before MCP/jira_get_issue, --live/--force, and attachment download. mcp-atlassian is an optional way to populate step 1; it is not required.

1. Env JIRA_PERSONAL_TOKEN (canonical)
2. Else env JIRA_PAT (alias; copy into JIRA_PERSONAL_TOKEN for the rest of the session)
3. Else file ~/.config/jira-certs/jira-pat.txt (Windows: %USERPROFILE%\.config\jira-certs\jira-pat.txt) — first line, trimmed, single-line secret
4. Else ask the user once for a PAT and ask whether to write it to that file. Do not live-fetch until a token exists.

After env or the file has a token: do not paste the PAT into chat, argv, or command previews; do not echo it in replies or logs; do not cat the file into the conversation. Scripts read env or the file themselves.

Do not teach a manual curl that interpolates the PAT (no “equivalent curl from the Authentication table”). That fallback is forbidden (supersedes the older attachment-download delta if it is still open).

Attachment Download

Always download attachments to local disk via the skill scripts — never read attachment content into the Agent context. To inspect log contents, extract only the relevant lines with grep/head/tail.

Authentication (Internal Jira)

Credentials (recipe field): store the PAT as one line in ~/.config/jira-certs/jira-pat.txt (same directory as the mTLS pair; not in any git repo). Format: single-line secret, no quotes. Rotation: replace the file contents and any exported env, then retry. mcp-atlassian may inject JIRA_PERSONAL_TOKEN instead of the file.

Attachment URL

Take it directly from attachment[].url returned by jira_get_issue, e.g.: https://jira.example.com/secure/attachment/{attachmentId}/{filename}

Download Script

Probe curl -V first. If the output contains Schannel (typical Windows) or PEM --cert/--key is unavailable, MUST use the node sidecar. Otherwise the bash script is allowed.

# Node (Windows / Schannel curl)
node scripts/download_jira_attachments.mjs 100001 app-log-1700000000000.zip /tmp/logs/PROJ-1234.zip

# Bash + OpenSSL curl (PEM --cert/--key)
scripts/download_jira_attachments.sh 100001 app-log-1700000000000.zip /tmp/logs/PROJ-1234.zip

Both resolve the PAT from the credential chain (Bearer, Basic fallback). Override cert paths with JIRA_CLIENT_CERT / JIRA_CLIENT_KEY. Set JIRA_URL (e.g. https://jira.example.com). Never put the PAT on the command line.

Download & Archive Flow

1. Resolve credentials (chain above), then call jira_get_issue(issue_key=..., fields="summary,description,attachment,status,priority") for attachment[].id / filename / url
2. Download to a temp dir via the selected script — download 1 first to verify auth, then batch
3. unzip -l to preview the zip structure; confirm it is flat before extracting
4. Archive into the project at issues/{type}/jira-bug/{JIRA-ID}-app-log/, writing {JIRA-ID}.md to record the ticket info + attachment list

Download result report format: see reference.md § 7

Cache Freshness Prompts

Error Handling