# JIRA Essentials

Core MCP operations and essential guidance for JIRA integration. This file contains only the most critical information needed for JIRA operations.

## MCP Tools Overview

### Essential JIRA Operations

The following MCP tools provide core JIRA functionality:

**Issue Management:**

- `mcp__mcp-atlassian__jira_search` - Find issues using JQL
- `mcp__mcp-atlassian__jira_get_issue` - Get detailed issue information
- `mcp__mcp-atlassian__jira_create_issue` - Create new issues
- `mcp__mcp-atlassian__jira_update_issue` - Update existing issues
- `mcp__mcp-atlassian__jira_transition_issue` - Change issue status

**Field Discovery:**

- `mcp__mcp-atlassian__jira_search_fields` - Auto-detect custom fields
- `mcp__mcp-atlassian__jira_get_transitions` - Get available status changes

**Batch Operations:**

- `mcp__mcp-atlassian__jira_batch_create_issues` - Create multiple issues
- `mcp__mcp-atlassian__jira_link_to_epic` - Link issues to epics

## MCP Availability Detection

### Intelligent Setup Validation

Before any JIRA operations, verify tools are available:

```
Check for tools with prefix "mcp__mcp-atlassian__"
→ Available: Proceed with operations
→ Not Available: Provide setup guidance
→ Partial: Guide through configuration
```

**Setup Guidance When MCP Not Available:**

1. Install MCP CLI: `npm install -g @modelcontextprotocol/cli`
2. Install Atlassian tools: `mcp install @modelcontextprotocol/atlassian`
3. Configure JIRA connection (URL, API token, permissions)
4. Restart IDE/environment to load new tools
5. Test with simple query

## Field Mapping Intelligence

### Semantic Field Discovery

Use intelligent analysis to find custom fields:

**Discovery Process:**

1. Search for keywords: "epic" → Epic Link field, "sprint" → Sprint field
2. Analyze field usage patterns in existing issues
3. Match field purposes rather than exact names
4. Validate mappings through test operations

**Common Field Patterns:**

- Epic Link: Usually `customfield_10014` or similar
- Sprint: Usually `customfield_10020` or similar
- Story Points: Usually `customfield_10016` or similar

**Fallback Strategy:**

- Try semantic search for field purposes
- Check field configuration endpoints
- Use partial matching for field names
- Provide manual override options

## Error Handling Essentials

### Common Issues & Solutions

**Authentication Errors:**

- Verify API token is valid and not expired
- Check user has project permissions
- Confirm JIRA instance URL is correct
- Test with simple read-only operation first

**Field Not Found:**

- Run field discovery with relevant keywords
- Check field visibility permissions
- Verify field exists in project configuration
- Use exact field IDs when names fail

**Permission Denied:**

- Confirm user has appropriate project role
- Check issue type permissions and restrictions
- Verify custom field visibility settings
- Review workflow restrictions for transitions

**Rate Limiting:**

- Implement exponential backoff for retries
- Batch operations when possible
- Cache frequently accessed data
- Monitor API usage patterns

## Analysis Intelligence

### Adaptive Analysis Patterns

**Attachment Analysis:**

- Auto-detect file types (logs, screenshots, traces, configs)
- Extract relevant information based on content patterns
- Correlate evidence across multiple attachments
- Focus on actionable insights over raw data

**Pattern Recognition:**

- Identify error patterns and timing correlations
- Recognize environment-specific issues
- Detect user behavior patterns leading to problems
- Find relationships between symptoms and root causes

**Context Adaptation:**

- Scale analysis depth to match issue complexity
- Adapt technical detail to audience (dev vs business)
- Include relevant evidence while filtering noise
- Generate appropriate recommendations based on findings

## Integration Essentials

### Core Integration Patterns

**Story to Issue Mapping:**

1. Extract essential story information
2. Map to appropriate JIRA fields
3. Generate suitable issue format
4. Link to original story location
5. Maintain bidirectional references

**Status Synchronization:**

1. Map BMAD statuses to JIRA workflow
2. Handle workflow transitions appropriately
3. Resolve conflicts using intelligent rules
4. Update both systems consistently

**Evidence Correlation:**

1. Connect code changes to JIRA issues
2. Link bugs to related stories and epics
3. Associate test results with development work
4. Maintain traceability across tools

## Natural Language Processing

### Request Interpretation

**Sync Requests:**

- Identify scope (single story, epic, project)
- Determine sync mode (light, full, status-only)
- Assess urgency and validation needs
- Choose appropriate conflict resolution

**Analysis Requests:**

- Understand investigation type (bug, performance, security)
- Determine analysis depth required
- Identify relevant evidence sources
- Adapt output format to context

**Quality Requests:**

- Assess readiness level needed
- Understand risk tolerance
- Identify relevant quality dimensions
- Generate appropriate validation approach

This essentials guide provides the core knowledge needed for JIRA integration while relying on LLM intelligence for adaptive behavior, complex analysis, and contextual decision-making.