diff --git a/plugins/sdlc-workflow/skills/release-notes/SKILL.md b/plugins/sdlc-workflow/skills/release-notes/SKILL.md new file mode 100644 index 000000000..37727373f --- /dev/null +++ b/plugins/sdlc-workflow/skills/release-notes/SKILL.md @@ -0,0 +1,445 @@ +--- +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.