Jira Operations

---

name: "jira-operations"
description: "JIRA cache and performance operations. TRIGGERS: 'warm the cache', 'warm cache', 'cache status', 'clear cache', 'cache warm', 'cache for project', 'discover project', 'project discovery', 'cache hit rate', 'optimize performance', 'rate limit'. Use for JIRA API performance optimization and project context discovery. NOT FOR: project configuration/settings (use jira-admin), issue operations (use jira-issue), bulk issue modifications (use jira-bulk)."
version: "1.0.0"
author: "jira-assistant-skills"
license: "MIT"
allowed-tools: ["Bash", "Read", "Glob", "Grep"]
triggers:
  - "Cache hit rate drops below 50%"
  - "JIRA API responses slower than 2 seconds"
  - "Setting up new JIRA instance"
  - "Before bulk operations (warm cache first)"
  - "After modifying projects (invalidate cache)"
  - "Troubleshooting 429 rate limit errors"
origin:
  type: upstream
upstream:
  repository: grandcamel/JIRA-Assistant-Skills
  path: skills/jira-ops
  ref: b5837311ca3ae61ac56dab8fe9c0d9a4e075c092
  license: MIT
trust:
  tier: reviewed
  reviewed_at: '2026-08-26'
  reviewed_by: ulises-jeremias
  reviewed_provenance: sha256:d864df3b378a12155a9e210335f84bdbe00e7d4faa4be24864a22a7f21dc0a0b
maintenance:
  status: active
  last_checked: '2026-08-26'
distribution:
  mode: vendored
  redistribution_allowed: true
  attribution_file: LICENSE
security:
  scripts: false
  shell: false
  network: true
  mcp: false
  hooks: false
---

# JIRA Operations Skill

Cache management, request batching, and operational utilities for JIRA Assistant.

## Risk Levels

| Operation | Risk | Notes |
|-----------|------|-------|
| Discover project | `-` | Read-only analysis |
| Cache status | `-` | Read-only |
| Cache warm | `-` | Populates local cache |
| Cache clear (dry-run) | `-` | Preview only |
| Cache clear | `!` | Local cache cleared, will re-fetch |

**Risk Legend**: `-` Safe, read-only | `!` Caution, modifiable | `!!` Warning, destructive but recoverable | `!!!` Danger, irreversible

## When to Use This Skill

Use this skill when you need to:

- **Discover project context**: Auto-discover project metadata, workflows, and usage patterns
- **Monitor cache status**: Check cache size, entry counts, and hit rates
- **Clear cache data**: Remove stale or sensitive cached data
- **Pre-warm cache**: Load commonly accessed data for better performance
- **Optimize performance**: Reduce API calls through effective caching
- **Troubleshoot slowness**: Diagnose cache-related performance issues

## What This Skill Does

**IMPORTANT:** Always use the `jira-as` CLI. Never run Python scripts directly.

- **Project Discovery**: Discover project metadata and usage patterns (field fill rates, value distributions, parent hierarchy) for intelligent defaults
- **Cache Status Monitoring**: Display cache statistics (size, entries, hit rates)
- **Cache Clearing**: Remove cache entries by category, pattern, or all at once
- **Cache Warming**: Pre-load project metadata and field definitions
- **Request Batching**: Parallel request execution for bulk operations (programmatic API)

## Quick Start

```bash
# Discover project context (prints to stdout)
jira-as ops discover-project PROJ

# Check cache status
jira-as ops cache-status

# Clear all cache
jira-as ops cache-clear --force

# Warm cache with all metadata
jira-as ops cache-warm --all
```

## Common Tasks (30-Second Solutions)

### Check cache status
```bash
# Basic status
jira-as ops cache-status

# Output as JSON
jira-as ops cache-status --json

# Verbose output (-v is short for --verbose)
jira-as ops cache-status -v
jira-as ops cache-status --verbose
```

### Warm the cache
```bash
# Cache project list
jira-as ops cache-warm --projects

# Cache field definitions
jira-as ops cache-warm --fields

# Cache assignable users (requires project context)
jira-as ops cache-warm --users

# Cache all available metadata with verbose output
jira-as ops cache-warm --all --verbose

# Output as JSON
jira-as ops cache-warm --all --json
```

### Clear cache
```bash
# Clear all cache (with confirmation)
jira-as ops cache-clear

# Clear all cache (skip confirmation, -f is short for --force)
jira-as ops cache-clear -f
jira-as ops cache-clear --force

# Clear only issue cache (-c is short for --category)
# Categories: issue, project, user, field, search, default
jira-as ops cache-clear -c issue -f
jira-as ops cache-clear --category issue --force

# Preview what would be cleared
jira-as ops cache-clear --dry-run

# Clear keys matching pattern
jira-as ops cache-clear --pattern "PROJ-*" -c issue -f

# Clear specific cache key (requires --category)
jira-as ops cache-clear --key "PROJ-123" -c issue -f

# Output as JSON
jira-as ops cache-clear -f --json
```

### Discover project context
```bash
# Discover and print project context to stdout (text format)
jira-as ops discover-project PROJ

# Output as JSON (-o is short for --output)
jira-as ops discover-project PROJ -o json
jira-as ops discover-project PROJ --output json

# Verbose output with detailed analysis (-v is short for --verbose)
jira-as ops discover-project PROJ -v

# Custom sample size and period (-s, -d are short forms)
jira-as ops discover-project PROJ -s 200 -d 60
jira-as ops discover-project PROJ --sample-size 200 --days 60

# Output goes to stdout only; redirect to save the full discovery data
jira-as ops discover-project PROJ -o json > project-context.json
```

Discovery output includes project metadata (issue types, components, versions,
assignable users) plus pattern analysis of sampled issues: top assignees,
common labels, per-field fill rates, value distributions (issue type, status,
priority), and parent hierarchy usage. Use `--output json` to get the full
discovery data.

See [Commands Guide](docs/COMMANDS.md) for complete documentation.

## Available Commands

All commands support `--help` for full documentation.

| Command | Description |
|---------|-------------|
| `jira-as ops discover-project` | Discover project configuration and usage patterns (stdout only) |
| `jira-as ops cache-status` | Display cache statistics (size, entries, hit rate) |
| `jira-as ops cache-clear` | Clear cache entries (all, by category, or by pattern) |
| `jira-as ops cache-warm` | Pre-warm cache with commonly accessed data |

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Validation or general error |
| 2 | Authentication error |
| 3 | Permission denied |
| 4 | Resource not found |
| 5 | Rate limit exceeded |
| 6 | Conflict error |
| 7 | Server error |
| 130 | Cancelled (Ctrl+C) |

## Configuration

Cache is stored in `~/.jira-skills/cache/` with configurable TTL per category.

See [Configuration Guide](docs/CONFIG.md) for details.

## Shared Libraries

This skill uses shared infrastructure from `jira-as`:

| Library | Description |
|---------|-------------|
| `cache.py` | SQLite-based caching with TTL and LRU eviction |
| `request_batcher.py` | Parallel request batching for bulk operations |

See [API Reference](docs/API_REFERENCE.md) for programmatic usage.

## Documentation

- [Quick Start Guide](docs/QUICK_START.md) - Get started in 5 minutes
- [Scripts Guide](docs/SCRIPTS.md) - Detailed script documentation
- [API Reference](docs/API_REFERENCE.md) - Programmatic cache and batcher APIs
- [Configuration](docs/CONFIG.md) - TTL settings
- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions
- [Security](docs/SECURITY.md) - Cache security considerations
- [Best Practices](docs/best-practices/INDEX.md) - Optimization patterns