Merge pull request #18 from redhat-developer/feat/jira-subcommands

feat: add sub-command router and sprint ceremony workflows to rhdh-jira

Author: schultzp2020

README.md

@@ -38,7 +38,12 @@ Test plugins in a local RHDH instance before deploying.
 
 Track work across the four RHDH Jira projects.
 
-- **[rhdh-jira](./skills/rhdh-jira/SKILL.md)** — Search, create, view, edit, transition, and link issues across RHIDP, RHDHPLAN, RHDHBUGS, and RHDHSUPP. Uses `acli` with REST API and GraphQL fallback for custom fields.
+- **[rhdh-jira](./skills/rhdh-jira/SKILL.md)** — Search, create, view, edit, transition, link, assign, and refine issues across RHIDP, RHDHPLAN, RHDHBUGS, and RHDHSUPP. Uses `acli` for simple operations, GraphQL for bulk reads, and REST API as fallback. Sub-commands:
+  - **[assign](./skills/rhdh-jira/references/assign.md)** — Recommend assignees using team expertise profiling, sprint capacity analysis, and context proximity scoring. Supports deep mode (5-layer analysis via GraphQL) and quick mode (match from existing context). Assigns after user confirmation.
+  - **[refine](./skills/rhdh-jira/references/refine.md)** — Check issues against RHDH workflow exit criteria, detect duplicates, verify parent/child hierarchy, flag unaddressed comments, identify stale issues, and validate sprint readiness.
+  - **[plan](./skills/rhdh-jira/references/plan.md)** — Sprint planning prep: carryover report, velocity trend, per-member capacity, ready-for-planning queue, and sprint fill suggestions with expertise matching.
+  - **[sprint-report](./skills/rhdh-jira/references/sprint-report.md)** — Sprint review summary: committed vs completed, per-member breakdown, epic progress, demo checklist with naming conventions, and velocity trend.
+  - **[release](./skills/rhdh-jira/references/release.md)** — Release readiness: feature matrix, Program Increment funnel, epic roll-up, cross-team dependency map, blocker bugs, release notes readiness, and risk assessment.
 
 ### Orchestration
 

skills/rhdh-jira/SKILL.md

@@ -1,14 +1,32 @@
 ---
 name: rhdh-jira
 description: |
-  Interacts with RHDH Jira projects (RHIDP, RHDHPLAN, RHDHBUGS, RHDHSUPP) using the Atlassian CLI (acli), with REST API and GraphQL fallback for custom field updates and complex queries. 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, JQL queries, or Jira API schema discovery. 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, release planning, or acli setup and installation.
+  Interacts with RHDH Jira projects (RHIDP, RHDHPLAN, RHDHBUGS, RHDHSUPP) using acli, GraphQL, and REST API. Use when the user needs to search, create, view, edit, transition, assign, refine, or report on Jira issues for RHDH. Also use for sprint planning, sprint reviews, release readiness, assignee recommendations, or issue refinement. Trigger on Jira issue keys (RHIDP-1234, RHDHPLAN-567), sprint ceremony prep, "who should take this", "refine this", "plan the sprint", "sprint report", "how's the release looking", or "release status".
 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.
 
+## 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) |
+
+Single source of truth for command descriptions: `scripts/command-metadata.json`
+
+### 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.
+
 ## Prerequisites
 
 Run `scripts/setup.py` to verify everything is configured:
@@ -26,6 +44,16 @@ The script checks:
 
 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:
@@ -40,6 +68,7 @@ Before attempting any REST API or GraphQL call:
 |--------|---------|
 | `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. |
 
 ## Projects
 
@@ -76,15 +105,20 @@ Load only what the current task requires.
 | `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 introspection, JQL search via GraphQL, field type fragments. |
+| `references/graphql-queries.md` | Complex read queries needing multiple fields, relationships, or custom field data in one call. Schema introspection, JQL search via GraphQL, field type fragments. Also for bulk operations where acli would be too slow. |
+| `references/assign.md` | Recommending assignees for unassigned issues. Team roster lookup, expertise profiling, sprint capacity analysis, context proximity scoring. Also for applying assignments after user confirmation. |
+| `references/refine.md` | Checking issues against exit criteria per status, identifying duplicates, missing fields, unaddressed comments, and readiness for the next workflow status. |
+| `references/plan.md` | Sprint planning prep: carryover report, velocity trend, per-member capacity, ready-for-planning queue, sprint fill suggestions. |
+| `references/sprint-report.md` | Sprint review summary: committed vs completed, per-member breakdown, epic progress, demo checklist with naming conventions, velocity trend. |
+| `references/release.md` | Release readiness report: feature matrix, PI funnel states, epic roll-up, cross-team dependency map, blocker bugs, RN readiness, risk assessment. |
 
 ## 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.
+5. **Team field has two JQL syntaxes.** `customfield_10001` cannot be used in JQL WHERE clauses. However, `"Team[Team]" = {teamId}` (using the team UUID, not display name) works. Use the UUID syntax for JQL filtering; use `customfield_10001.name` in post-processing only when you need the display name from JSON output.
 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`.
 8. **`--enrich` is MANDATORY for custom fields.** Both `acli search --json` and `acli view KEY --json` (without `--fields "*all"`) return only basic fields (assignee, issuetype, priority, status, summary). Story points, team, sprint, and size will appear as empty/null — looking like the data isn't set when it actually is. Always use `scripts/parse_issues.py --enrich` to get custom field data. Skipping `--enrich` is the #1 cause of false "missing data" reports.
@@ -105,9 +139,19 @@ Load only what the current task requires.
 | Rate limiting (429) | Wait 5 seconds, retry once. |
 | Interactive prompt hangs | Missing `--yes` flag on a mutating command. |
 | Custom field update fails via `acli` | Fall back to Jira REST API using `.jira-token` file. See Gotcha #9. |
+| `issueSearchStable` returns errors | Fall back to REST API search (`/rest/api/3/search`) with the same JQL. Warn that the beta API failed. |
+
+## Team Conventions
+
+These apply across all sub-commands:
+
+- **Release Pending counts as completed.** Release Pending items remain in the sprint and count toward velocity and capacity. They represent done work awaiting release.
+- **Confirmation flow.** Sub-commands that modify Jira issues (assign, refine, release) use a standard prompt: `"Apply changes? [y/N/edit]"` — **y** applies all, **N** cancels, **edit** steps through each change individually.
 
 ## Common Workflows
 
+> Sub-commands share data. `plan` reuses roster/capacity/expertise from `assign`. `sprint-report` uses the same velocity query pattern as `plan`. `release` references exit criteria from `workflows.md` and can invoke `assign` for unassigned Features.
+
 ### Creating an issue
 
 1. Load `references/templates.md` for the body template
@@ -132,6 +176,46 @@ Load only what the current task requires.
 2. Use `issueByKey` for single issues or `issueSearchStable` (beta) for JQL search
 3. Fall back to `acli` + `parse_issues.py --enrich` if GraphQL returns errors
 
+### Recommending and assigning issues
+
+1. Load `references/assign.md`
+2. Identify unassigned issues (single key, JQL query, or passed-in list)
+3. Determine the team (from issue field, parent epic, or user input)
+4. Run deep or quick analysis per the reference
+5. Present recommendations, get user confirmation, then assign
+
+### Refining issues
+
+1. Load `references/refine.md`
+2. Identify issues to refine (specific keys, JQL, `sprint`, or `backlog`)
+3. Run all 6 checks: missing fields, duplicates, hierarchy, comments, staleness, sprint readiness
+4. Present refinement report with actionable recommendations
+5. Optionally apply auto-fixable changes and prompt for manual decisions
+
+### Sprint planning prep
+
+1. Load `references/plan.md`
+2. Resolve team, board, and sprint context
+3. Generate carryover report, velocity trend, capacity snapshot, and ready-for-planning queue
+4. Auto-generate sprint fill suggestions with expertise matching
+5. Surface critical customer bugs (exempt from capacity) and retro action items
+
+### Sprint review summary
+
+1. Load `references/sprint-report.md`
+2. Resolve sprint (active or previous)
+3. Partition completed vs carried over, compute completion rate
+4. Per-member breakdown, epic progress, demo checklist with naming conventions
+5. Optionally save as markdown file
+
+### Release readiness
+
+1. Load `references/release.md`
+2. Fetch Features for the target version/label
+3. Quick mode: PI funnel, feature matrix, readiness score
+4. Deep mode: adds epic roll-up, dependency map, coherence analysis, RN readiness, risk assessment
+5. Optionally remediate (assign owners, create Epics, transition statuses)
+
 ### Discovering unknown fields or endpoints
 
 1. For REST: load `references/rest-api-fallback.md` — use the OpenAPI spec or `/rest/api/3/field` endpoint
@@ -141,5 +225,5 @@ Load only what the current task requires.
 ## 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** — use `acli` first. REST API is a fallback for custom field updates and schema discovery when `acli` cannot handle the operation (see Gotcha #9)
-- **GraphQL for simple lookups** — use `acli` for single-issue views and simple searches. GraphQL is for complex queries needing relationships or many custom fields in one call, and for schema introspection
+- **Jira REST API directly** — use `acli` first, then GraphQL for bulk reads. REST API is the last resort for writes when acli fails and for schema discovery via OpenAPI spec (see Gotcha #9)
+- **GraphQL for simple lookups** — use `acli` for single-issue views and simple searches. GraphQL is for bulk operations, complex queries needing relationships or many custom fields in one call, team roster lookups, and schema introspection