redhat-developer · schultzp2020 · May 6, 2026 · May 6, 2026
diff --git a/skills/rhdh-jira/SKILL.md b/skills/rhdh-jira/SKILL.md
@@ -0,0 +1,110 @@
+---
+name: rhdh-jira
+description: |
+  Interact with RHDH Jira projects (RHIDP, RHDHPLAN, RHDHBUGS, RHDHSUPP) using the Atlassian CLI (acli). Use when the user needs to search, create, view, edit, transition, comment on, or link Jira issues for Red Hat Developer Hub. Also use when the user asks about Jira workflows, exit criteria, issue templates, custom fields, boards, sprints, or JQL queries in the RHDH context. Trigger when the user mentions Jira issue keys like RHIDP-1234, RHDHPLAN-567, RHDHBUGS-890, or any RHDH project key. Also trigger for support case bug filing, feature request creation, or release planning in Jira. Covers acli setup, authentication, and troubleshooting.
+compatibility: "acli (Atlassian CLI) on PATH. Python 3 for scripts. Windows, macOS, Linux."
+---
+
+# 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.
+
+## 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. Smoke test against `redhat.atlassian.net`
+
+If `acli` is not installed, download from [Atlassian CLI](https://developer.atlassian.com/cloud/acli/). Authenticate with `acli auth login` or configure an API token.
+
+## 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. |
+
+## 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 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. |
+| `references/jql-patterns.md` | Building a JQL query, finding a board ID, or looking up sprint information. JQL cookbook with 23+ tested queries. |
+
+## Common Gotchas
+
+1. **`acli auth status` lies.** It checks OAuth, not API token auth. Always returns "unauthorized" with token auth even when Jira works fine. Use `acli jira project list --recent 1` as a smoke test instead.
+2. **`view` uses positional arg, everything else uses `--key`.** `acli jira workitem view RHIDP-123` but `acli jira workitem edit --key RHIDP-123 ...`.
+3. **`--yes` is mandatory for mutations.** All `edit`, `transition`, `assign`, and `link create` commands prompt interactively without it. Always pass `--yes`.
+4. **`--fields` is restrictive on search.** Only accepts `key`, `summary`, `status`, `assignee`, `issuetype`, `priority`, `description`, `labels`. For components, sprint, fixVersions, and all custom fields — use `--json` or `scripts/parse_issues.py --enrich`.
+5. **Team field is NOT JQL-filterable.** `customfield_10001` cannot be used in JQL WHERE clauses. Fetch all issues, filter by `customfield_10001.name` in post-processing.
+6. **ADF vs plain text.** Reading descriptions via `--json` returns Atlassian Document Format (nested JSON). Creating/editing with `--description` accepts plain text. Don't try to round-trip ADF through `--description`.
+7. **Acceptance Criteria field is almost always null.** Scan the description for "Requirements", "Acceptance Criteria", or bullet-style criteria instead of checking `customfield_10718`.
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| `acli` not on PATH | Run `scripts/setup.py`. Install from Atlassian if missing. |
+| "unauthorized" from `auth status` | Ignore. Check `jira_config.yaml` exists. Run smoke test. |
+| "required flag(s) not set" | Command syntax wrong. Run `acli jira <subcommand> --help`. |
+| "field X is not allowed" | Use `--json` instead of `--fields` for that field. |
+| "the value X does not exist for the field 'project'" | Project key is wrong or project is archived (e.g., RHDHPAI). |
+| Rate limiting (429) | Wait 5 seconds, retry once. |
+| Interactive prompt hangs | Missing `--yes` flag on a mutating command. |
+
+## Common Workflows
+
+### Creating an issue
+1. Load `references/templates.md` for the body template
+2. Load `references/workflows.md` for required fields at New status
+3. Run `acli jira workitem create` (see `references/acli-commands.md` if unsure of syntax)
+
+### Searching with custom fields (team, story points, sprint)
+1. Build JQL using patterns from `references/jql-patterns.md`
+2. Pipe results through `scripts/parse_issues.py --enrich` for full field data
+3. Use `-f team="X"` to filter by team (not possible in JQL)
+
+### Transitioning an issue
+1. Load `references/workflows.md` for exit criteria at the target status
+2. Verify required fields are set before transitioning
+3. Run `acli jira workitem transition --key KEY --status "X" --yes`
+
+## When NOT to Use
+
+- **Non-RHDH Jira projects** — this skill's field mappings, workflows, and JQL patterns are specific to RHIDP/RHDHPLAN/RHDHBUGS/RHDHSUPP
+- **Jira REST API directly** — this skill covers `acli` CLI only
diff --git a/skills/rhdh-jira/references/acli-commands.md b/skills/rhdh-jira/references/acli-commands.md
@@ -0,0 +1,233 @@
+# acli Jira Command Reference
+
+Cheat sheet for `acli jira` commands. For full flag details, run `acli jira <subcommand> --help`.
+
+## Key Syntax Rules
+
+1. **`view` takes a positional arg.** Everything else uses `--key`.
+2. **Always pass `--yes`** on mutating commands (`edit`, `transition`, `assign`, `link create`) to skip interactive prompts.
+3. **Use `--json`** when you need fields beyond `key`, `summary`, `status`, `assignee`, `issuetype`, `priority`, `description`. The `--fields` flag rejects `components`, `sprint`, `labels`, `fixVersions`.
+4. **Use `--csv`** for search results you want to pipe or parse.
+5. **Use `--paginate`** to fetch all results beyond the default page size.
+
+## Work Items
+
+### Search
+
+```bash
+# JQL search with field selection
+acli jira workitem search --jql "project = RHIDP AND status = 'In Progress'" --fields "key,summary,status,assignee" --limit 50
+
+# JSON output for full field data
+acli jira workitem search --jql "project = RHIDP" --limit 20 --json
+
+# Count only
+acli jira workitem search --jql "project = RHDHBUGS AND status not in (Closed)" --count
+
+# CSV export
+acli jira workitem search --jql "project = RHIDP" --fields "key,summary,status" --csv
+
+# Fetch all results (paginated)
+acli jira workitem search --jql "project = RHIDP AND sprint in openSprints()" --paginate
+```
+
+### View
+
+```bash
+# View issue (positional arg — NOT --key)
+acli jira workitem view RHIDP-123
+
+# Specific fields
+acli jira workitem view RHIDP-123 --fields "summary,description,status"
+
+# All fields
+acli jira workitem view RHIDP-123 --fields "*all"
+
+# JSON for full data (components, sprint, custom fields)
+acli jira workitem view RHIDP-123 --json
+
+# Open in browser
+acli jira workitem view RHIDP-123 --web
+```
+
+### Create
+
+```bash
+# Basic creation
+acli jira workitem create --project RHIDP --type Story --summary "Implement auth plugin" --description "As a user..." --assignee "@me"
+
+# With labels
+acli jira workitem create --project RHDHBUGS --type Bug --summary "Login fails" --label "rhdh-customer,ci-fail"
+
+# With parent (sub-task or child of epic)
+acli jira workitem create --project RHIDP --type Task --summary "Write tests" --parent RHIDP-12968
+
+# From JSON file (complex issues)
+acli jira workitem create --from-json workitem.json --project RHIDP --type Epic
+
+# Generate JSON template
+acli jira workitem create --generate-json
+
+# From description file
+acli jira workitem create --project RHIDP --type Story --summary "New feature" --description-file story.txt
+```
+
+### Edit
+
+```bash
+# Edit summary (--key flag, NOT positional)
+acli jira workitem edit --key RHIDP-123 --summary "Updated summary" --yes
+
+# Edit multiple issues
+acli jira workitem edit --key "RHIDP-123,RHIDP-124" --assignee "jdoe@example.com" --yes
+
+# Edit by JQL (batch)
+acli jira workitem edit --jql "project = RHIDP AND labels = 'needs-info'" --labels "needs-pm" --yes
+
+# Add/remove labels
+acli jira workitem edit --key RHIDP-123 --labels "demo,test-day" --yes
+acli jira workitem edit --key RHIDP-123 --remove-labels "needs-info" --yes
+
+# Edit description from file
+acli jira workitem edit --key RHIDP-123 --description-file updated.txt --yes
+
+# Edit issue type
+acli jira workitem edit --key RHIDP-123 --type Task --yes
+```
+
+### Transition
+
+```bash
+# Move to status (--key flag)
+acli jira workitem transition --key RHIDP-123 --status "In Progress" --yes
+
+# Batch transition by JQL
+acli jira workitem transition --jql "project = RHIDP AND status = 'Review'" --status "Closed" --yes
+
+# Ignore errors on batch (some may not have valid transition)
+acli jira workitem transition --jql "..." --status "To Do" --yes --ignore-errors
+```
+
+### Assign
+
+```bash
+# Assign to self
+acli jira workitem assign --key RHIDP-123 --assignee "@me" --yes
+
+# Assign to user
+acli jira workitem assign --key RHIDP-123 --assignee "jdoe@example.com" --yes
+
+# Assign to project default
+acli jira workitem assign --key RHIDP-123 --assignee "default" --yes
+```
+
+### Comment
+
+```bash
+# Add comment
+acli jira workitem comment create --key RHIDP-123 --body "Investigation complete. Root cause: ..."
+
+# List comments
+acli jira workitem comment list --key RHIDP-123
+
+# Update comment
+acli jira workitem comment update --key RHIDP-123 --id 12345 --body "Updated findings"
+
+# Delete comment
+acli jira workitem comment delete --key RHIDP-123 --id 12345
+```
+
+### Links
+
+```bash
+# List available link types
+acli jira workitem link type
+
+# Create link (--out = source, --in = target)
+acli jira workitem link create --out RHIDP-123 --in RHIDP-456 --type "Blocks" --yes
+
+# List links on an issue
+acli jira workitem link list --key RHIDP-123
+
+# Delete link (by link ID only, no --key needed)
+acli jira workitem link delete --id 12345 --yes
+```
+
+### Attachments
+
+```bash
+# List attachments (note: attachment upload is not available via acli)
+acli jira workitem attachment list --key RHIDP-123
+
+# Delete attachment
+acli jira workitem attachment delete --key RHIDP-123 --id 12345
+```
+
+## Boards
+
+```bash
+# Search boards by project
+acli jira board search --project RHIDP
+
+# Search by name
+acli jira board search --name "RHDH Cope"
+
+# Get board details
+acli jira board get --id 11374
+
+# List sprints for a board (--id, NOT --board-id)
+acli jira board list-sprints --id 11374
+
+# Active sprints only
+acli jira board list-sprints --id 11374 --state active
+```
+
+## Sprints
+
+```bash
+# View sprint details
+acli jira sprint view --id 65456
+
+# List work items in a sprint
+acli jira sprint list-workitems --sprint 65456 --board 11374
+
+# Create sprint
+acli jira sprint create --name "RHDH COPE 3292" --board 11374
+```
+
+## Projects
+
+```bash
+# List recent projects
+acli jira project list --recent 10
+
+# View project details
+acli jira project view --key RHIDP
+```
+
+## Filters
+
+```bash
+# Search for saved filters
+acli jira filter search --name "RHDH"
+
+# List my/favourite filters
+acli jira filter list --my
+acli jira filter list --favourite
+
+# Get filter details (includes JQL)
+acli jira filter get --id 10001
+```
+
+## Output Format Differences
+
+| Behavior | Table (default) | `--json` |
+|----------|----------------|----------|
+| Description | Plain text | ADF (Atlassian Document Format) |
+| Team field | String name | Complex object `{id, name, avatarUrl, ...}` |
+| Sprint field | Not shown | Array of sprint objects |
+| Components | Not available via `--fields` | Full objects |
+| Labels | Not available via `--fields` | Array of strings |
+| Fix versions | Not available via `--fields` | Array of version objects |
+
+When writing descriptions, use `--description "plain text"`. When reading, be aware `--json` returns ADF — don't try to round-trip it.