From 542d61e984781175b08a16853234642fb2a2a54d Mon Sep 17 00:00:00 2001 From: Petr Toman Date: Fri, 19 Jun 2026 15:50:01 +0200 Subject: [PATCH] feat(sdlc-workflow): add release-notes skill Add a new skill that guides engineers and technical writers through the Trusted Profile Analyzer release notes process. The skill operates in three modes: - Document mode: Engineer assesses an issue, fills the release note template (Known Issue / Bug Fix / Feature), and links to a tracker - Review mode: Technical Writer rewrites the text in AsciiDoc format and proposes it for engineer review - Approve mode: Engineer approves or rejects the proposed text The skill automates Jira field updates (Release Note Type, Text, and Status custom fields) and creates Document links to Release Notes tracker epics. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../skills/release-notes/SKILL.md | 445 ++++++++++++++++++ 1 file changed, 445 insertions(+) create mode 100644 plugins/sdlc-workflow/skills/release-notes/SKILL.md 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.