diff --git a/README.md b/README.md index 9e53ca9..2efe85d 100644 --- a/README.md +++ b/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 diff --git a/skills/rhdh-jira/SKILL.md b/skills/rhdh-jira/SKILL.md index d4cec17..892787c 100644 --- a/skills/rhdh-jira/SKILL.md +++ b/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 diff --git a/skills/rhdh-jira/assets/examples/bug-example.txt b/skills/rhdh-jira/assets/examples/bug-example.txt new file mode 100644 index 0000000..44ee40d --- /dev/null +++ b/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. diff --git a/skills/rhdh-jira/assets/examples/epic-example.txt b/skills/rhdh-jira/assets/examples/epic-example.txt new file mode 100644 index 0000000..29727e9 --- /dev/null +++ b/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 diff --git a/skills/rhdh-jira/assets/examples/feature-example.txt b/skills/rhdh-jira/assets/examples/feature-example.txt new file mode 100644 index 0000000..aa249e5 --- /dev/null +++ b/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. diff --git a/skills/rhdh-jira/assets/examples/story-example.txt b/skills/rhdh-jira/assets/examples/story-example.txt new file mode 100644 index 0000000..05c85bc --- /dev/null +++ b/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 diff --git a/skills/rhdh-jira/assets/examples/task-example.txt b/skills/rhdh-jira/assets/examples/task-example.txt new file mode 100644 index 0000000..5feda89 --- /dev/null +++ b/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 diff --git a/skills/rhdh-jira/assets/templates/bug.txt b/skills/rhdh-jira/assets/templates/bug.txt new file mode 100644 index 0000000..8d094a5 --- /dev/null +++ b/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* + + # + +h2. *Actual results:* + +h2. *Expected results:* + +h2. *Reproducibility (Always/Intermittent/Only Once):* + +h2. *Build Details:* + +h2. *Additional info (Such as Logs, Screenshots, etc):* diff --git a/skills/rhdh-jira/assets/templates/epic.txt b/skills/rhdh-jira/assets/templates/epic.txt new file mode 100644 index 0000000..49ec64d --- /dev/null +++ b/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: +(?) DEV - Upstream documentation merged: +(?) DEV - Downstream build attached to advisory: +(?) QE - Test plans in Playwright: +(?) QE - Automated tests merged: +(?) DOC - Downstream documentation merged: diff --git a/skills/rhdh-jira/assets/templates/feature.txt b/skills/rhdh-jira/assets/templates/feature.txt new file mode 100644 index 0000000..4cc08b9 --- /dev/null +++ b/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. + + + +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. + + + +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. + + + +h3. *Out of Scope (Optional)* + +High-level list of items that are out of scope. + + + +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. + + + +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. + + + +h3. *Upstream engagement* + +Review ideas/need with upstream SIGs to determine how best to interact with community diff --git a/skills/rhdh-jira/assets/templates/story.txt b/skills/rhdh-jira/assets/templates/story.txt new file mode 100644 index 0000000..f0a338c --- /dev/null +++ b/skills/rhdh-jira/assets/templates/story.txt @@ -0,0 +1,39 @@ +h1. Story (Required) + +As a trying to I want + +__ + +h2. *Background (Required)* + +__ + +h2. *Out of scope* + +__ + +h2. *Approach (Required)* + +__ + +h2. *Dependencies* + +__ + +h2. *Acceptance Criteria (Required)* + +__ + +__ + +(?) documentation updates (design docs, release notes etc) +(?) demo needed +(?) SOP required + +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 diff --git a/skills/rhdh-jira/assets/templates/task.txt b/skills/rhdh-jira/assets/templates/task.txt new file mode 100644 index 0000000..bb31a7b --- /dev/null +++ b/skills/rhdh-jira/assets/templates/task.txt @@ -0,0 +1,12 @@ +h1. Task Description (Required) + +As an engineer working on RHDH, I want to so that + +h2. *Background* + +h2. *Dependencies and Blockers* + +(?) QE impacted work +(?) Documentation impacted work + +h2. *Acceptance Criteria* diff --git a/skills/rhdh-jira/references/duplicates.md b/skills/rhdh-jira/references/duplicates.md new file mode 100644 index 0000000..b4a775a --- /dev/null +++ b/skills/rhdh-jira/references/duplicates.md @@ -0,0 +1,93 @@ +# Duplicate Detection + +Search for potentially duplicate issues before creating a new one or during refinement audits. Runs automatically — no user prompt. + +Uses GraphQL for bulk reads (skip acli). Authentication setup: see `references/auth.md`. + +## Modes + +### Pre-creation check + +Run before creating any issue. The goal is to prevent duplicates, not to find them retroactively. + +Input: proposed issue summary + project + type. + +### Audit check + +Run during refinement (`refine` Check 2). The goal is to flag existing issues that may be duplicates of each other. + +Input: an existing issue's key + summary. + +## Detection Steps + +### Step 1 — Extract keywords + +Extract 2-3 distinctive keywords from the issue summary: + +- Skip stop words (the, a, an, is, for, to, in, of, and, or, with) +- Skip project names (RHDH, Backstage, Red Hat) +- Skip generic action words (update, fix, add, remove, implement, create) +- Keep domain-specific terms (catalog, RBAC, dynamic plugins, CI/CD, operator, helm) + +If fewer than 2 distinctive keywords remain, the summary is too generic for reliable detection. Skip the check and note: "Summary too generic for duplicate detection — verify manually." + +### Step 2 — Search + +```bash +curl -s -u "$AUTH" "$GRAPHQL_URL" -X POST \ + -H 'Content-Type: application/json' \ + -H 'X-ExperimentalApi: JiraIssueSearch' \ + -d '{ + "query": "query FindDuplicates { jira { issueSearchStable(cloudId: \"'"$CLOUD_ID"'\", issueSearchInput: {jql: \"project in (RHIDP, RHDHPLAN, RHDHSUPP, RHDHBUGS) AND summary ~ \\\"KEYWORD1 KEYWORD2\\\" AND status != Closed ORDER BY updated DESC\"}, first: 10) { edges { node { key summary status { name } assignee { name } issueType { name } } } } } }" + }' +``` + +For pre-creation checks, also add `AND key != \"CURRENT_KEY\"` if comparing against an existing issue. + +For type-scoped checks, add `AND issuetype = \"TYPE\"` to narrow results (e.g., only search Features when creating a Feature). + +### Step 3 — Score overlap + +For each result, compute word overlap with the proposed/source summary: + +``` +overlap = (shared_words / max(words_in_source, words_in_candidate)) × 100 +``` + +Case-insensitive. Ignore stop words in the overlap calculation. + +### Step 4 — Classify + +| Overlap | Classification | Action | +|---------|---------------|--------| +| >80% | Likely duplicate | **Pre-creation:** "This likely already exists as {KEY}: {summary}. Use the existing issue?" **Audit:** Flag as "likely duplicate — review." | +| 40-80% | Possibly related | **Pre-creation:** "Possibly related to {KEY}: {summary}. Still create?" **Audit:** Flag as "possibly related — check for overlap." | +| <40% | Not a match | Skip silently. | + +### Step 5 — Check existing links + +Before flagging, check if a `Duplicate` issue link already exists between the two issues. If already linked, skip — it's a known duplicate. + +## Limits + +- Surface at most 3 candidates. If more than 3 match above 40%, the keywords are too generic. +- Exclude Closed issues from results (already resolved). +- Do not flag sub-tasks as duplicates of their parent (common false positive). + +## Pre-creation flow + +The duplicate check is automatic and does not prompt the user before searching. The flow: + +1. Agent prepares to create an issue +2. Run duplicate detection with the proposed summary +3. If likely duplicate found: present it and ask "Use the existing issue instead?" +4. If possibly related found: present candidates and ask "Still create?" +5. If no matches: proceed with creation silently + +## Error Handling + +| Error | Action | +|-------|--------| +| `issueSearchStable` fails | See SKILL.md Error Handling. Skip duplicate check, proceed with creation. | +| GraphQL rate limit (429) | Wait 5 seconds, retry once. If still fails, skip check and note "duplicate check skipped." | +| Summary has <2 distinctive keywords | Skip check. Note "summary too generic for duplicate detection." | diff --git a/skills/rhdh-jira/references/grill.md b/skills/rhdh-jira/references/grill.md new file mode 100644 index 0000000..48a949a --- /dev/null +++ b/skills/rhdh-jira/references/grill.md @@ -0,0 +1,161 @@ +# Grill Behavior + +Shared challenging behavior for issue creation workflows. Each caller defines its own question list — this reference defines *how* to challenge the answers. + +Load this alongside the command's type-specific questions. Apply every applicable behavior during the grill — don't skip challenges to be polite. + +## Cadence + +Ask one question at a time. Wait for the answer before asking the next. Adapt follow-ups based on what you learn. If the conversation already established context (e.g., chained from a parent issue), don't re-ask — carry it forward. + +## Field Inference + +Don't ask the user to fill in each Jira field manually. Instead, infer field values from the conversation and present a recommendation for confirmation. The grill is a conversation, not a form. + +After the grill questions are complete, present all inferred fields at once: + +> "Based on our discussion, here's what I'd set:" +> +> - **Priority**: Major — this is a functional gap, not a regression or blocker +> - **Team**: COPE — you mentioned this is in the dynamic plugins area +> - **Size**: M (3) — cross-team coordination + 4 AC items suggests ~3 sprints +> - **Component**: Plugins — primary area of change +> - **Assignee**: Allison Hill — top expertise in plugins per assign analysis +> - **Labels**: `rhdh-2.1-candidate`, `demo` — customer-facing feature targeting 2.1 +> +> "Adjust any of these? [y to confirm / list changes]" + +### Inference signals + +| Field | Infer from | +|-------|------------| +| **Priority** | Severity of the problem, customer impact, blocker language, urgency words. Default to Major unless clear signals suggest otherwise. | +| **Team** | Components mentioned, domain area, who the user is, parent issue's team, which team owns the affected code. | +| **Size** | AC count, dependency count, complexity signals from the grill ("need to investigate", "multiple PRs", "cross-team"). Cross-reference against `references/sizing.md`. | +| **Component** | Technical domain discussed (RBAC, plugins, catalog, helm, operator, CI/CD, docs). Match against known components in `references/fields.md`. Also check codebase context — if the user has been editing files during the session, infer from file paths (see below). | +| **Assignee** | If the user is describing their own work, suggest them. Otherwise, run a lightweight expertise match from the conversation context (component + domain keywords against team roster). For deep analysis, suggest running `assign`. | +| **Labels** | Customer-facing → `demo`. Release target mentioned → `rhdh-X.Y-candidate`. Stretch goal language → `stretch`. Support origin → `rhdh-customer`. | + +### Codebase-aware component inference + +If the session involved editing or reading files, use the file paths to infer the component: + +```bash +# Check recently modified files in the working tree +git diff --name-only HEAD~3 2>/dev/null | head -20 +``` + +Path-to-component signals: + +| Path pattern | Component | +|--------------|-----------| +| `plugins/catalog/`, `catalog-backend` | Catalog | +| `plugins/rbac/`, `rbac-backend` | RBAC | +| `plugins/tekton/` | Tekton | +| `plugins/topology/` | Topology | +| `plugins/lightspeed/` | Lightspeed | +| `plugins/bulk-import/` | Bulk Import | +| `packages/backend/`, `packages/app/` | Build | +| `docker/`, `Dockerfile`, `Containerfile` | Build | +| `charts/`, `helm/` | Helm | +| `docs/`, `*.md` in doc paths | Documentation | +| `e2e/`, `playwright/`, `cypress/` | Test Framework | +| `.github/`, `ci/`, `.tekton/` | CI/CD | + +This is a hint, not definitive. Present as: "You've been working in `plugins/catalog/` — setting Component to Catalog." The user can override. + +### When inference is weak + +If a field can't be inferred with reasonable confidence, say so: "I'm not sure about the team — is this COPE or Install Method?" Don't guess silently. One targeted question is better than a wrong default. + +## Challenge Behaviors + +### Challenge sizing + +After the user proposes a size (T-shirt or story points): + +- Count the acceptance criteria items. If the AC count seems high for the proposed size, push back: "You have {N} acceptance criteria items — is {size} realistic?" +- Check for cross-team dependencies. Dependencies add coordination overhead that inflates effort. +- Check for unknowns. If the user said "we need to investigate" or "not sure about," that's a spike signal — suggest time-boxing or splitting the unknown into a separate spike. +- Cross-reference against the sizing guide. Load `references/sizing.md` for T-shirt size definitions (Features/Epics) and Fibonacci story point scale (Stories/Tasks). + +### Challenge completeness + +After the user describes scope and AC: + +- **Testing**: "Does QE need to be involved? Is there a test plan or automation needed?" If the issue type is an Epic or Feature and no testing consideration was mentioned, ask. +- **Documentation**: "Does this change user-facing behavior? If so, docs need updating." If documentation wasn't mentioned for a user-facing change, flag it. +- **Upstream**: "Is there upstream Backstage work that needs to land first? Or is this purely downstream?" Don't assume — ask if not clear from context. +- **Security**: For features touching auth, RBAC, permissions, or API endpoints: "Any security considerations?" +- **Migration/Breaking changes**: "Does this change existing behavior? Will users need to update their configuration?" + +Skip challenges that clearly don't apply. Don't ask about docs for a CI pipeline task. Don't ask about upstream for a purely downstream bug fix. + +### Challenge scope + +- **Split signals**: If a single AC item is complex enough to be its own issue, say so: "This AC item — '{item}' — sounds like it could be a separate {Story/Epic}. Should we split it?" +- **Overlap**: During the duplicate check (which runs after the grill), if related issues were found, revisit scope: "This overlaps with {KEY}. Should this issue be scoped to only the non-overlapping parts?" +- **Scope creep markers**: If the user keeps adding "also it should..." or "and maybe we could..." — pause and ask: "We're growing the scope. Should some of this be a follow-up issue?" + +### Probe risks and unknowns + +- "What could go wrong with this approach?" +- "Are there any unknowns that might change the sizing?" +- "Is there a dependency on another team or external service that could block this?" +- "Has this been attempted before? If so, what happened?" + +Don't ask all four — pick the ones that are relevant based on context. For a simple Task with clear scope, skip risk probing. For a Feature with cross-team dependencies, probe harder. + +### Cross-reference existing issues + +During the grill (not just during duplicate check), search for related work: + +- If the user mentions a component, search for open issues in that component: "There are {N} open issues in {component} — any of these related?" +- If the user mentions a dependency, verify it exists in Jira: "You mentioned depending on {thing} — is that tracked as a Jira issue?" +- If a related issue is found, ask whether to add an issue link (Blocks, Depends, Related). + +Keep this lightweight. One search during the grill is enough — don't run a search after every answer. + +### Validate before creating + +Before proceeding to creation, verify the issue would pass the entry-status exit criteria from `references/workflows.md`: + +- Are all required fields for New status determined? (Assignee, Priority, Team, Component — varies by type) +- Is the description substantive enough? A one-sentence description on a Feature is a red flag. +- Is the summary clear and specific? Summaries like "Update plugins" or "Fix bug" are too vague. + +If validation fails, ask the user to fill the gap rather than creating a half-baked issue. + +## Applicability by Issue Type + +Not every behavior applies to every type. Use this as a guide: + +| Behavior | Feature | Epic | Story | Task | Bug | +|----------|---------|------|-------|------|-----| +| Challenge sizing | ✅ | ✅ | ✅ | ✅ (if SP set) | ❌ | +| Completeness: testing | ✅ | ✅ | ✅ | ❌ | ❌ | +| Completeness: docs | ✅ | ✅ | ✅ (if user-facing) | ❌ | ❌ | +| Completeness: upstream | ✅ | ✅ | ✅ | ❌ | ❌ | +| Completeness: security | ✅ | ✅ | ✅ | ✅ | ❌ | +| Completeness: migration | ✅ | ✅ | ✅ | ❌ | ❌ | +| Challenge scope | ✅ | ✅ | ✅ | ❌ | ❌ | +| Probe risks | ✅ | ✅ | ❌ | ❌ | ❌ | +| Cross-reference | ✅ | ✅ | ✅ | ✅ | ✅ | +| Validate before creating | ✅ | ✅ | ✅ | ✅ | ✅ | + +**Vulnerability** follows the Story column. Always requires Security component. + +Bugs skip most challenges — the goal is to capture the defect accurately, not challenge whether it should exist. Cross-reference and validation still apply (check for duplicates, ensure fields are set). + +Tasks skip scope/risk challenges unless they're complex (multi-day, cross-system). Use judgment. + +## Comment Suggestions + +After the issue is created, proactively suggest comments for context that emerged during the grill but doesn't belong in the description: + +- **Decision trail**: "We discussed [alternative] but chose [approach] because [reason]." +- **Elaboration**: "Additional context about [topic] that supports the decision." +- **Abandoned paths**: "Initially considered [approach], abandoned because [reason]." +- **Customer context**: "This was raised by [customer type/use case] — relevant for prioritization." + +Present each suggestion with a recommended comment text. The user approves, edits, or skips each one. diff --git a/skills/rhdh-jira/references/refine.md b/skills/rhdh-jira/references/refine.md index 02b3863..90e893e 100644 --- a/skills/rhdh-jira/references/refine.md +++ b/skills/rhdh-jira/references/refine.md @@ -65,25 +65,7 @@ For each issue, check: ### Check 2 — Duplicate Detection -For each issue, search for potential duplicates: - -```bash -# Search by similar summary keywords -curl -s -u "$AUTH" "$GRAPHQL_URL" -X POST \ - -H 'Content-Type: application/json' \ - -H 'X-ExperimentalApi: JiraIssueSearch' \ - -d '{ - "query": "query FindDuplicates { jira { issueSearchStable(cloudId: \"'"$CLOUD_ID"'\", issueSearchInput: {jql: \"project in (RHIDP, RHDHPLAN, RHDHSUPP, RHDHBUGS) AND summary ~ \\\"KEYWORD1 KEYWORD2\\\" AND key != \\\"CURRENT_KEY\\\" AND status != Closed ORDER BY updated DESC\"}, first: 10) { edges { node { key summary status { name } assignee { name } } } } } }" - }' -``` - -Extract 2-3 distinctive keywords from the issue summary (skip stop words, project names, and generic terms like "update", "fix", "add"). If the search returns issues with high summary similarity: - -- **Exact match** (>80% word overlap): Flag as "likely duplicate — review before proceeding." -- **Partial match** (40-80%): Flag as "possibly related — check for overlap." -- **Low match** (<40%): Skip. - -Also check existing issue links for `Duplicate` link type — if already linked, note it and skip. +Run the audit check from `references/duplicates.md` for each issue. Flag likely and possibly related duplicates in the report. ### Check 3 — Parent/Hierarchy Integrity diff --git a/skills/rhdh-jira/references/sizing.md b/skills/rhdh-jira/references/sizing.md new file mode 100644 index 0000000..1335e36 --- /dev/null +++ b/skills/rhdh-jira/references/sizing.md @@ -0,0 +1,72 @@ +# Sizing Guide + +T-shirt sizing for Features and Epics, Fibonacci story points for Stories/Tasks. Use during issue creation grills and refinement to validate sizing. + +## Feature Sizing (RHDHPLAN) + +T-shirt size set via the `Size` field (`customfield_10795`). + +| Size | Points | Effort | Notes | +|------|--------|--------|-------| +| **XS** | 1 | <30% of release (~2 development sprints) | Possibly should be an Epic | +| **S** | 2 | 30-60% of release (~2-3 development sprints) | | +| **M** | 3 | 60-90% of release (~3-4 development sprints) | | +| **L** | 4 | 90%+ of release (~4+ development sprints) | | +| **XL** | 5 | Whole release (~5 full development sprints) | Likely too big — split or create Outcome | + +If multiple L or XL Epics exist within a Feature, the Feature scope may need to be reassessed. + +## Epic Sizing (RHIDP) + +T-shirt size set via the `Size` field (`customfield_10795`). + +| Size | Points | Effort | Notes | +|------|--------|--------|-------| +| **XS** | 1 | ~1 sprint | Possibly should be a Story-sized issue | +| **S** | 2 | ~2 sprints | | +| **M** | 3 | ~3 sprints | | +| **L** | 4 | ~4 sprints | | +| **XL** | 5 | ~5 sprints | Likely too big — split or create Feature | + +## Story/Task Sizing (RHIDP) + +Story points set via `customfield_10028`. Uses Fibonacci scale. + +| Points | Scope | Effort | Complexity | +|--------|-------|--------|------------| +| **1** | Extremely narrow: short AC, simple change, no/simple docs, may update existing tests | Few hours to 1 day | Little | +| **2** | Very narrow: short AC, simple changes, short docs, may add new test cases | 1-2 days | Little | +| **3** | Narrow: multiple/branched AC, new unit/integration tests, demo required, small doc updates | 3-5 days | Low | +| **5** | Broader: possibly new functionality, long/multiple PRs, affects multiple codebase areas, significant doc updates | 5-7 days | Medium | +| **8** | Very broad: may require research, new functionality, may work with external libraries, multiple codebase areas | Up to a sprint | High | +| **13** | Unbound scope: unknown PRs, interconnected AC branches, requires external team review | Not known | Very high | + +**13-point stories should be split.** If the scope is unbound, consider breaking into smaller stories or creating a spike to reduce unknowns first. + +## RHDHSUPP Sizing (Support Cases) + +Story points for support interaction tracking. Different from engineering sizing — measures investigation and communication effort. + +| Points | Scope | Time Spent | +|--------|-------|------------| +| **1** | Minimal investigation, minimal communication, quick solution | Few hours to 1 day | +| **2** | Some investigation, moderate communication, solution found quickly | 1-2 days | +| **3** | Moderately complex, in-depth investigation, time on understanding customer requirements | 2-4 days | +| **5** | Complex, possibly multi-team, extensive back-and-forth to reproduce | 4 days to 1 week | +| **8** | Highly complex, extensive research and collaboration, long-term solution needed | More than a week | +| **13** | Unbound: sitting unresolved, multiple back-and-forth with customer, too much time reproducing | Not known | + +Support issues may result in follow-up RFE (RHDHPLAN) or product defect (RHDHBUGS) after investigation. + +## Sizing Signals During Grill + +Use these to challenge sizing during issue creation: + +| Signal | Challenge | +|--------|-----------| +| AC count > 5 on a 3-point story | "That's a lot of acceptance criteria for 3 points — is this really a 3?" | +| Cross-team dependencies on a Small feature | "Cross-team coordination adds overhead — should this be Medium?" | +| "We need to investigate" in a Story | "This sounds like unknowns — should this be a spike first?" | +| XL Epic or Feature | "This is the largest size — can it be split into smaller deliverables?" | +| 13-point Story | "Unbound scope — split into smaller stories or create a spike to reduce unknowns." | +| XS Feature | "This might be small enough to be an Epic directly — does it need Feature-level tracking?" | diff --git a/skills/rhdh-jira/references/templates.md b/skills/rhdh-jira/references/templates.md index c4f3eaa..b1788a7 100644 --- a/skills/rhdh-jira/references/templates.md +++ b/skills/rhdh-jira/references/templates.md @@ -1,237 +1,54 @@ # Issue Templates -Jira wiki markup templates for each issue type. Use with `--description` or `--description-file` when creating issues via `acli jira workitem create`. +Jira wiki markup templates for each issue type. Each template lives in its own file under `assets/templates/`. Filled-in examples are under `assets/examples/`. -## Outcome Template +## Template Files -Project: RHDHPLAN | Type: Outcome +| Issue Type | Project | Template | Example | +|------------|---------|----------|---------| +| Feature | RHDHPLAN | `assets/templates/feature.txt` | `assets/examples/feature-example.txt` | +| Epic | RHIDP | `assets/templates/epic.txt` | `assets/examples/epic-example.txt` | +| Story | RHIDP | `assets/templates/story.txt` | `assets/examples/story-example.txt` | +| Task | RHIDP | `assets/templates/task.txt` | `assets/examples/task-example.txt` | +| Bug | RHDHBUGS | `assets/templates/bug.txt` | `assets/examples/bug-example.txt` | -``` -h3. *Description:* - -_Provide a quick overview of the goal and key background or context._ - - -h3. *Benefits/Value:* - -_What are the benefits or value for our customers if we do this?_ - * - -h3. *Acceptance Criteria:* - -_What must be true for this to be considered complete?_ - * - -h3. *Out of Scope:* - -_If there are significant scope constraints, note them so goals and non-goals are clear._ - * - -h3. *Metrics:* - -_What metrics and telemetry data influence this and either help inform this work, or could help us understand its impact?_ - * - -h3. *Dependencies:* - -_Note any major team or technology dependencies outside of our direct control that we may need to plan around._ - * -``` - -## Feature Template - -Project: RHDHPLAN | Type: Feature - -``` -h1. *Feature Overview (aka. Goal Summary)* - -An elevator pitch (value statement) that describes the Feature in a clear, concise way. - - - -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. - - - -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. - - - -h3. *Out of Scope (Optional)* - -High-level list of items that are out of scope. +Load the template file for the issue type being created. Read the example file for tone and detail calibration. - - -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. - - - -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. - - - -h3. *Upstream engagement* - -Review ideas/need with upstream SIGs to determine how best to interact with community -``` - -## Epic Template - -Project: RHIDP | Type: Epic - -``` -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: -(?) DEV - Upstream documentation merged: -(?) DEV - Downstream build attached to advisory: -(?) QE - Test plans in Playwright: -(?) QE - Automated tests merged: -(?) DOC - Downstream documentation merged: -``` - -## Story Template - -Project: RHIDP | Type: Story - -``` -h1. Story +## Usage -As a user of RHDH, I want to so that - -h2. *Background* - -h2. *Dependencies and Blockers* -(?) QE impacted work -(?) Documentation impacted work - -h2. *Acceptance Criteria* -(?) upstream documentation updates (design docs, release notes etc) -(?) Technical enablement / Demo -``` - -## Task Template - -Project: RHIDP | Type: Task - -``` -h1. Task - -As an engineer working on RHDH, I want to so that - -h2. *Background* - -h2. *Dependencies and Blockers* -(?) QE impacted work -(?) Documentation impacted work - -h2. *Acceptance Criteria* -``` - -## Bug Template - -Project: RHDHBUGS | Type: Bug - -``` -h2. *Description of problem:* - -h2. *Prerequisites (if any, like setup, operators/versions):* - -h2. *Steps to Reproduce* - # - -h2. *Actual results:* - -h2. *Expected results:* - -h2. *Reproducibility (Always/Intermittent/Only Once):* - -h2. *Build Details:* - -h2. *Additional info (Such as Logs, Screenshots, etc):* -``` - -**Important for support-originated bugs:** Do not include any customer-related information in RHDHBUGS issues. RHDHBUGS is a public project. Customer details stay in RHDHSUPP. - -## Feature Request Template - -Project: RHDHPLAN | Type: Feature Request - -``` -h1. Requested Feature Overview (aka. Goal Summary) - -An elevator pitch (value statement) that describes the desired Feature in a clear, concise way. - - - -h3. Goals (aka. expected user outcomes) - -The observable functionality that the user would have as a result of receiving this feature. Include the anticipated primary user type/persona. - - - -h3. Requirements (aka. Acceptance Criteria): - -A list of specific needs, objectives, or user stories that must be delivered in order to be considered complete. - - - -h3. Out of Scope (Optional) - -High-level list of items that are out of scope. - - - -h3. Customer Considerations (Optional) - -Provide any additional customer-specific considerations that must be made when designing and delivering the Feature. - - -``` - -## Usage Example - -Save a template to a file and create the issue: +Save a filled-in template to a temp file, then create the issue: ```bash -# Write template to file, fill in details -cat > epic.txt << 'EOF' +# Write filled template to file +cat > issue-desc.txt << 'EOF' h1. EPIC Goal -Implement SSO integration for RHDH admin console. -h2. *Background/Feature Origin* -Customer requests for enterprise SSO support. -h2. *Acceptance Criteria* -(?) DEV - SSO login flow working with OIDC providers -(?) QE - E2E tests for SSO login/logout -(?) DOC - Admin guide updated with SSO configuration steps +Implement SSO integration for admin console. +... EOF # Create the issue acli jira workitem create --project RHIDP --type Epic \ --summary "SSO Integration for Admin Console" \ - --description-file epic.txt \ + --description-file issue-desc.txt \ --assignee "@me" \ - --label "must-have" + --yes ``` + +## Field Requirements at Creation + +Load `references/workflows.md` for full exit criteria per status. Key fields at creation (New status): + +| Issue Type | Required Fields | +|------------|----------------| +| Feature | Assignee, Priority, Team | +| Epic | Assignee, Team, Priority, Component | +| Story | Assignee, Priority, Component | +| Task | Assignee, Priority, Component | +| Bug | Description (steps to reproduce), Priority | + +## Notes + +- **Feature Request** and **Outcome** templates exist in RHDHPLAN but are not used by the creation sub-commands. See `references/support.md` for Feature Request creation from support cases. +- **Bugs go to RHDHBUGS**, not RHIDP. Do not include customer information in RHDHBUGS — it's a public project. +- **Spikes** use the Task template with a `SPIKE:` prefix in the summary and a time-boxed story point estimate. +- **Sub-tasks** are created as children of an existing issue, not standalone. Use `acli jira workitem create --parent KEY` for sub-tasks. diff --git a/skills/rhdh-jira/references/to-epic.md b/skills/rhdh-jira/references/to-epic.md new file mode 100644 index 0000000..90dcd4d --- /dev/null +++ b/skills/rhdh-jira/references/to-epic.md @@ -0,0 +1,141 @@ +# Create Epic + +Create an RHIDP Epic from conversation context. Grills the user on delivery scope, dependencies, and acceptance criteria. Optionally chains into Story/Task decomposition. + +## Workflow + +### Step 1 — Determine Context + +Two entry modes: + +- **Chained from Feature**: Context carries down. The Feature's scope, AC, and customer considerations are established. The grill narrows to delivery scope for this team. +- **Standalone**: Full grill. No parent Feature context. + +If chained, the parent Feature key is known. If standalone, ask: "Is this Epic part of an existing Feature? [Feature key / no]" + +### Step 2 — Draft from Context + +Load `assets/templates/epic.txt` for structure and `assets/examples/epic-example.txt` for tone calibration. + +Synthesize: Draft as many template sections as possible from the conversation (and parent Feature if chained): + +- EPIC Goal, Background/Feature Origin, Why important, User Scenarios, Dependencies, AC + +If chained from a Feature, pre-fill: Goal (scoped to this team's delivery), Background (link to parent Feature), Dependencies (other Epics in the Feature). + +Present the draft: "Here's what I have for this Epic. Review and tell me what's missing." + +### Step 3 — Fill Gaps + +For unfilled sections, ask targeted questions. Adapt based on entry mode: + +**Chained (narrowed):** + +1. **EPIC Goal** — what does *this team's* delivery achieve within the parent Feature? +2. **Dependencies** — internal (other Epics) and external (upstream, other teams) +3. **Acceptance Criteria** — team-specific. Which checklist items apply? (DEV, QE, DOC) + +**Standalone (full):** + +1. **EPIC Goal** — what are we trying to solve? +2. **Background/Feature Origin** — where did this come from? +3. **Why is this important?** +4. **User Scenarios** — who benefits and how? +5. **Dependencies** — internal and external +6. **Acceptance Criteria** — full checklist + +Skip questions the draft already answered. + +### Step 4 — Challenge + +Follow the challenging behavior in `references/grill.md`. + +### Step 5 — Infer Fields + +Infer all Jira fields per `references/grill.md` Field Inference. If chained, inherit Priority and Team from parent Feature. Key fields: Team, Priority, Size (T-shirt), Component, Assignee (Epic Owner). + +### Step 6 — Review + +Render the filled template and inferred fields as a temporary markdown file for user review: + +```bash +cat > /tmp/epic-review.md << 'EOF' +## Epic: {summary} + +### Description +{filled template content} + +### Fields +- **Priority**: {value} +- **Team**: {value} +- **Size**: {value} +- **Component**: {value} +- **Assignee**: {value} +EOF +``` + +Present to the user: "Review the Epic before creating. [approve / edit / cancel]" + +### Step 7 — Duplicate Check + +Run the pre-creation check from `references/duplicates.md`. Search RHIDP Epics (`issuetype = Epic`). + +### Step 8 — Create Epic + +Fill the template. Create the issue: + +```bash +acli jira workitem create --project RHIDP --type Epic \ + --summary "Epic summary" \ + --description-file /tmp/epic-desc.txt \ + --assignee "ACCOUNT_ID" \ + --priority "Major" \ + --component "Plugins" \ + --yes +``` + +If a parent Feature exists, link via REST: + +```bash +curl -s -X PUT -u "$AUTH" -H "Content-Type: application/json" \ + -d '{"fields": {"parent": {"key": "RHDHPLAN-XXX"}}}' \ + "https://redhat.atlassian.net/rest/api/3/issue/RHIDP-XXX" +``` + +Set Team and Size via REST — follow API preference order in SKILL.md. + +### Step 9 — Comments + +Follow the comment suggestion behavior from `references/grill.md` — proactively suggest decision trail, elaboration, and abandoned paths as comments. + +Add via `acli jira workitem comment --key RHIDP-XXX --comment "text" --yes`. + +### Step 10 — Chain Decomposition + +After the Epic is created: + +> "Break this Epic into Stories/Tasks? [y/N]" + +If yes: + +1. Discuss the breakdown: what are the deliverable slices? +2. For each slice, invoke the `to-issue` workflow with context carried down: + - The Epic's goal, AC, and dependencies are established + - The issue grill narrows to: implementation specifics, story points, approach +3. Each Story/Task is automatically linked to the parent Epic via `parent` field +4. Type inference runs per slice (Story if user-facing, Task if internal) + +## Error Handling + +| Error | Action | +|-------|--------| +| RHIDP project inaccessible | Stop. User lacks project access. | +| Parent Feature key invalid | Warn. Create Epic without parent link. | +| `acli create` fails | Fall back to REST API. | +| Parent link update fails | Report failure. Epic is created — user can link manually. | + +## Caveats + +1. **Epic Owner responsibility.** The assignee is the Epic Owner — single point of contact for delivery, works with the Feature Owner to align execution. +2. **Component is required at New status.** Don't skip this during the grill. See `references/fields.md` for the component list. +3. **Multi-team Features create multiple Epics.** When chained from a Feature, each team gets its own Epic. The Feature Owner coordinates across them. diff --git a/skills/rhdh-jira/references/to-feature.md b/skills/rhdh-jira/references/to-feature.md new file mode 100644 index 0000000..41c8b62 --- /dev/null +++ b/skills/rhdh-jira/references/to-feature.md @@ -0,0 +1,133 @@ +# Create Feature + +Create a RHDHPLAN Feature from conversation context. Grills the user on scope, customer value, and acceptance criteria before creating. Optionally chains into Epic decomposition. + +## Workflow + +### Step 1 — Draft from Context + +Load `assets/templates/feature.txt` for structure and `assets/examples/feature-example.txt` for tone calibration. + +Before asking questions, review what the conversation already established. Draft as many template sections as possible from existing context: + +- Feature Overview, Goals, AC, Out of Scope, Customer Considerations, Documentation, Upstream engagement + +Present the draft: "Based on our conversation, here's what I have so far. Review and tell me what's missing or wrong." + +### Step 2 — Fill Gaps + +For any template sections the agent couldn't fill from context, ask targeted questions (one at a time): + +1. **Feature Overview** — what is this? Elevator pitch. +2. **Goals** — what does the user get? Which persona benefits? +3. **Requirements / Acceptance Criteria** — what must be true for this to be complete? Include non-functional requirements. +4. **Out of Scope** — what is explicitly NOT included? +5. **Customer Considerations** — any customer-specific context? +6. **Documentation Considerations** — what docs need creating/updating? +7. **Upstream engagement** — does this need Backstage community alignment? + +Skip questions the draft already answered well. + +### Step 3 — Challenge + +Follow the challenging behavior in `references/grill.md` on the completed draft. + +### Step 4 — Infer Fields + +Infer all Jira fields from the conversation per the Field Inference section in `references/grill.md`. Present recommendations for confirmation. Key fields for Features: Priority, Team, Size (T-shirt), Assignee (Feature Owner), and Labels (`demo`, `rhdh-X.Y-candidate`, `stretch`). + +### Step 5 — Review + +Render the filled template and inferred fields as a temporary markdown file for user review: + +```bash +# Save to temp file +cat > /tmp/feature-review.md << 'EOF' +## Feature: {summary} + +### Description +{filled template content} + +### Fields +- **Priority**: {value} — {rationale} +- **Team**: {value} +- **Size**: {value} — {rationale} +- **Assignee**: {value} +- **Labels**: {values} +EOF +``` + +Present to the user: "Review the Feature before creating. Edit the file or tell me what to change. [approve / edit / cancel]" + +- **approve** — proceed to duplicate check and creation +- **edit** — user modifies the file or provides changes verbally, agent updates +- **cancel** — abort creation + +### Step 6 — Duplicate Check and Feature Request Link + +Before creating, run the pre-creation check from `references/duplicates.md` using the proposed summary. Search RHDHPLAN Features specifically (`issuetype = Feature`). + +Also search for accepted Feature Requests that this Feature may originate from: + +```bash +jql: "project = RHDHPLAN AND issuetype = 'Feature Request' AND status = Accepted AND summary ~ \"KEYWORD1 KEYWORD2\"" +``` + +If a matching Feature Request is found: "Found accepted Feature Request {KEY}: {summary}. Link this Feature to it?" If yes, add a `Related` issue link after creation. + +If a likely duplicate Feature is found, present it and ask: "This may already exist as {KEY}: {summary}. Use the existing issue instead?" + +### Step 7 — Create Feature + +Fill the template with grill results. Save to a temp file. Create the issue: + +```bash +acli jira workitem create --project RHDHPLAN --type Feature \ + --summary "Feature summary" \ + --description-file /tmp/feature-desc.txt \ + --assignee "ACCOUNT_ID" \ + --priority "Major" \ + --label "rhdh-2.1-candidate" \ + --yes +``` + +Set additional fields via REST if needed (Team, Size) — follow API preference order in SKILL.md. + +### Step 8 — Comments + +Follow the comment suggestion behavior from `references/grill.md` — proactively suggest decision trail, elaboration, and abandoned paths as comments. + +Add each approved comment via: + +```bash +acli jira workitem comment --key RHDHPLAN-XXX --comment "comment text" --yes +``` + +### Step 9 — Chain Decomposition + +After the Feature is created: + +> "Break this Feature into Epics? The RHDH process typically creates Epics per team (Eng, QE, Doc). [y/N]" + +If yes: + +1. Ask: "Which teams are involved?" Default suggestion: Eng + Doc (QE is often covered within the Eng epic). +2. For each team, invoke the `to-epic` workflow with context carried down from this Feature: + - The Feature's scope, AC, and customer considerations are established — don't re-grill on these + - The Epic grill narrows to: delivery scope for *this team*, dependencies, team-specific AC +3. Each Epic is automatically linked to the parent Feature via `parent` field + +## Error Handling + +| Error | Action | +|-------|--------| +| RHDHPLAN project inaccessible | Stop. User lacks project access. | +| `acli create` fails | Fall back to REST API. See SKILL.md Error Handling. | +| Duplicate check finds match | Present match. If user confirms duplicate, open existing issue instead. | +| Team field update fails via acli | Fall back to REST. See `references/rest-api-fallback.md`. | + +## Caveats + +1. **Feature Owner responsibility.** Creating a Feature implies ownership. Ensure the assignee understands the Feature Owner responsibilities defined in the RHDH Agile Workflow (single point of contact, coordinates cross-team dependencies, ensures sizing and labels). +2. **Candidate label convention.** The label format is `rhdh-X.Y-candidate` (e.g., `rhdh-2.1-candidate`). Ask which release this targets during the grill. +3. **Description stays structured.** Only template sections go in the description. Decision trail, elaboration, and abandoned approaches go in comments. diff --git a/skills/rhdh-jira/references/to-issue.md b/skills/rhdh-jira/references/to-issue.md new file mode 100644 index 0000000..8a10e95 --- /dev/null +++ b/skills/rhdh-jira/references/to-issue.md @@ -0,0 +1,180 @@ +# Create Issue + +Create a Story, Task, Bug, or Spike from conversation context. Automatically infers the issue type based on what's being described. Leaf node in the hierarchy — no further decomposition offered. + +## Workflow + +### Step 1 — Determine Context + +Two entry modes: + +- **Chained from Epic**: Context carries down. The Epic's goal, AC, and dependencies are established. The grill narrows to implementation specifics. +- **Standalone**: Full grill. No parent Epic context. + +If chained, the parent Epic key is known. If standalone, ask: "Is this part of an existing Epic? [Epic key / no]" + +### Step 2 — Type Inference + +Determine the issue type from the conversation context: + +| Signal | Type | Project | Notes | +|--------|------|---------|-------| +| User-facing behavior change, UI, API contract | **Story** | RHIDP | Uses Story template | +| Internal: CI, refactoring, tooling, tests, infra | **Task** | RHIDP | Uses Task template | +| Something is broken, regression, unexpected behavior | **Bug** | RHDHBUGS | Uses Bug template. **Do not include customer information — RHDHBUGS is public.** | +| Bug from a support case | **Bug** | RHDHSUPP | Uses Bug template. Support-originated — link to customer case. See `references/support.md`. | +| CVE, vulnerability, security advisory | **Vulnerability** | RHIDP | Requires Security component. Uses Story template and grill questions. | +| "Investigate", "research", "spike", "explore", "POC", unknown scope | **Task** (spike) | RHIDP | Summary prefixed with `SPIKE:`. Requires time-boxed story points. | + +Confirm the inference with the user: "This sounds like a {type}. Correct?" + +If the user disagrees, adjust. Additional disambiguation questions: + +- Story vs Task: "Is this user-facing (Story) or internal engineering work (Task)?" +- Bug project: "Is this from a support case? (RHDHSUPP) Or a product defect? (RHDHBUGS)" +- Vulnerability: "Is this a CVE or security advisory? (Vulnerability in RHIDP with Security component)" + +### Step 3 — Draft from Context + +Load the appropriate template and example from `assets/templates/` and `assets/examples/` (see `references/templates.md` for the mapping). + +Synthesize: Draft as many template sections as possible from the conversation (and parent Epic if chained). If chained, pre-fill Background (link to parent Epic) and Dependencies. + +Present the draft: "Here's what I have. Review and tell me what's missing." + +### Step 4 — Fill Gaps + +For unfilled sections, ask targeted questions based on the inferred type: + +**Story gaps:** + +1. **User story** — "As a \ trying to \ I want \" +2. **Background** — context and motivation +3. **Out of scope** — what's not included +4. **Approach** — general technical path, schemas, class definitions +5. **Dependencies** — linked Stories/Epics, QE/Doc impact +6. **Acceptance Criteria** — edge cases, minimum test list, docs/demo/SOP needs + +**Task gaps:** + +1. **Task description** — what needs to happen and why +2. **Background** — context if not obvious +3. **Dependencies and Blockers** — QE/Doc impact +4. **Acceptance Criteria** — what does "done" look like + +**Bug gaps:** + +1. **Description of problem** — what's wrong +2. **Prerequisites** — setup, versions, operators +3. **Steps to Reproduce** — numbered steps +4. **Actual results** — what happens +5. **Expected results** — what should happen +6. **Reproducibility** — Always/Intermittent/Only Once +7. **Build Details** — version, environment +8. **Additional info** — logs, screenshots + +**Spike gaps:** + +1. **What are we investigating?** — the question to answer +2. **Why?** — what decision depends on this research +3. **Time-box** — "How many story points to allocate?" (required for spikes) +4. **Expected output** — what deliverable closes this spike (doc, ADR, prototype, go/no-go recommendation) + +Skip questions the draft already answered. + +### Step 5 — Challenge + +Follow the challenging behavior in `references/grill.md`. + +### Step 6 — Infer Fields + +Infer all Jira fields per `references/grill.md` Field Inference. If chained, inherit Priority, Team, and Component from parent Epic. Key fields: Priority, Component, Assignee, and Story Points (required for Spikes as time-box). + +### Step 7 — Review + +Render the filled template and inferred fields as a temporary markdown file for user review: + +```bash +cat > /tmp/issue-review.md << 'EOF' +## {Type}: {summary} + +### Description +{filled template content} + +### Fields +- **Type**: {inferred type} +- **Project**: {project} +- **Priority**: {value} +- **Component**: {value} +- **Assignee**: {value} +- **Story Points**: {value} +EOF +``` + +Present to the user: "Review the issue before creating. [approve / edit / cancel]" + +### Step 8 — Duplicate Check + +Run the pre-creation check from `references/duplicates.md`. Scope to the target project and type. + +### Step 9 — Create Issue + +Fill the template. Create the issue: + +```bash +# Story +acli jira workitem create --project RHIDP --type Story \ + --summary "Story summary" \ + --description-file /tmp/story-desc.txt \ + --assignee "ACCOUNT_ID" \ + --priority "Major" \ + --component "Plugins" \ + --yes + +# Bug (different project) +acli jira workitem create --project RHDHBUGS --type Bug \ + --summary "Bug summary" \ + --description-file /tmp/bug-desc.txt \ + --priority "Critical" \ + --yes + +# Spike (Task with prefix) +acli jira workitem create --project RHIDP --type Task \ + --summary "SPIKE: Research multi-source catalog merging" \ + --description-file /tmp/spike-desc.txt \ + --assignee "ACCOUNT_ID" \ + --priority "Major" \ + --component "Plugins" \ + --yes +``` + +If a parent Epic exists, link via REST: + +```bash +curl -s -X PUT -u "$AUTH" -H "Content-Type: application/json" \ + -d '{"fields": {"parent": {"key": "RHIDP-XXX"}}}' \ + "https://redhat.atlassian.net/rest/api/3/issue/RHIDP-YYY" +``` + +Set Story Points via REST if acli fails — follow API preference order in SKILL.md. + +### Step 10 — Comments + +Follow the comment suggestion behavior from `references/grill.md` — proactively suggest decision trail, elaboration, and abandoned paths as comments. + +## Error Handling + +| Error | Action | +|-------|--------| +| RHIDP/RHDHBUGS project inaccessible | Stop. User lacks project access. | +| Type inference ambiguous | Ask the user directly. | +| `acli create` fails | Fall back to REST API. | +| Parent Epic link fails | Report failure. Issue is created — user can link manually. | +| Spike without time-box | Do not create. Ask: "Spikes require a time-box. How many story points?" | + +## Caveats + +1. **Bugs go to RHDHBUGS.** Never create Bugs in RHIDP. RHDHBUGS is a public project — no customer information in the description. +2. **Spikes are Tasks, not a separate type.** Identified by the `SPIKE:` prefix in the summary. Always time-boxed. +3. **No further decomposition.** Stories, Tasks, and Bugs are leaf nodes. If the scope is too large for a single issue, suggest splitting into multiple issues or promoting to an Epic. +4. **Done Checklist.** Stories include a Done Checklist in the template. Remind the user this is part of the definition of done. diff --git a/skills/rhdh-jira/references/update-jira-status.md b/skills/rhdh-jira/references/update-jira-status.md new file mode 100644 index 0000000..cdbbadf --- /dev/null +++ b/skills/rhdh-jira/references/update-jira-status.md @@ -0,0 +1,195 @@ +# Update Jira Status + +Update a Jira issue with the current session's progress. Detects the related issue, adds a status comment summarizing the session, and proposes status transitions. Checks upward through the hierarchy and suggests parent transitions when all siblings are complete. + +On-demand — run when you're at a natural stopping point. + +Authentication setup: see `references/auth.md`. All examples below assume `AUTH`, `CLOUD_ID`, and `GRAPHQL_URL` are set per that file. + +## Workflow + +### Step 1 — Detect Related Issue + +Search for the Jira issue related to the current session. Check in priority order — stop at the first match: + +1. **Conversation context** — scan for issue keys mentioned in the conversation (RHIDP-1234, RHDHPLAN-567, RHDHBUGS-890) +2. **Git branch name** — parse the current branch for an issue key pattern: + + ```bash + git branch --show-current 2>/dev/null | grep -oE '(RHIDP|RHDHPLAN|RHDHBUGS|RHDHSUPP)-[0-9]+' + ``` + +3. **PR title/description** — if a PR exists for the current branch, check its title: + + ```bash + gh pr view --json title,body 2>/dev/null + ``` + +4. **Recent commits** — scan commit messages on the current branch: + + ```bash + git log --oneline -10 2>/dev/null | grep -oE '(RHIDP|RHDHPLAN|RHDHBUGS|RHDHSUPP)-[0-9]+' + ``` + +5. **Keyword search** — if no key found, extract topic keywords from the conversation and search Jira: + + ```bash + jql: "project in (RHIDP, RHDHPLAN, RHDHSUPP, RHDHBUGS) AND summary ~ \"KEYWORD1 KEYWORD2\" AND status != Closed AND assignee = currentUser() ORDER BY updated DESC" + ``` + + Present candidates: "I found these possibly related issues — which one?" + +If multiple distinct keys are found, ask: "This session touches multiple issues: {keys}. Which one(s) to update?" + +If no match at all: "No related issue found. Want to create one?" → route to the appropriate creation command. + +### Step 2 — Fetch Current Issue State + +Query the issue to understand its current state: + +```bash +acli jira workitem view ISSUE_KEY --json +``` + +Or via GraphQL for richer data (components, sprint, parent): + +```bash +curl -s -u "$AUTH" "$GRAPHQL_URL" -X POST \ + -H 'Content-Type: application/json' \ + -d '{ + "query": "query IssueState { jira { issueByKey(key: \"ISSUE_KEY\", cloudId: \"'"$CLOUD_ID"'\") { key summary status { name } issueType { name } priority { name } assignee { name accountId } storyPoints parentIssue { key summary status { name } } fields { edges { node { __typename name ... on JiraSprintField { selectedSprintsConnection { edges { node { name state } } } } } } } } } }" + }' +``` + +Note the current status — this determines which transitions are available. + +### Step 3 — Compose Status Comment + +Summarize the current session's progress as a short status comment. The comment should be: + +- **Concise** — 2-5 sentences. Not a full session log. +- **Actionable** — what was done, what's the current state, what's next (if applicable) +- **Factual** — avoid subjective assessments. State what happened. + +Templates by situation: + +**Work in progress:** +> "Started implementation. [Approach/what was done]. Next: [what remains]." + +**Hit a blocker:** +> "Blocked on [dependency/issue]. [What was tried]. Waiting for [person/resolution]." + +**Implementation complete, PR up:** +> "Implementation complete. PR: [link]. [Brief description of changes]." + +**PR merged:** +> "PR merged and verified. [Any follow-up needed]." + +**Abandoned approach:** +> "Investigated [approach]. Abandoned because [reason]. Switching to [alternative]." + +**Scope discovery:** +> "Investigation revealed [finding]. Scope is [larger/smaller/different] than expected. [Recommendation]." + +Confirm the comment with the user before posting: + +> "Proposed status comment:\n\n{comment}\n\nPost this? [y/N/edit]" + +Add via: + +```bash +acli jira workitem comment --key ISSUE_KEY --comment "comment text" --yes +``` + +### Step 4 — Propose Status Transition + +Based on session activity, propose a transition if applicable. Load `references/workflows.md` for exit criteria at the target status. + +| Session activity | Proposed transition | +|-----------------|-------------------| +| Started working | New/To Do → In Progress | +| PR up for review | In Progress → Review | +| PR merged | Review → Closed | +| All work done, awaiting release | In Progress/Review → Release Pending | +| Descoped / won't fix | Any → Closed (with resolution + comment per Team Conventions in SKILL.md) | + +Before proposing a transition, verify exit criteria are met for the target status. If not, flag what's missing: "To move to Review, you need: [missing fields]. Set them first?" + +**Check for Jira automation.** Before suggesting a parent transition in Step 6, fetch the parent's current status first. Jira automation rules may have already cascaded the transition (e.g., child moving to In Progress automatically moves parent Epic to In Progress). If the parent already transitioned, skip the suggestion. + +If no transition is applicable, skip this step silently. + +Confirm with the user: + +> "Move {KEY} from {current} to {target}? [y/N]" + +Apply via: + +```bash +acli jira workitem transition --key ISSUE_KEY --status "TARGET" --yes +``` + +### Step 5 — Propose Issue Links + +If the session revealed dependencies or related issues not yet tracked: + +- "You mentioned {KEY2} is blocking this — add a Blocks link?" +- "You discovered {KEY3} is related — add a Related link?" + +Add via: + +```bash +acli jira workitem link create --key ISSUE_KEY --link-type "Blocks" --target-key TARGET_KEY --yes +``` + +### Step 6 — Upward Cascade Check + +After updating the issue, check if parent issues should transition too. One level at a time, each with confirmation. + +If the issue has no `parentIssue` in the Step 2 response, skip the cascade check entirely. + +**Check parent Epic:** + +Query siblings of the updated issue: + +```bash +jql: "parent = {epic_key}" +``` + +If ALL siblings are in a terminal status for their type — Closed for Stories/Tasks, Closed or Release Pending for Bugs: +> "All stories under {epic_key} ({epic_summary}) are complete. Transition Epic to Dev Complete? [y/N]" + +If the user confirms, transition the Epic. Add a status comment: "All child issues complete. Transitioning to Dev Complete." + +**Check parent Feature:** + +If the Epic was transitioned, query sibling Epics of the parent Feature: + +```bash +jql: "parent = {feature_key} AND issuetype = Epic" +``` + +If ALL sibling Epics are in Release Pending or Closed (Dev Complete is not sufficient — Epics still need Release Notes fields and demo links): +> "All Epics under {feature_key} ({feature_summary}) are complete. The Feature Owner is {owner}. Recommend reaching out to {owner} to transition the Feature to Release Pending." + +Do not transition the Feature directly — that's the Feature Owner's responsibility. Suggest reaching out instead. + +## Error Handling + +| Error | Action | +|-------|--------| +| No issue detected | Offer keyword search. If no match, suggest creating an issue. | +| `git` not available | Skip git-based detection. Continue with conversation context and keyword search. | +| `gh` not available | Skip PR detection. Continue with other methods. | +| Issue is Closed | "This issue is already Closed. Open a new issue or reopen?" | +| Transition fails | Check exit criteria. Report which fields are missing. | +| Comment fails | Report error. Issue state is unchanged. | +| Parent query returns 0 siblings | Skip cascade check — issue may be unlinked. | + +## Caveats + +1. **On-demand only.** The agent does not proactively suggest status updates. Run this when you're ready. +2. **Git detection is best-effort.** Branch naming conventions vary — the agent always confirms before acting. +3. **Upward cascade stops at Feature.** The agent suggests the Feature transition but defers to the Feature Owner to apply it. +4. **Multiple issues per session.** If the session touched multiple issues, the agent asks which one(s) to update. Each update runs the full workflow independently. +5. **Resolution field.** When closing or descoping, set the resolution field and add a rationale comment — same convention as `refine.md` remediation. diff --git a/skills/rhdh-jira/scripts/command-metadata.json b/skills/rhdh-jira/scripts/command-metadata.json index e9a1107..753e99a 100644 --- a/skills/rhdh-jira/scripts/command-metadata.json +++ b/skills/rhdh-jira/scripts/command-metadata.json @@ -23,5 +23,25 @@ "description": "Release readiness: feature matrix, PI funnel, epic roll-up, dependency map, blocker bugs, RN readiness, risk assessment.", "argumentHint": "[version] or [version team]", "reference": "references/release.md" + }, + "to-feature": { + "description": "Create a RHDHPLAN Feature from conversation context. Grills on scope, customer value, AC. Optionally chains into Epic decomposition.", + "argumentHint": "[feature description]", + "reference": "references/to-feature.md" + }, + "to-epic": { + "description": "Create an RHIDP Epic from conversation context. Grills on delivery scope, dependencies, AC. Optionally chains into Story/Task decomposition.", + "argumentHint": "[epic description]", + "reference": "references/to-epic.md" + }, + "to-issue": { + "description": "Create a Story, Task, Bug, or Spike. Automatically infers the issue type. Grills on implementation details, AC, story points.", + "argumentHint": "[issue description]", + "reference": "references/to-issue.md" + }, + "update-jira-status": { + "description": "Update a Jira issue with session progress. Detects the related issue, adds a status comment, proposes transitions, checks upward cascade to parent Epic/Feature.", + "argumentHint": "[issue key] or auto-detect", + "reference": "references/update-jira-status.md" } } diff --git a/skills/skill-maker/references/architecture-patterns.md b/skills/skill-maker/references/architecture-patterns.md index 7340aad..beef4d5 100644 --- a/skills/skill-maker/references/architecture-patterns.md +++ b/skills/skill-maker/references/architecture-patterns.md @@ -297,6 +297,67 @@ Rules: - Provide a one-line skip reason template - Never ask users to install tooling just to satisfy a gated step +## Creation Workflows + +### When to use + +Use when a skill creates structured artifacts through conversation (Jira issues, PRDs, design docs, config files). The goal is to feel like a conversation with a smart colleague, not a form. + +### Draft-then-grill + +Don't ask every question from scratch. Synthesize what the conversation already established into a draft, present it for review, then ask only about gaps: + +1. **Draft from context** — fill in as many template sections as possible from what's already known +2. **Present for review** — "Here's what I have so far. What's missing or wrong?" +3. **Fill gaps** — ask targeted questions only for unfilled sections +4. **Challenge** — probe sizing, completeness, scope, risks on the completed draft + +This respects the user's time. If they spent 10 minutes describing the problem, they don't want to re-answer it as 7 template questions. + +### Field inference + +When the artifact has metadata fields (priority, owner, category, labels, sizing), infer values from the conversation instead of asking for each one: + +- Propose all fields at once with rationale +- User confirms or adjusts + +Examples across domains: + +- **Issue tracker**: "Priority Major (functional gap, not a regression). Team inferred from component. Size M based on AC count." +- **Design doc**: "Category: API Design. Reviewer: inferred from module ownership. Status: Draft." +- **Config file**: "Environment: staging — you mentioned testing. Region: us-east-1 — matches existing infra." + +Inference signals depend on the domain: conversation keywords, codebase context (file paths being edited), parent artifact inheritance, historical patterns, or org conventions. + +### Review gate with preview + +Before creating the artifact, render a preview as a temp file so the user can review the complete picture: + +```markdown +## {Type}: {summary} + +### Description +{filled template} + +### Fields +- **Priority**: Major — rationale +- **Team**: COPE +... +``` + +Present: "Review before creating. [approve / edit / cancel]" + +This is a concrete implementation of the mutation gate — no artifact is created until the user approves the preview. + +### Chained decomposition + +When artifacts form a hierarchy (e.g., PRD → issues, design doc → tasks, Feature → Epic → Story), offer to continue down the chain after each creation: + +- Context carries down — don't re-ask what was already established +- The grill narrows at each level (high-level scope → delivery plan → implementation details) +- Each level is a separate confirmation — the user can stop at any point +- Parent/child linking happens automatically where the target system supports it + ## Structured Artifacts as Handoffs ### When to use diff --git a/skills/skill-maker/references/spec-guide.md b/skills/skill-maker/references/spec-guide.md index fe38342..9004958 100644 --- a/skills/skill-maker/references/spec-guide.md +++ b/skills/skill-maker/references/spec-guide.md @@ -117,6 +117,28 @@ When a skill offers multiple ways to accomplish similar tasks (CLI, API, library - Each reference file explains when to use *it* vs alternatives - Default to the simplest approach — escalate only when it can't handle the task +## Template + Example Pairs for Artifact Creation + +When a skill creates structured artifacts (Jira issues, PRDs, design docs, ADRs, config files), split templates into individual files under `assets/templates/`. Add filled-in examples under `assets/examples/` to calibrate the agent's tone and detail level. + +``` +assets/ + templates/ + feature.txt # Structure: what sections to fill + epic.txt + story.txt + examples/ + feature-example.txt # Calibration: tone, detail level, good output + epic-example.txt +``` + +- The **template** tells the agent *what sections to fill* — the skeleton. +- The **example** tells the agent *how much detail and what tone* — the calibration. +- Each creation workflow loads only its template + example pair — not the entire collection. +- Keep a thin index reference (e.g., `references/templates.md`) that maps issue types to files and documents field requirements. + +Not every template needs an example. Prioritize examples for the most common or most error-prone artifact types. + ## Fake Data in Examples Skill examples should use realistic but fake data wherever possible. Real credentials, real user emails, and real PII should never appear in skill files that may be committed to version control.