Release Notes

Release Notes

You generate release notes from a Linear cycle — pulling completed issues from engineering teams, categorizing them, and formatting them for the team. This is a standalone utility skill, not a pipeline stage.

Inputs

• $ARGUMENTS — the cycle number (integer, e.g., 47)
• The conventions file — projects path (from Pipeline Configuration → Work Directory → Projects) and project tracker config
• <projects-path>/release-notes/*.md — previous release notes (for format reference)

Pre-Flight Checks (MANDATORY)

Run ALL checks before doing anything else. If any check fails, STOP and report the issue.

Check 1: Argument Is a Number

$ARGUMENTS must be a single integer (the cycle number). If it's missing, empty, or not a number, STOP:

"Usage: /release-notes <cycle_number> — provide a cycle number (e.g., /release-notes 47)."

Check 2: Pipeline Config Exists

Locate the conventions file in the current repo root — look for CLAUDE.md, AGENTS.md, or CONVENTIONS.md (use the first one found). Read it in full. From the ## Pipeline Configuration section, extract:

• Projects path from Work Directory → Projects
• Project Tracker → Tool — must be "Linear"

If no conventions file is found, STOP:

"No conventions file found (CLAUDE.md, AGENTS.md, or CONVENTIONS.md). This skill requires Pipeline Configuration with Linear as the project tracker."

If the project tracker is not Linear, STOP:

"This skill requires Linear as the project tracker. Current tracker: [value]."

Check 3: Cycle Exists

Look up the Engineering team using list_teams (search for "Engineering"). Then use list_cycles on that team to find the target cycle by number.

Try list_cycles with type current first. If the target cycle number isn't in the current cycle, try previous, then next.

If the cycle is not found across all three queries, STOP:

"Cycle $ARGUMENTS not found on the Engineering team. Available cycles: [list what you found]."

Record the cycle's start date, end date, and ID for later use.

Step-by-Step Procedure

Step 1: Read Previous Release Notes (Template Discovery)

Check for existing release notes:

mkdir -p <projects-path>/release-notes

Use Glob to find <projects-path>/release-notes/*.md. If files exist, read the most recent one (sorted by filename, which includes the date). This becomes your format template — match its structure, tone, section headings, and bullet style.

If no previous files exist, use the Built-In Template (see below).

Step 2: Look Up Teams and Cycles

Find the four engineering teams using list_teams:

• Engineering (the primary team — cycle numbers match user-facing cycle numbers)
• Web
• iOS
• Android

For each team found, look up the target cycle. The Engineering team's cycle is already found from Pre-Flight Check 3. For the other teams, search for a cycle with the same number or overlapping date range.

Not all teams may have a matching cycle — that's OK. Record which teams have cycles and which don't.

Step 3: Fetch Completed Issues

For each team that has a matching cycle, fetch issues in "Done" and "Pending Release" statuses:

1. First, use list_issue_statuses for each team to find the exact status names/IDs for completed states (look for statuses of type "completed" — typically "Done"). Also look for any status named "Pending Release" or similar.

2. Then use list_issues with the team and cycle filters, filtered to those completed statuses.

Collect all issues across all teams. For each issue, record:

• Title
• Team (Engineering, Web, iOS, Android)
• Labels (if any)
• Issue identifier (e.g., ENG-123)

Step 4: Categorize Issues

Group issues into three categories using this priority order:

Priority 1 — Label-based (most reliable):

Priority 2 — Title keyword heuristics:

Priority 3 — Default:

If neither labels nor title keywords match, default to Maintenance.

Internal flagging:

Flag issues that appear to be internal/engineering-only (not customer-facing) with [INTERNAL?] in the draft. Heuristics for internal items:

• Title mentions "refactor", "tech debt", "CI", "pipeline", "deploy", "infrastructure", "migration" (without user-facing context)
• Labels include "internal", "devops", "infra"

These flags help the operator decide what to include in the final notes.

Step 5: Rewrite Issue Titles

Transform Linear issue titles into customer-friendly descriptions:

• Remove prefixes like "Fix:", "Bug:", "Feature:" — incorporate them naturally
• Replace internal jargon with user-facing language
• Focus on what changed for the user, not how it was implemented
• Keep descriptions concise (one sentence)
• For bug fixes, describe what works now, not what was broken

Examples:

• "Fix: PDF export crashes when area has no inspections" → Fixed an issue where PDF exports could fail for areas without recent inspections
• "Add inspection schedule limit setting" → **Inspection Schedule Limit** - Administrators can now set a maximum number of inspections that can be scheduled per area
• "Remove deprecated v3 API endpoints" → Retired legacy API v3 endpoints (replaced by v4)

Step 6: Ask for Mobile Build Numbers

Use AskUserQuestion to ask the operator:

1. Current iOS build version (e.g., "5.2.1 (Build 847)")
2. Current Android build version (e.g., "5.2.1 (Build 312)")

Present as a single question with two text fields. If the operator doesn't have them yet, they can enter "TBD" and fill them in later.

Step 7: Write Release Notes

Generate the release notes file. Use the format from the previous cycle's notes (Step 1) if available, otherwise use the Built-In Template.

Filename: <projects-path>/release-notes/<end-date>-cycle-<N>.md

Where <end-date> is the cycle end date in YYYY-MM-DD format and <N> is the cycle number.

Write the file.

Step 8: Present Draft Summary

Tell the operator:

1. The file path where notes were written
2. Summary: number of issues categorized (X new features, Y maintenance, Z cleanup)
3. Which teams had cycles (and which didn't)
4. Any items flagged [INTERNAL?] — list them so the operator can decide whether to keep or remove
5. Remind them: "Review and wordsmith the descriptions before posting. Remove [INTERNAL?] flags — either delete the item or remove the flag to keep it."

Built-In Template

Use this template when no previous release notes exist in the release-notes/ directory:

# Release Notes for Cycle {N} ({start_date} - {end_date})

## Mobile App Builds

* **iOS**: {ios_version}
* **Android**: {android_version}

## Links

* [iOS in the App Store](https://apps.apple.com/us/app/orangeqc/id324039524)
* [OrangeQC in the Google Play Store](https://play.google.com/store/apps/details?id=com.orangeqc.native)

## New Features

* **{Feature Name}** - {Customer-friendly description of what's new}

## Maintenance

* {Customer-friendly description of fix or improvement}

## Cleaning Up

* {Description of removal or deprecation}

Format notes:

• Use * for bullet points (not -)
• Bold the feature name in New Features (e.g., **Feature Name** - description)
• Maintenance and Cleaning Up items don't need bold names — just descriptions
• Dates in the header use the format from the cycle data (e.g., "Jan 27 - Feb 3, 2026")
• If a category has no items, omit that section entirely

What NOT To Do

• Do not post or publish the notes. Write them to a file — the operator posts them after review.
• Do not prompt for each issue individually. Categorize in batch, review at the end.
• Do not include issue identifiers (like ENG-123) in the output — release notes are customer-facing.
• Do not make up issues. Only include issues that came from the Linear cycle query.
• Do not include cancelled or backlog issues. Only "Done" and "Pending Release" statuses.