home / skills / bitsoex / bitso-java / jira-integration

jira-integration skill

safe

This skill creates and manages Jira tickets, discovers projects, searches existing issues, and links work across branches and PRs for efficient remediation.

npx playbooks add skill bitsoex/bitso-java --skill jira-integration

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

5.0 KB

---
name: jira-integration
description: >
  Create and manage Jira tickets with severity-based processing. Includes
  project discovery, ticket search, and branch naming.
compatibility: All repositories with Jira integration
metadata:
  version: "1.0.0"
  category: workflow
  tags:
    - jira
    - tickets
    - tracking
    - severity-processing
  triggers:
    - on-demand
  uses:
    - pr-workflow
---

# Jira Integration

Best practices for AI agents to create and manage Jira tickets when performing automated work like fixing vulnerabilities, resolving SonarQube issues, or improving test coverage.

## Core Principles

1. **Create Ticket Before Work** - Always create/find a Jira ticket before starting
2. **Discover Project Key** - Never hardcode project keys
3. **Search Before Creating** - Check for existing tickets first
4. **Severity-Based Processing** - Process issues one severity level at a time
5. **Link Everything** - Connect Jira → Branch → Commits → PR

## Skill Contents

### Sections

- [Core Principles](#core-principles) (L25-L32)
- [Workflow Overview](#workflow-overview) (L57-L66)
- [Quick Reference](#quick-reference) (L67-L101)
- [References](#references) (L102-L111)
- [Severity-Based Processing](#severity-based-processing) (L112-L128)
- [Best Practices](#best-practices) (L129-L136)
- [Skill Dependencies](#skill-dependencies) (L137-L142)
- [Related](#related) (L143-L146)

### Available Resources

**📚 references/** - Detailed documentation
- [branch naming](references/branch-naming.md)
- [project discovery](references/project-discovery.md)
- [severity processing](references/severity-processing.md)
- [ticket creation](references/ticket-creation.md)
- [ticket search](references/ticket-search.md)

---

## Workflow Overview

| Step | Description | Reference |
|------|-------------|-----------|
| **0. Discover** | Find user's Jira project key | `references/project-discovery.md` |
| **1. Search** | Check for existing open tickets | `references/ticket-search.md` |
| **2. Create** | Create ticket if none exists | `references/ticket-creation.md` |
| **3. Branch** | Create branch with Jira key | `references/branch-naming.md` |
| **4. Process** | Fix by severity level | `references/severity-processing.md` |

## Quick Reference

### Emoji Conventions

| Work Type | Emoji | Example |
|-----------|-------|---------|
| AI-assisted (all) | 🤖 | Required in ALL AI commits/PRs |
| Security/Vulnerability | 🛡️ | `🤖 🛡️ fix(security): resolve critical CVE` |
| Code Quality/SonarQube | ✅ | `🤖 ✅ fix(quality): resolve BLOCKER issues` |
| Test Coverage | 🧪 | `🤖 🧪 test: improve coverage` |
| Dependency Updates | 📦 | `🤖 📦 chore(deps): update Spring Boot` |
| Documentation | 📝 | `🤖 📝 docs: update API documentation` |
| Performance | ⚡ | `🤖 ⚡ perf: optimize queries` |
| Refactoring | ♻️ | `🤖 ♻️ refactor: simplify error handling` |

### Ticket Summary Format

```text
🤖🛡️ Fix [SEVERITY] Dependabot vulnerabilities in [repo-name]
🤖✅ Resolve [SEVERITY] SonarQube issues in [repo-name]
🤖🧪 Improve test coverage for [module/class]
🤖📦 Update [dependency] to [version]
```

### Branch Naming

```text
{type}/{JIRA-KEY}-{short-description}
```

Examples:
- `fix/PROJ-123-critical-vulnerabilities`
- `fix/PROJ-456-blocker-sonar-issues`
- `test/PROJ-789-coverage-payment-service`

## References

| Reference | Content |
|-----------|---------|
| `references/project-discovery.md` | How to discover user's Jira project key |
| `references/ticket-search.md` | JQL queries to find existing tickets |
| `references/ticket-creation.md` | Create tickets with proper format |
| `references/branch-naming.md` | Branch naming with Jira keys |
| `references/severity-processing.md` | Process by severity level |

## Severity-Based Processing

### Vulnerability Severity Order

1. **CRITICAL** - Fix first
2. **HIGH** - Only after no CRITICAL remain
3. **MEDIUM/MODERATE** - Only after no HIGH remain
4. **LOW** - Only after no MEDIUM remain

### SonarQube Severity Order

1. **BLOCKER** - Fix first
2. **CRITICAL** - Only after no BLOCKER remain
3. **MAJOR** - Only after no CRITICAL remain
4. **MINOR** - Only after no MAJOR remain
5. **INFO** - Only after no MINOR remain

## Best Practices

1. **One severity per PR** - Keep PRs focused and reviewable
2. **Batch related fixes** - Group similar issues in one commit
3. **Clear descriptions** - Document what was fixed and why
4. **Link everything** - Jira ticket ↔ Branch ↔ Commits ↔ PR
5. **Update ticket status** - Move ticket through workflow as work progresses

## Skill Dependencies

| Skill | Purpose |
|-------|---------|
| `pr-workflow` | PR creation, commit formats, GitHub CLI |

## Related

- [pr-workflow](.claude/skills/pr-workflow/SKILL.md) - PR creation and management
- [stacked-prs](.claude/skills/stacked-prs/SKILL.md) - Stacked PR workflows
<!-- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY -->
<!-- Source: bitsoex/ai-code-instructions → global/skills/jira-integration/SKILL.md -->
<!-- To modify, edit the source file and run the distribution workflow -->

Overview

This skill automates creating and managing Jira tickets for AI-driven code work, enforcing severity-based processing and clear traceability. It discovers the correct Jira project, searches for existing tickets, creates new tickets when needed, and generates branch names tied to Jira keys. The goal is to keep fixes reviewable, linked, and prioritized by severity.

How this skill works

The skill first discovers the user's Jira project key instead of relying on hardcoded values. It searches for open tickets that match the issue context; if none exist it creates a new ticket using standardized summaries and metadata. It then suggests branch names that include the Jira key and enforces processing one severity level at a time, linking commits and PRs back to the ticket.

When to use it

When fixing vulnerabilities or Dependabot alerts and you must track work in Jira
When resolving SonarQube or code-quality issues that need prioritized handling
When improving test coverage and you need traceable, reviewable PRs
When creating automated commits so each change is linked to a ticket
When you want consistent branch naming and ticket-to-commit traceability

Best practices

Always discover the project key programmatically; never hardcode it
Search for existing tickets first and avoid duplicate tickets
Process issues one severity level per PR to keep changes focused
Use emoji and standardized ticket summaries to make intent clear
Link Jira ticket ↔ branch ↔ commits ↔ PR and update ticket status as work progresses

Example use cases

Create a Jira ticket and branch for CRITICAL security fixes, then open a PR with linked commits
Search for existing SonarQube blocker tickets and batch related fixes into a single reviewable PR
Generate a test/PROJECT-123-coverage branch and open a ticket when adding unit tests to a module
Update dependency versions with a chore/PROJECT-456 branch and a descriptive Jira ticket
Run automated remediation for MEDIUM issues only after HIGH and CRITICAL issues have been addressed

FAQ

What if a matching ticket already exists?

The skill will attach work to the existing ticket instead of creating a duplicate and will use that ticket key in the branch name.

How does severity-based processing work?

Issues are processed in a defined order (e.g., CRITICAL before HIGH) and the skill will not proceed to a lower severity until higher severities are cleared.