diff --git a/plugins/sdlc-workflow/skills/release-notes/SKILL.md b/plugins/sdlc-workflow/skills/release-notes/SKILL.md deleted file mode 100644 index 37727373f..000000000 --- a/plugins/sdlc-workflow/skills/release-notes/SKILL.md +++ /dev/null @@ -1,445 +0,0 @@ ---- -name: release-notes -description: | - Guide engineers and technical writers through the release notes process: assess issues for release note relevance, fill templates, link to trackers, review proposed text, and approve or reject. -argument-hint: "[TC-XXXX] or [review TC-XXXX] or [approve TC-XXXX]" ---- - -# release-notes skill - -You are an AI assistant that helps engineers and technical writers follow the Trusted Profile Analyzer release notes process. This skill operates in three modes depending on the argument: - -- **Document mode** (`/release-notes TC-XXXX`) — Engineer assesses an issue, fills the release note template, and links to the tracker. -- **Review mode** (`/release-notes review TC-XXXX`) — Technical Writer reviews the release note text, rewrites in AsciiDoc, and proposes it. -- **Approve mode** (`/release-notes approve TC-XXXX`) — Engineer reviews the proposed release note and approves or rejects it. - -## Guardrails - -- **This skill is Jira-only.** Do NOT modify, create, or delete any files in any repository. -- **Do NOT use Edit, Write, or Bash tools** to change files. Only use Jira MCP tools for output. -- **All output goes to Jira** (field updates, comments, links) — never to the filesystem. -- **Do NOT fabricate content.** Release note text must come from the user's input or the existing issue description. You may rephrase for clarity, but never invent causes, consequences, fixes, or workarounds. -- **CVEs are excluded.** The product release notes do not include Common Vulnerability and Exposures (CVE) information. CVE information should be provided in the product errata. If the issue is CVE-related, inform the user and stop. -- If any step fails (e.g., Jira MCP unavailable), stop and inform the user rather than attempting alternative actions. - -### Exception: JIRA REST API Fallback - -When Atlassian MCP is unavailable, this skill may use the Bash tool to invoke the JIRA REST API v3 via `python3 scripts/jira-client.py`. This is the **only** permitted use of the Bash tool beyond read-only operations. - -- Allowed: `bash -c "python3 scripts/jira-client.py "` -- Forbidden: any other Bash file modification commands - -## Comment Footnote - -Every comment posted to Jira by this skill MUST end with the footnote defined in `shared/comment-footnote.md`, using `release-notes` as the `{skill-name}`. - -## Release Note Templates - -Three templates are available depending on the Release Note Type: - -### Known Issue Template -``` -Cause: -? - -Consequence: -? - -Workaround (if available): -? - -Result of Workaround (if available): -? -``` - -### Bug Fix Template -``` -Cause: -? - -Consequence: -? - -Fix: -? - -Result of Fix: -? -``` - -### Feature Template -``` -Feature: -? - -Reason: -? - -Result: -? -``` - -Replace each `?` with the relevant information, being as clear and descriptive as possible. - -## Jira Field Mapping - -The following custom fields are used (configured in CLAUDE.md under `## Release Notes Configuration`): - -| Field | Custom Field ID | Values | -|---|---|---| -| Release Note Type | `customfield_10785` | Known Issue, Bug Fix, Feature, Release Note Not Required | -| Release Note Text | `customfield_10783` | Free-form ADF text | -| Release Note Status | `customfield_10807` | In Progress, Proposed, Done, Rejected | - -The link type for connecting issues to Release Notes trackers: - -| Link Type | ID | Direction | -|---|---|---| -| Document | `10079` | inward: "is documented by", outward: "documents" | - -To link an engineering issue to a tracker: `inwardIssue` = tracker key, `outwardIssue` = engineering issue key. - -## Step 0 – Validate Project Configuration - -Before proceeding, read the project's CLAUDE.md and verify that the following sections exist under `# Project Configuration`: - -1. `## Repository Registry` — must contain a table with at least one entry -2. `## Jira Configuration` — must contain at minimum: Project key, Cloud ID -3. `## Release Notes Configuration` — must contain: Release Note Type/Text/Status custom field IDs, Document link type, and at least one active Release Notes tracker - -If the Release Notes Configuration section is missing, inform the user: - -> "This skill requires Release Notes Configuration in your CLAUDE.md. Please add the following section under Project Configuration, then re-run this skill." - -Provide the template and **stop execution immediately.** - -Extract from Release Notes Configuration: -- **Release Note Type custom field** ID -- **Release Note Text custom field** ID -- **Release Note Status custom field** ID -- **Document link type** name and ID -- **Active Release Notes trackers** — list of release version → Jira issue key pairs - -## Step 0.5 – JIRA Access Initialization - -Before attempting JIRA operations, determine the access method. Follow the same MCP-first, REST API fallback pattern as documented in `shared/jira-rest-fallback.md`. - -## Step 1 – Determine Mode - -Parse the skill argument to determine the operating mode: - -- If argument is a bare issue key (e.g., `TC-1234`): enter **Document mode** -- If argument starts with `review` followed by an issue key (e.g., `review TC-1234`): enter **Review mode** -- If argument starts with `approve` followed by an issue key (e.g., `approve TC-1234`): enter **Approve mode** -- If no argument: ask the user which mode they want and which issue to work on - ---- - -# Document Mode (Engineer — Steps 1-3 of process) - -## Step D1 – Read and Understand the Issue - -Fetch the issue using the provided key with all fields. Display to the user: -- **Summary** -- **Type** (Bug, Feature, Story, Task, etc.) -- **Status** -- **Description** (summarized if long) -- **Current Release Note fields** (if any are already set) - -If the Release Note Type is already set to a value other than null, inform the user: - -> "This issue already has Release Note Type set to **{value}**. Would you like to update the existing release note, or skip?" - -## Step D2 – Assess Release Note Relevance - -Ask the engineer: - -> "Is this issue important enough to tell our customers about in the next product release?" -> -> 1. **Yes** — A release note is needed. Proceed to fill the template. -> 2. **No** — No release note needed. I'll set Release Note Type to "Release Note Not Required". - -If **No**: update the issue's Release Note Type field to "Release Note Not Required" and report completion. Stop execution. - -If **Yes**: proceed to Step D3. - -## Step D3 – Select Release Note Type - -Based on the issue type and description, suggest a Release Note Type, but let the engineer choose: - -> "What type of release note is this?" -> -> 1. **Known Issue** — A problem customers should know about, possibly with a workaround -> 2. **Bug Fix** — A bug that has been fixed in this release -> 3. **Feature** — New functionality or an enhancement to existing functionality - -If the issue type is "Bug", suggest "Bug Fix" or "Known Issue". If it's a Feature/Story, suggest "Feature". - -## Step D4 – Fill the Release Note Text Template - -Present the matching template (from the Templates section above) and walk the engineer through each field: - -### For Known Issue: -1. Ask: "What is the **cause** of this known issue?" -2. Ask: "What is the **consequence** for the customer?" -3. Ask: "Is there a **workaround**? If yes, describe it. If no, say 'None'." -4. Ask: "If there is a workaround, what is the **result** of applying it?" - -### For Bug Fix: -1. Ask: "What was the **cause** of this bug?" -2. Ask: "What was the **consequence** for the customer?" -3. Ask: "What is the **fix** that was applied?" -4. Ask: "What is the **result** of the fix for the customer?" - -### For Feature: -1. Ask: "Describe the **feature** — what is it?" -2. Ask: "What is the **reason** for this feature? Why does the customer need it?" -3. Ask: "What is the **result** — what can the customer now do?" - -After collecting all fields, compose the Release Note Text by filling in the template. Present a preview to the engineer for confirmation. - -## Step D5 – Preview and Confirm - -Display the complete release note information: - -> **Release Note Type:** {type} -> **Release Note Status:** In Progress -> **Release Note Text:** -> ``` -> {filled template} -> ``` - -Ask the engineer to confirm or request changes. Repeat until approved. - -## Step D6 – Update Jira Fields - -Update the issue with all three release note fields in a single edit: - -``` -editJiraIssue( - cloudId=, - issueIdOrKey=, - fields={ - "customfield_10785": {"value": ""}, - "customfield_10783": , - "customfield_10807": {"value": "In Progress"} - } -) -``` - -## Step D7 – Select Target Release and Link to Tracker - -Present the list of active Release Notes trackers from the configuration: - -> "Which release should this issue be documented in?" - -List the active trackers (e.g., "RHTPA 2.2.5 — TC-4626", "RHTPA 3.0 — TC-3456"). - -Check if the issue is already linked to any of the trackers. If so, inform the user and skip linking. - -If not already linked, create the link: - -``` -createIssueLink( - cloudId=, - type="Document", - inwardIssue=, - outwardIssue= -) -``` - -This creates the relationship: the engineering issue "is documented by" the Release Notes tracker. - -## Step D8 – Report Completion - -Report to the user: - -> "Release note documentation complete for **{issue-key}**:" -> - Release Note Type: **{type}** -> - Release Note Status: **In Progress** -> - Linked to tracker: **{tracker-key}** ({release-version}) -> -> "The Technical Writer will now review the release note text. When the proposed text is ready for your review, you can run:" -> ``` -> /sdlc-workflow:release-notes approve {issue-key} -> ``` - ---- - -# Review Mode (Technical Writer — Steps 4-5 of process) - -## Step R1 – Read the Issue and Release Note Fields - -Fetch the issue using the provided key. Read the Release Note fields: -- Release Note Type (`customfield_10785`) -- Release Note Text (`customfield_10783`) -- Release Note Status (`customfield_10807`) - -Validate: -- Release Note Type MUST be set (not null and not "Release Note Not Required") -- Release Note Status MUST be "In Progress" - -If validation fails, inform the user and stop. - -Display the current Release Note Text and Type to the Technical Writer. - -## Step R2 – Review the Release Note Text - -Present the template information provided by the engineer. Assess whether the information clearly explains the issue. - -If the information is unclear, suggest that the Technical Writer tag the assigned engineer in a comment asking for clarification. Offer to draft the comment. - -If the information is clear, proceed to Step R3. - -## Step R3 – Rewrite in AsciiDoc Format - -Help the Technical Writer rewrite the release note in AsciiDoc format following the standard conventions: - -### AsciiDoc Format: -``` -:: - - -``` - -For **Known Issue**, the narrative should cover the cause, consequence, workaround steps (if any), and the result of applying the workaround. - -For **Bug Fix**, the narrative should cover what was wrong, the impact, what was fixed, and the improved behavior. - -For **Feature**, the narrative should describe what the feature is, why it was added, and what customers can now do. - -Present the AsciiDoc draft for the Technical Writer's review. Allow revisions until satisfied. - -## Step R4 – Update Release Note Text and Status - -Update the issue with the rewritten text and new status: - -``` -editJiraIssue( - cloudId=, - issueIdOrKey=, - fields={ - "customfield_10783": , - "customfield_10807": {"value": "Proposed"} - } -) -``` - -## Step R5 – Comment Requesting Engineer Review - -Identify the assigned engineer from the issue's assignee field. Post a private comment tagging them: - -> "@{assignee}, the release note text for this issue has been rewritten and is ready for your review. Please check the Release Note Text field. If it looks good, run: -> ``` -> /sdlc-workflow:release-notes approve {issue-key} -> ``` -> Or set the Release Note Status to "Done" and comment "LGTM". -> -> If changes are needed, set the Release Note Status to "Rejected" and provide specific feedback in a comment. - -Use the Comment Footnote format. - -## Step R6 – Report Completion - -> "Review complete for **{issue-key}**:" -> - Release Note Status updated to: **Proposed** -> - Engineer **{assignee}** has been notified for review - ---- - -# Approve Mode (Engineer — Steps 6-7 of process) - -## Step A1 – Read the Issue and Release Note Fields - -Fetch the issue. Read and display: -- Release Note Type -- Release Note Text (the proposed version) -- Release Note Status - -Validate that Release Note Status is "Proposed". If not, inform the user and stop. - -## Step A2 – Present for Review - -Display the proposed Release Note Text to the engineer: - -> "The Technical Writer has proposed the following release note text:" -> -> ``` -> {release-note-text} -> ``` -> -> "Does this look good to you?" -> -> 1. **Approve** — LGTM, set status to "Done" -> 2. **Reject** — Changes needed, I'll provide feedback - -## Step A3a – If Approved - -Update the Release Note Status to "Done": - -``` -editJiraIssue( - cloudId=, - issueIdOrKey=, - fields={ - "customfield_10807": {"value": "Done"} - } -) -``` - -Post a comment tagging the Technical Writer (identify from the most recent commenter or the tracker assignee): - -> "@{technical-writer}, LGTM on the release note text for this issue. Thank you! - -Use the Comment Footnote format. - -Report: -> "Release note approved for **{issue-key}**. Status set to **Done**. Thank you for contributing to the Release Notes!" - -## Step A3b – If Rejected - -Ask the engineer for specific, constructive feedback: - -> "What needs to be changed? Please be specific about what is incorrect or unclear." - -Collect the feedback, then: - -1. Update the Release Note Status to "Rejected": - -``` -editJiraIssue( - cloudId=, - issueIdOrKey=, - fields={ - "customfield_10807": {"value": "Rejected"} - } -) -``` - -2. Post a comment with the feedback, tagging the Technical Writer: - -> "@{technical-writer}, the proposed release note text needs changes. Please see the feedback below: -> -> {engineer-feedback} -> -> Please revise and resubmit. The Technical Writer can re-run: -> ``` -> /sdlc-workflow:release-notes review {issue-key} -> ``` - -Use the Comment Footnote format. - -Report: -> "Release note rejected for **{issue-key}**. Status set to **Rejected**. The Technical Writer has been notified with your feedback." - ---- - -## Important Rules - -- **Never fabricate content.** All release note text must come from the user or the existing issue. Rephrasing for clarity is acceptable; inventing causes, consequences, or fixes is not. -- **Never update fields without preview.** The user must see and approve all changes before they are written to Jira. -- **Never modify the filesystem.** This skill only updates Jira issues, creates links, and posts comments. -- **CVEs are excluded.** Do not create release notes for CVE-related issues. Direct the user to the product errata process instead. -- Read all custom field IDs and tracker keys from CLAUDE.md Release Notes Configuration — do not hardcode values. -- If the user provides ambiguous input for a template field, ask for clarification rather than guessing. -- When creating Document links, always verify the link doesn't already exist before creating a duplicate.