claude-engineering-plugin/docs/brainstorms/2026-04-17-ce-release-notes-skill-requirements.md

---
date: 2026-04-17
topic: ce-release-notes-skill
---

# `ce-release-notes` Skill

## Problem Frame

The `compound-engineering` plugin ships frequently — often multiple releases per week. Users who install the plugin via the marketplace can't easily keep up with what's changed: skill renames, new behaviors, retired commands, or relevant fixes. The release history exists publicly on GitHub (release-please-generated GitHub Releases at `EveryInc/compound-engineering-plugin`), but scrolling through release pages to answer "what happened to the deepen-plan skill?" is friction users won't bother with.

This skill provides a conversational interface over the plugin's GitHub Releases so a user can ask either "what's new?" or a specific question and get a grounded, version-cited answer without leaving Claude Code.

**Premise note:** The user-pain claim above is grounded in the rapid release cadence rather than in cited support asks or telemetry. We accept the residual risk that the skill may see low adoption if the conversational-lookup framing turns out to be a weaker need than discoverability or release-page bookmarking.

## Requirements

**Invocation and Modes**
- R1. Skill is invoked via slash command `/ce:release-notes` (matching the `ce:` namespace convention used by sibling skills like `/ce:plan`, `/ce:brainstorm`). The skill directory is `plugins/compound-engineering/skills/ce-release-notes/`; the SKILL.md `name:` frontmatter field is `ce:release-notes` (colon form, not dash) — that is what produces the `/ce:release-notes` slash command. (Several existing `ce-` skills use `name: ce-x` and are not slash-invoked; this one needs the colon form to match R1.)
- R2. Bare invocation (`/ce:release-notes`) returns a summary of recent releases.
- R3. Argument invocation (`/ce:release-notes <question or topic>`) returns a direct answer to the user's question, grounded in the relevant release(s).
- R4. **v1 is slash-only invocation.** The SKILL.md frontmatter sets `disable-model-invocation: true` so the skill only fires when the user explicitly types `/ce:release-notes`. Auto-invocation is deferred to a possible v2 once dogfooding shows users clearly want conversational triggering and a tested gating description has been validated against a prompt corpus.

**Data Source**
- R5. Source of truth is the GitHub Releases API for `EveryInc/compound-engineering-plugin`. **Layered access strategy:** prefer the `gh` CLI when available (authenticated, consistent JSON output, better error messages, higher rate limits). Fall back to anonymous HTTPS against `https://api.github.com/repos/EveryInc/compound-engineering-plugin/releases` (or the equivalent paginated endpoint) when `gh` is missing or unauthenticated. The repo is public, so anonymous reads work and the 60 req/hr-per-IP unauth'd limit is more than enough for this skill's invocation frequency.
- R6. Only releases tagged with the `compound-engineering-v*` prefix are considered. Sibling tags (`cli-v*`, `coding-tutor-v*`, `marketplace-v*`, `cursor-marketplace-v*`) are filtered out, even though `cli` and `compound-engineering` share version numbers via release-please's `linked-versions` plugin.
- R7. No local caching, no fallback to `CHANGELOG.md` files. Always fetch live.
- R8. Skill must fail gracefully with an actionable message when **both** access paths fail (e.g., no network, GitHub API outage, rate-limit exhaustion on the anonymous fallback). Missing `gh` alone is not a failure — the skill silently uses the anonymous fallback.

**Output — Summary Mode**
- R9. Default window is the last 10 plugin releases.
- R10. Per-release section format: version + publish date + the release-please-generated changelog body (already grouped by `Features`, `Bug Fixes`, etc.), trimmed minimally — release sizes vary, so do not impose a uniform highlight count.
- R11. Each release section links to its GitHub release URL so users can read the full notes.

**Output — Query Mode**
- R12. Search window is the last 20 plugin releases — fixed cap, no expansion. 20 releases is already a substantial corpus (multiple weeks of cadence). If no matching content is found within that window, report "not found" and surface the GitHub releases page link (per R14) so the user can search further manually.
- R13. **When a confident match is found**, the answer is a direct narrative response that cites the specific release version(s) the answer is drawn from (e.g., "The `deepen-plan` skill was renamed to `ce-debug` in `v2.45.0`"). Include a link to the cited release. The release body itself is a terse one-line conventional-commit bullet per change with a linked PR number; for query-mode synthesis the skill should follow the linked PR(s) (e.g., `gh pr view <N>`) to ground the narrative in the rich PR description rather than only the commit subject. (Verified against `v2.65.0`–`v2.67.0` release bodies and PR #568.)
- R14. **When no confident match is found** (after expanding the search window per R12) **or the answer is uncertain**, say so plainly rather than guessing — and surface a link to the GitHub releases page so the user can investigate further.

## Success Criteria
- A user who installed the plugin via the marketplace can run `/ce:release-notes` and immediately see what's shipped recently in the compound-engineering plugin (not CLI noise, not other plugins).
- A user can ask `/ce:release-notes what happened to deepen-plan?` and get a direct narrative answer with a version citation, without having to open any browser tab.
- The skill works for users without `gh` installed (silent anonymous-API fallback) and produces a clear error only when both access paths fail.

## Scope Boundaries
- **Out of scope:** Coverage of `cli`, `coding-tutor`, `marketplace`, or `cursor-marketplace` releases. Only `compound-engineering` plugin releases are surfaced.
- **Out of scope:** "What's coming next" / unreleased changes. The skill does not peek at the open release-please PR. Only shipped releases are summarized.
- **Out of scope:** Local caching, CHANGELOG.md parsing, or any source other than the GitHub Releases API.
- **Out of scope:** Per-PR or per-commit drill-down *as a primary user-facing surface*. Query mode may follow PR links for context (per R13), but the skill does not browse arbitrary commits or expose PR-level navigation as a separate mode.
- **Out of scope:** Customization flags for window size or output format in v1. Defaults are fixed; users can ask follow-up questions in chat to drill deeper.

## Key Decisions
- **Plugin-only filter (excludes `cli-v*`):** Linked versions mean a `2.67.0` bump can contain CLI-only or plugin-only changes; surfacing both would dilute the user-facing signal. Users who care about plugin behavior should not have to mentally filter CLI noise.
- **GitHub Releases over CHANGELOG.md:** GitHub Releases are authoritative for what shipped, are accessible without a repo checkout (most plugin users won't have one), and the release-please-generated body is already markdown-grouped and ready to display.
- **Slash-only invocation in v1 (no auto-invoke):** No sibling `ce:*` skill currently auto-invokes. Making this the first one introduces a hard-to-validate gating problem (the skill description is the only lever, and the failure modes are silent — either firing on unrelated projects' "what's new?" prompts, or never firing for actual CE-shaped questions). Slash-only satisfies both stated user journeys (`/ce:release-notes` bare summary and `/ce:release-notes <question>`) without the gating risk. Auto-invoke is deferred to a possible v2 once dogfooding shows the conversational triggering is genuinely wanted and a tested gating description exists.
- **Layered data access (`gh` preferred, anonymous public API fallback):** The repo is public, so anonymous reads work and the 60 req/hr unauth'd limit is far above this skill's invocation frequency. Layering means users without `gh` installed still get value rather than bouncing on an "install gh and retry" message. Prefer `gh` when present for cleaner error handling, consistent JSON output, and authenticated rate limits.
- **No local caching:** `gh release list` is fast (~1s for metadata; bodies add some cost) and release queries are infrequent; caching adds carrying cost (invalidation, location in `.context/`) without meaningful payoff. Reversal cost is low — caching can be added later if real latency or frequency problems show up.
- **Two-mode design instead of always-query:** A bare-invocation summary serves the casual "what have I missed?" use case, which is materially different from "what specifically happened to X?". One skill covers both with a clean argument convention.
- **Distinct from the existing `changelog` skill:** The plugin already ships a `changelog` skill that produces witty daily/weekly changelog summaries of recent activity. That serves a different use case (narrative recap of work) than this skill's version-aware release-notes lookup against shipped GitHub Releases. The two are complementary, not redundant.

## Dependencies / Assumptions
- Users have **either** the `gh` CLI (preferred path) **or** outbound HTTPS access to `api.github.com` (anonymous fallback path). Per R5, missing `gh` alone is not a failure.
- The 60 req/hr anonymous limit is per source IP, not per user. Users on shared NAT egress (corporate networks, VPN exit nodes) could in principle exhaust the budget collectively even at low individual usage. We accept this as low-likelihood given the skill's invocation pattern; if it surfaces in practice, encourage `gh auth login` rather than adding caching.
- The repo `EveryInc/compound-engineering-plugin` remains the canonical source. (If the plugin moves repos, the hardcoded repo reference in the skill must be updated.)
- Release-please continues to use the `compound-engineering-v*` tag prefix and the conventional-commit-grouped release body format. A change to release-please configuration could break R6 or R10.

## Outstanding Questions

### Deferred to Planning
- [Affects R10][Technical] Should the summary impose a maximum-length cap on individual release bodies (separate from R10's no-uniform-highlight-count rule), to prevent a single 30-bullet release from dominating the summary view? Decide based on real release sizes during implementation.
- [Affects R8][Technical] Exact failure messages when both access paths fail (network down, GitHub outage, anonymous rate-limit hit). Ensure they're actionable (point the user to the GitHub releases URL as a manual fallback).
- [Affects R5][Technical] Implementation choice for the anonymous fallback: shell out to `curl` + `jq`, or use a different HTTP client. Decide based on cross-platform portability requirements (note: AGENTS.md "Platform-Specific Variables in Skills" rules apply since this skill will be converted for Codex/Gemini/OpenCode).
- [Affects R13, R14][Technical] Define the "confident match" criterion that gates R13 (direct narrative answer) vs. R14 (say-so-plainly). Options include keyword/substring match against release bodies, semantic match via embedding, or LLM judgment with an explicit confidence prompt. Decide during planning based on cost and accuracy tradeoffs.
- [Affects R4][Needs research] If/when v2 auto-invoke is reconsidered, define the actual gate. Since v1 has no auto-invoke surface to observe, "dogfooding shows users want it" is unfalsifiable as written — the v2 trigger needs a concrete source of evidence (explicit user requests, opt-in beta flag with telemetry, or a stated time-box for revisiting).
- [Affects R5][Technical] Should the repo reference (`EveryInc/compound-engineering-plugin`) be hardcoded in the skill, or derived from `.claude-plugin/plugin.json` (`homepage`/`repository` field) for portability? Hardcoding is simpler; derivation survives a future repo move without skill edits. Decide based on portability vs. complexity tradeoff during planning.
- [Affects R10][Technical] Release-please body format drift handling: R10 assumes the `Features`/`Bug Fixes` markdown grouping. Decide whether to (a) accept silent degradation if release-please config changes, (b) parse defensively and fall back to raw rendering, or (c) detect drift and surface a warning. Low priority — release-please config has been stable.

## Next Steps
- `/ce:plan docs/brainstorms/2026-04-17-ce-release-notes-skill-requirements.md` for structured implementation planning.