rhdh-jira

What this skill does

<essential_principles>

# RHDH Jira

Foundational skill for interacting with RHDH's Jira instance via the Atlassian CLI (`acli`). Covers all four active projects, issue types, workflows, custom fields, and JQL patterns.

</essential_principles>

<intake>

## Commands

| Command | Description | Reference |
|---------|-------------|-----------|
| `assign [issue key(s) or JQL]` | Recommend and assign team members using expertise, capacity, and context proximity analysis | [references/assign.md](references/assign.md) |
| `refine [issue key(s), JQL, or 'sprint']` | Check issues against exit criteria, identify duplicates, missing fields, unaddressed comments, and readiness | [references/refine.md](references/refine.md) |
| `plan [team]` | Sprint planning prep: carryover, velocity, capacity, ready queue, sprint fill suggestions | [references/plan.md](references/plan.md) |
| `sprint-report [team]` | Sprint review summary: committed vs completed, per-member breakdown, demo checklist | [references/sprint-report.md](references/sprint-report.md) |
| `release [version]` | Release readiness: feature matrix, PI funnel, dependency map, blocker bugs, risk assessment | [references/release.md](references/release.md) |
| `to-feature [description]` | Create a RHDHPLAN Feature with grill, duplicate check, and optional Epic decomposition | [references/to-feature.md](references/to-feature.md) |
| `to-epic [description]` | Create an RHIDP Epic with grill, duplicate check, and optional Story/Task decomposition | [references/to-epic.md](references/to-epic.md) |
| `to-issue [description]` | Create a Story, Task, Bug, or Spike with automatic type inference and grill | [references/to-issue.md](references/to-issue.md) |
| `update-jira-status [key]` | Update issue with session progress, status comment, transition, and upward cascade | [references/update-jira-status.md](references/update-jira-status.md) |

Single source of truth for command descriptions: `scripts/command-metadata.json`

**Wait for response before proceeding.**

</intake>

<routing>

### Routing rules

1. **No argument**: Show the command menu. Ask what to do.
2. **First word matches a command**: Load its reference file and follow it.
3. **First word doesn't match**: General Jira invocation using the full argument as context — use the reference files table below to decide what to load.

</routing>

## Prerequisites

Run `scripts/setup.py` to verify everything is configured:

```bash
python scripts/setup.py
```

The script checks:

1. `acli` binary on PATH
2. Jira API token auth configured (`~/.config/acli/jira_config.yaml`)
3. `.jira-token` file next to `acli` executable (for REST API fallback)
4. Smoke test against `redhat.atlassian.net`

If `acli` is not installed, download from [Atlassian CLI](https://developer.atlassian.com/cloud/acli/) and follow the [Getting Started guide](https://developer.atlassian.com/cloud/acli/guides/how-to-get-started/) for installation and authentication setup. Use API token authentication, not OAuth — OAuth sessions expire and `acli auth status` gives false negatives with token auth (see Gotchas).

### API preference order

All operations follow this priority: **acli → GraphQL → REST API**.

- **acli** — default for simple, single-issue operations (view, edit, assign, transition).
- **GraphQL** — for bulk reads where acli would be too slow (expertise profiles, capacity, refinement checks). Skip acli entirely for bulk.
- **REST API** — for writes when already in an authenticated API context (avoids shelling out to acli mid-workflow), or as fallback when acli fails for custom field updates.

Sub-commands (`assign`, `refine`) document which API they use. When a sub-command's workflow already has `AUTH` set from GraphQL reads, prefer REST for writes.

### REST/GraphQL capability gate

Before attempting any REST API or GraphQL call:

1. Run `python scripts/setup.py --json` and check `token_file_found`
2. If missing, state: "REST API/GraphQL fallback unavailable — `.jira-token` not configured. Run `setup.py` for instructions." Continue with acli-only workflow.
3. If the user needs REST/GraphQL, load `references/auth.md` for setup instructions

## Scripts

| Script | Purpose |
|--------|---------|
| `scripts/setup.py` | Verify acli install + auth. Run with `--json` for structured output. |
| `scripts/parse_issues.py` | Flatten, enrich, and filter acli JSON output. Solves the core problem: `acli search --json` can't return custom fields (team, story points, sprint). Pipe search results in, get clean data out. Use `--enrich` to fetch full fields, `-f team="X"` to filter by team. |
| `scripts/command-metadata.json` | Single source of truth for sub-command descriptions and argument hints. |
| `scripts/validate_components.py` | Validate `references/fields.md` component catalog against live Jira projects (RHIDP + RHDHPLAN). Reports drift in both directions. Run with `--json` for structured output. |
| `scripts/jira-wiki-to-adf.py` | Convert a filled Jira wiki markup template to Atlassian Document Format JSON for use with `acli --description-file`. Handles `hN.` headings, `* ` bullets, `# ` ordered lists, `(?)` / `(/)` task items, `*bold*`, `_italic_`, `{{monospace}}`, backtick code. Usage: `python scripts/jira-wiki-to-adf.py input.txt > output.adf.json` |

## Projects

| Key | Purpose | Issue Types |
|-----|---------|-------------|
| RHIDP | Engineering work | Epic, Story, Task, Sub-task, Vulnerability |
| RHDHPLAN | Program planning | Feature, Outcome, Feature Request, Sub-task |
| RHDHBUGS | Product defects | Bug, Sub-task |
| RHDHSUPP | Support-engineering interactions | Bug |

RHDHPAI (Plugins and AI) is **archived** — JQL queries against it will fail.

### Issue type selection

- **Story** — end-user facing work (API, UI changes)
- **Task** — not end-user facing (tests, CI/CD, refactoring, code organization)
- **Epic** — collection of Stories/Tasks toward a deliverable
- **Feature** — program-level planning item in RHDHPLAN
- **Bug** — product defect (RHDHBUGS) or support case tracking (RHDHSUPP)
- **Sub-task** — child of any issue type above
- **Vulnerability** — CVE tracking in RHIDP (Product Security)

<reference_index>

## Reference Files

Load only what the current task requires.

| File | Load when... |
|------|-------------|
| `references/acli-commands.md` | Running an acli command you haven't used before, or hitting unexpected flag behavior. Quick reference for syntax, flag differences, and output formats. |
| `references/fields.md` | Need to know a field name, custom field ID, accepted values, or label conventions. Custom fields, labels, link types, components, priorities. |
| `references/workflows.md` | Transitioning issues, checking exit criteria, or verifying readiness for the next status. |
| `references/templates.md` | Creating new issues. Also load `references/workflows.md` for required fields at entry status. |
| `references/support.md` | Handling support cases, filing bugs from customer cases, or creating feature requests from support. Full RHDHSUPP workflow, SLA, and anti-patterns. |
| `references/feature-exploration.md` | Feature Exploration Process checklist: component validation, labels (demo, rhdh-testday), Doc Epic automation, cross-team dependencies, rescoping. Load when creating Features, refining Features, or checking Feature readiness. |
| `references/jql-patterns.md` | Building a JQL query, finding a board ID, or looking up sprint information. JQL cookbook with 23+ tested queries. |
| `references/auth.md` | Setting up authentication for REST API or GraphQL calls. Token file format, path discovery, security, instance config, common auth errors. |
| `references/rest-api-fallback.md` | `acli` failed to update a custom field (Team, Size, Story Points, Release Note Type). Curl examples, response handling, OpenAPI spec discovery. |
| `references/graphql-queries.md` | Complex read queries needing multiple fields, relationships, or custom field data in one call. Schema in