feat: add issue creation, status update commands, and shared references

README.md

@@ -44,6 +44,10 @@ Track work across the four RHDH Jira projects.
   - **[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.
+  - **[to-feature](./skills/rhdh-jira/references/to-feature.md)** — Create a RHDHPLAN Feature from conversation context. Grills on scope, customer value, and acceptance criteria. Optionally chains into Epic decomposition.
+  - **[to-epic](./skills/rhdh-jira/references/to-epic.md)** — Create an RHIDP Epic. Grills on delivery scope, dependencies, and acceptance criteria. Optionally chains into Story/Task decomposition.
+  - **[to-issue](./skills/rhdh-jira/references/to-issue.md)** — Create a Story, Task, Bug, or Spike with automatic type inference. Grills on implementation details and story points.
+  - **[update-jira-status](./skills/rhdh-jira/references/update-jira-status.md)** — Update an issue with session progress. Detects the related issue, adds a status comment, proposes transitions, and checks upward cascade to parent Epic/Feature.
 
 ### Orchestration
 

skills/rhdh-jira/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: rhdh-jira
 description: |
-  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".
+  Interacts with RHDH Jira projects (RHIDP, RHDHPLAN, RHDHBUGS, RHDHSUPP) using acli, GraphQL, and REST API. Covers the full Jira lifecycle: create issues, assign, refine, plan sprints, report, track releases, and update status. Trigger on Jira keys (RHIDP-1234), "create a feature/epic/story/task/bug", "who should take this", "refine this", "plan the sprint", "sprint report", "release status", "update jira", or any sprint ceremony prep.
 compatibility: "acli (Atlassian CLI) on PATH. Python 3 for scripts. Windows, macOS, Linux."
 ---
 
@@ -18,6 +18,10 @@ Foundational skill for interacting with RHDH's Jira instance via the Atlassian C
 | `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`
 
@@ -111,6 +115,13 @@ Load only what the current task requires.
 | `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. |
+| `references/to-feature.md` | Create a RHDHPLAN Feature from conversation context with grill and optional Epic decomposition. |
+| `references/to-epic.md` | Create an RHIDP Epic from conversation context with grill and optional Story/Task decomposition. |
+| `references/to-issue.md` | Create a Story, Task, Bug, or Spike with automatic type inference and grill. |
+| `references/update-jira-status.md` | Update a Jira issue with session progress, status comment, transitions, and upward cascade to parent Epic/Feature. |
+| `references/duplicates.md` | Duplicate detection for pre-creation checks and refinement audits. Shared across creation commands and refine. |
+| `references/grill.md` | Shared challenging behavior for issue creation grills: sizing, completeness, scope, risks, cross-referencing. |
+| `references/sizing.md` | T-shirt sizing guide for Features/Epics and Fibonacci story points for Stories/Tasks. Used during grills and refinement. |
 
 ## Common Gotchas
 
@@ -146,7 +157,9 @@ Load only what the current task requires.
 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.
+- **Confirmation flow.** Sub-commands that modify Jira issues use a standard prompt: `"Apply changes? [y/N/edit]"` — **y** applies all, **N** cancels, **edit** steps through each change individually.
+- **Closure requires rationale.** When closing or descoping issues, always add a comment documenting the reason and set the resolution field (`Won't Do`, `Duplicate`, `Done`). Preserves the decision trail.
+- **Comments over description bloat.** Issue descriptions use the structured template sections. Decision trail, elaboration, abandoned approaches, and customer context go in comments. Creation commands proactively suggest comments for context that emerged during the grill.
 
 ## Common Workflows
 
@@ -216,6 +229,24 @@ These apply across all sub-commands:
 4. Deep mode: adds epic roll-up, dependency map, coherence analysis, RN readiness, risk assessment
 5. Optionally remediate (assign owners, create Epics, transition statuses)
 
+### Creating Features, Epics, and Issues
+
+1. Load the appropriate creation reference (`to-feature.md`, `to-epic.md`, or `to-issue.md`)
+2. Load `references/grill.md` for challenging behavior
+3. Load the template + example pair from `assets/templates/` and `assets/examples/`
+4. Grill the user on scope, AC, sizing (reference `references/sizing.md`)
+5. Run duplicate check per `references/duplicates.md`
+6. Create the issue, suggest comments for decision trail
+7. Offer chained decomposition (Feature → Epics → Stories/Tasks)
+
+### Updating Jira from a session
+
+1. Load `references/update-jira-status.md`
+2. Detect related issue (conversation → git → PR → commits → keyword search)
+3. Compose status comment, propose transition
+4. Check upward cascade (sibling completion → parent transition)
+5. Suggest reaching out to Feature Owner if Feature-level work is complete
+
 ### Discovering unknown fields or endpoints
 
 1. For REST: load `references/rest-api-fallback.md` — use the OpenAPI spec or `/rest/api/3/field` endpoint

skills/rhdh-jira/assets/examples/bug-example.txt

@@ -0,0 +1,34 @@
+h2. *Description of problem:*
+
+Dynamic plugin loading fails silently when the plugin's package.json contains an invalid `scalprum` field. The plugin does not appear in the UI and no error is logged to the backend console.
+
+h2. *Prerequisites (if any, like setup, operators/versions):*
+
+RHDH 1.10 deployed via Helm chart with dynamic plugins enabled. At least one dynamic plugin configured in `dynamic-plugins.yaml`.
+
+h2. *Steps to Reproduce*
+
+ # Deploy RHDH 1.10 with Helm chart
+ # Add a dynamic plugin with an invalid `scalprum.name` field (e.g., missing the `@` prefix)
+ # Restart the RHDH pod
+ # Navigate to the UI and check for the plugin's page/card
+
+h2. *Actual results:*
+
+Plugin does not render. No error in browser console. No error in backend logs. The plugin appears as "loaded" in the admin panel but its components are not mounted.
+
+h2. *Expected results:*
+
+Either the plugin loads correctly despite the naming mismatch, or a clear error is logged indicating the scalprum name doesn't match the expected format.
+
+h2. *Reproducibility (Always/Intermittent/Only Once):*
+
+Always
+
+h2. *Build Details:*
+
+RHDH 1.10.2, Helm chart 1.10.1, OpenShift 4.16
+
+h2. *Additional info (Such as Logs, Screenshots, etc):*
+
+Discovered while onboarding the cost-management plugin. The invalid scalprum name was `cost-management` instead of `@red-hat-developer-hub/backstage-plugin-cost-management`. Once corrected, the plugin loaded. No documentation mentions this naming requirement.

skills/rhdh-jira/assets/examples/epic-example.txt

@@ -0,0 +1,32 @@
+h1. EPIC Goal
+
+Implement multi-source catalog provider registration and entity merging so that RHDH can ingest entities from multiple external catalogs simultaneously.
+
+h2. *Background/Feature Origin*
+
+Part of the Multi-Source Catalog Ingestion feature (RHDHPLAN-500). Platform engineers need to aggregate software catalog data from GitHub, GitLab, and Bitbucket without running separate RHDH instances.
+
+h2. *Why is this important?*
+
+Enterprise customers with heterogeneous SCM environments currently run multiple RHDH instances — one per catalog source. This increases operational overhead, fragments the developer experience, and makes cross-source search impossible.
+
+h2. *User Scenarios*
+
+* Platform engineer adds a GitLab provider alongside an existing GitHub provider via app-config
+* Developer searches the catalog and finds results from both GitHub and GitLab without knowing which source they came from
+* Admin views per-provider ingestion status in the admin dashboard
+
+h2. *Dependencies (internal and external)*
+
+* Backstage core catalog module provider registration API (upstream)
+* RHDH dynamic plugin system — must not interfere with provider lifecycle
+* RHIDP-600: Admin dashboard health monitoring (internal, parallel)
+
+h2. *Acceptance Criteria*
+
+(?) DEV - Upstream code and tests merged: provider registration + entity merge logic
+(?) DEV - Upstream documentation merged: multi-source configuration guide
+(?) DEV - Downstream build attached to advisory
+(?) QE - Test plans in Playwright: multi-provider ingestion + dedup scenarios
+(?) QE - Automated tests merged: provider failure isolation tests
+(?) DOC - Downstream documentation merged: admin guide + migration guide

skills/rhdh-jira/assets/examples/feature-example.txt

@@ -0,0 +1,34 @@
+h1. *Feature Overview (aka. Goal Summary)*
+
+Enable multi-source catalog ingestion so that RHDH can aggregate entities from multiple external catalogs (GitHub, GitLab, Bitbucket) into a unified software catalog without manual registration.
+
+h3. *Goals (aka. expected user outcomes)*
+
+Platform engineers can configure multiple catalog providers in a single RHDH instance and see all entities merged into one catalog view. End users searching the catalog see results from all configured sources without knowing which backend they came from.
+
+h3. *Requirements (aka. Acceptance Criteria):*
+
+* Users can add multiple catalog providers via app-config without code changes
+* Entity deduplication works across sources (same entity from GitHub and GitLab is merged, not duplicated)
+* Catalog refresh is incremental — only changed entities are re-processed
+* Error in one provider does not block ingestion from other providers
+* Admin dashboard shows per-provider ingestion status and error counts
+* Performance: 10,000 entities across 3 providers completes initial ingestion within 5 minutes
+
+h3. *Out of Scope (Optional)*
+
+* Real-time event-driven ingestion (webhook-based) — future release
+* Custom catalog provider SDK for third-party integrations
+* Migration tooling from single-source to multi-source configuration
+
+h3. *Customer Considerations (Optional)*
+
+Large enterprise customers (500+ developers) have expressed this as a top-3 need. Current workaround is running separate RHDH instances per catalog source, which increases operational overhead and fragments the developer experience.
+
+h3. *Documentation Considerations*
+
+Existing catalog configuration docs need a new "Multi-Source Configuration" section. Admin guide needs per-provider health monitoring docs. Migration guide from single-source to multi-source needed.
+
+h3. *Upstream engagement*
+
+Backstage core catalog module supports multiple providers natively. Need to verify RHDH dynamic plugin system doesn't interfere with provider registration lifecycle. Engage with Backstage SIG Catalog for alignment on entity merging behavior.

skills/rhdh-jira/assets/examples/story-example.txt

@@ -0,0 +1,41 @@
+h1. Story (Required)
+
+As a platform engineer trying to configure multiple catalog sources I want to add a second catalog provider via app-config so that entities from both sources appear in the unified catalog.
+
+_This enables multi-source catalog ingestion without code changes. Platform engineers managing heterogeneous SCM environments can consolidate all entities into one RHDH instance._
+
+h2. *Background (Required)*
+
+_Currently RHDH supports one catalog provider per instance. The multi-source catalog feature (RHDHPLAN-500, Epic RHIDP-700) requires extending the provider registration to accept multiple provider configs and merge their entities._
+
+h2. *Out of scope*
+
+_Entity conflict resolution UI — conflicts are handled by last-write-wins in this story. Custom conflict resolution is a future story._
+
+h2. *Approach (Required)*
+
+_Extend the existing CatalogBuilder to accept an array of provider configs instead of a single config. Each provider registers independently with the catalog engine. Entity merging uses the existing EntityPolicy chain — no new merge logic needed for this story._
+
+h2. *Dependencies*
+
+_Depends on RHIDP-701 (provider config schema) being merged first._
+
+(?) QE impacted work — need multi-provider test fixtures
+(?) Documentation impacted work — app-config reference update
+
+h2. *Acceptance Criteria (Required)*
+
+(?) Two providers configured in app-config both register and ingest successfully
+(?) Entities from both providers appear in catalog search results
+(?) Provider failure in one does not block the other
+(?) Existing single-provider configs continue to work without changes
+(?) documentation updates (design docs, release notes etc)
+(?) demo needed
+
+h1. *Done Checklist*
+
+(?) Code is completed, reviewed, documented and checked in
+(?) Unit and integration test automation have been delivered and running cleanly in continuous integration/staging/canary environment
+(?) Continuous Delivery pipeline(s) is able to proceed with new code included
+(?) Customer facing documentation, API docs, design docs etc. are produced/updated, reviewed and published
+(?) Acceptance criteria are met

skills/rhdh-jira/assets/examples/task-example.txt

@@ -0,0 +1,19 @@
+h1. Task Description (Required)
+
+As an engineer working on RHDH, I want to update the Renovate configuration to enable minor version Dockerfile updates so that base image security patches are not missed between releases.
+
+h2. *Background*
+
+Current Renovate rules disable minor version updates and only automerge patch versions. Over the past year, minor version bumps of the ubi9-minimal base image have been missed because they require manual intervention. This creates a growing gap between the base image in use and the latest security-patched version.
+
+h2. *Dependencies and Blockers*
+
+(?) QE impacted work — no, Renovate PRs go through existing CI
+(?) Documentation impacted work — no
+
+h2. *Acceptance Criteria*
+
+(?) Renovate config updated to allow minor version Dockerfile updates
+(?) Minor version updates create PRs without automerge (require human review)
+(?) Patch version updates continue to automerge as before
+(?) Existing Renovate behavior for non-Dockerfile dependencies is unchanged

skills/rhdh-jira/assets/templates/bug.txt

@@ -0,0 +1,17 @@
+h2. *Description of problem:*
+
+h2. *Prerequisites (if any, like setup, operators/versions):*
+
+h2. *Steps to Reproduce*
+
+ # <steps>
+
+h2. *Actual results:*
+
+h2. *Expected results:*
+
+h2. *Reproducibility (Always/Intermittent/Only Once):*
+
+h2. *Build Details:*
+
+h2. *Additional info (Such as Logs, Screenshots, etc):*

skills/rhdh-jira/assets/templates/epic.txt

@@ -0,0 +1,21 @@
+h1. EPIC Goal
+
+What are we trying to solve here?
+
+h2. *Background/Feature Origin*
+
+h2. *Why is this important?*
+
+h2. *User Scenarios*
+
+h2. *Dependencies (internal and external)*
+
+h2. *Acceptance Criteria*
+
+(?) Release Enablement/Demo - Provide necessary release enablement details and documents
+(?) DEV - Upstream code and tests merged: <link to meaningful PR or GitHub Issue>
+(?) DEV - Upstream documentation merged: <link to meaningful PR or GitHub Issue>
+(?) DEV - Downstream build attached to advisory: <link to errata>
+(?) QE - Test plans in Playwright: <link or reference to playwright>
+(?) QE - Automated tests merged: <link or reference to automated tests>
+(?) DOC - Downstream documentation merged: <link to meaningful PR>

skills/rhdh-jira/assets/templates/feature.txt

@@ -0,0 +1,39 @@
+h1. *Feature Overview (aka. Goal Summary)*
+
+An elevator pitch (value statement) that describes the Feature in a clear, concise way.
+
+<your text here>
+
+h3. *Goals (aka. expected user outcomes)*
+
+The observable functionality that the user now has as a result of receiving this feature. Include the anticipated primary user type/persona and which existing features, if any, will be expanded.
+
+<your text here>
+
+h3. *Requirements (aka. Acceptance Criteria):*
+
+A list of specific needs or objectives that a feature must deliver in order to be considered complete. If the feature spans across releases then good to have scope for each release with acceptance criteria. Be sure to include nonfunctional requirements such as security, reliability, performance, maintainability, scalability, usability, etc.
+
+<enter general Feature acceptance here>
+
+h3. *Out of Scope (Optional)*
+
+High-level list of items that are out of scope.
+
+<your text here>
+
+h3. *Customer Considerations (Optional)*
+
+Provide any additional customer-specific considerations that must be made when designing and delivering the Feature. Initial completion during Refinement status.
+
+<your text here>
+
+h3. *Documentation Considerations*
+
+Provide information that needs to be considered and planned so that documentation will meet customer needs. If the feature extends existing functionality, provide a link to its current documentation.
+
+<your text here>
+
+h3. *Upstream engagement*
+
+Review ideas/need with upstream SIGs to determine how best to interact with community