X Jira

Argument Parsing

Ticket Modes

Triage Modes

Global Flags

--json --quiet

Same behavior as x-slack: machine-readable JSON envelope, no prose. Agents should ALWAYS use this.

--fresh

Bypass the SWR cache and force a fresh API call. Use when accuracy matters (e.g., right before transitioning a ticket or after making changes).

Data Files

Shared (~/.claude/companies/{company}/data/):

Jira-specific (~/.claude/companies/{company}/data/jira/):

Policy file (~/.claude/policies/companies/{company}/jira-fields.yml):

• Custom field IDs (story points, sprint, etc.)
• Project-specific status exclusions
• See policies/jira-fields.yml.template for schema

Cache Design

Stale-While-Revalidate (SWR) Pattern

The cache stores ticket data with TTLs. Stale data is returned immediately while a background refresh updates the cache.

TTLs by data type:

Cache behavior:

1. Request for ticket KEY → check cache.json
2. If cached and within TTL → return immediately
3. If cached but past TTL → return stale data AND trigger refresh
4. If not cached → fetch from API, cache, return
5. --fresh flag → skip cache entirely, fetch from API, update cache

Comment staleness check:

• Cache stores comment_count alongside comment data
• On stale check: call mcp__atlassian-redacted__get_jira_issue with minimal fields to get comment count
• If count matches cached → extend TTL (no new comments)
• If count differs → full refresh

Eviction:

• Max 200 tickets in cache
• Tickets not accessed in 7 days are evicted
• LRU: when cache is full, evict least-recently-accessed entry

cache.json Schema

{
  "meta": { "last_eviction": "2026-01-01T00:00:00", "entry_count": 0 },
  "tickets": {
    "PROJ-123": {
      "fetched_at": "2026-01-01T00:00:00",
      "last_accessed": "2026-01-01T00:00:00",
      "data": {
        "key": "PROJ-123",
        "summary": "...",
        "status": "In Progress",
        "assignee_id": "...",
        "priority": "High",
        "components": [],
        "labels": [],
        "created": "2026-01-01",
        "updated": "2026-01-01"
      },
      "comments": {
        "fetched_at": "2026-01-01T00:00:00",
        "count": 0,
        "items": []
      }
    }
  },
  "users": {
    "Alice Smith": {
      "fetched_at": "2026-01-01T00:00:00",
      "account_id": "712020:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  },
  "field_schemas": {
    "fetched_at": null,
    "story_points": "customfield_10024"
  }
}

MCP Server Selection

Follow the PII protection policy (see ~/.claude/policies/pii-protection.md):

Ticket Modes

Mode: Find User

Resolve a name to Jira account ID. Checks people.yml cache first.

Input: find-user <name> — partial match, case-insensitive

1. Check people.yml for matching name/alias → return cached jira_id if found
2. If not in people.yml or jira_id is null: call mcp__atlassian-redacted__lookup_jira_account_id
3. If redacted MCP returns no results: warn user, try mcp__atlassian__lookupJiraAccountId (with PII warning)
4. On success: update people.yml with the discovered jira_id
5. Cache the lookup in cache.json under users

Mode: Get Ticket

Fetch a ticket with SWR cache.

Input: get-ticket <KEY> (e.g., get-ticket PROJ-123)

• Validate KEY format: ^[a-zA-Z]{2,12}-\d{1,7}$, normalize to uppercase
• With --fresh: skip cache, fetch via mcp__atlassian-redacted__get_jira_issue, update cache
• Check cache.json → if within TTL, serve from cache
• If past TTL: use mcp__atlassian-redacted__get_ticket_summary for lightweight staleness check
  • If status/assignee/updated unchanged → extend TTL, serve cached
  • If changed → full refresh via mcp__atlassian-redacted__get_jira_issue
• For comments specifically: use mcp__atlassian-redacted__check_comments_updated with cached comment count
  • If unchanged → extend comment TTL
  • If changed → full refresh
• Update cache with any fetched data

Mode: Create Ticket

Create a new Jira issue.

Input: create-ticket <project> <type> <summary> — or --json with full field body

• Validate project key format
• Call mcp__atlassian-redacted__create_jira_issue
• On success: add to ticket-tracker.yml if it matches monitored criteria
• Return: issue key, URL, status

Mode: Search

Search Jira via JQL or keywords.

Input: search <query>

• If query contains JQL operators (=, IN, ORDER BY, etc.) → pass as raw JQL
• Otherwise → construct JQL: text ~ "query" ORDER BY updated DESC
• Call mcp__atlassian-redacted__search_jira_issues
• Cache each returned ticket in cache.json
• Return: list of matching tickets with key, summary, status, assignee

Mode: Edit Ticket

Update a field on a ticket.

Input: edit-ticket <KEY> <field> <value>

• Validate KEY format
• Call mcp__atlassian-redacted__edit_jira_issue
• Invalidate the ticket's cache entry (force refresh on next access)

Mode: Transition

Move a ticket to a new status.

Input: transition <KEY> <status>

• Validate KEY format
• Call mcp__atlassian-redacted__get_jira_transitions to get available transitions
• Match <status> to transition name (fuzzy, case-insensitive)
• If ambiguous: return candidates, ask for disambiguation
• Call mcp__atlassian-redacted__transition_jira_issue
• Invalidate cache

Mode: Comment

Add a comment to a ticket.

Input: comment <KEY> <text>

• Validate KEY format, text max 4000 chars
• Preview before sending (same pattern as x-slack reply mode)
• Call mcp__atlassian-redacted__add_jira_comment
• Invalidate comment cache for this ticket

Triage Modes

Mode: Mentions

Full @mentions scan with WSJF prioritization, smart batching, delta tracking, and snapshot management.

Input: mentions [days] — lookback days, default 14

Full workflow: See mentions-workflow.md for the complete 10-step workflow including:

• Parallel JQL queries (assigned, reported, watched, comment-text search)
• Smart batching: Tier 1 (sprint + high priority), Tier 2 (remaining assigned), Tier 3 (watched)
• ADF parsing for @mention node detection
• WSJF scoring: (Priority + Staleness + Sprint) / Story Points
• Delta tracking via snapshots in data/mentions/
• Categorized output: Needs Response (Overdue/Stale/Fresh), Already Responded, Recent Activity, Stale Alerts

Quick summary (what this mode does at a high level):

1. Get owner's Jira account ID from people.yml
2. Run 5 parallel JQL queries to find candidate tickets
3. Smart-batch comment fetches (prioritize sprint/high-priority)
4. Scan ADF for @mention nodes matching owner
5. Score each ticket with WSJF
6. Present dashboard + categorized results sorted by WSJF
7. Save snapshot for delta tracking on next run

Mode: Triage

Scan a Jira project for items needing attention.

Input: triage [project] — default: scan all configured projects

1. Read classification-rules.yml for Jira-specific classification rules
2. Read categories.yml for category definitions
3. Read people.yml for routing
4. JQL queries:
   • Unassigned tickets in last 7 days
   • Tickets assigned to owner with no activity in 3 days
   • Tickets in "In Progress" for > 5 days without updates
5. Classify each ticket using classification-rules.yml
6. Route using people.yml topics
7. Update ticket-tracker.yml with findings
8. Present results grouped by priority

Mode: Help

Same pattern as x-slack help. Lists all modes with descriptions, args, examples.

Input: help [mode]

JSON Output Format

Same envelope as x-slack:

{
  "mode": "get-ticket|search|find-user|...",
  "ok": true,
  "count": 1,
  "results": [ ... ],
  "errors": [],
  "cache_hit": true,
  "cache_age_seconds": 245
}

Extra fields for cache-aware modes: cache_hit (bool), cache_age_seconds (int, null if miss).

Agent Spawning

Ticket Scanner Agent

Spawn: Agent tool, subagent_type: general-purpose
Task: Search Jira for [query]. For each result, get ticket details.
      Return: list of {key, summary, status, assignee, priority, updated}

Triage Agent

Same pattern as x-slack agent — see agent-prompt.md

Cross-Skill Integration

Other skills call x-jira modes directly with --json --quiet:

/x-bug-fix investigating PROJ-123

1. /x-jira get-ticket PROJ-123 --json --quiet
   → Cached ticket data (or fresh if stale)
2. /x-jira search "auth failure" --json --quiet
   → Related tickets
3. /x-jira find-user Alice --json --quiet
   → Jira account ID from people.yml cache
4. After fixing: /x-jira transition PROJ-123 "In Review" --json --quiet
5. /x-jira comment PROJ-123 "Fixed in PR #42" --json --quiet

/x-done closing out work

1. /x-jira get-ticket PROJ-123 --fresh --json --quiet
   → Fresh data before final status check
2. /x-jira transition PROJ-123 "Done" --json --quiet

Agent Discovery

Other agents call /x-jira help --json --quiet to discover modes at runtime.