release-notes - SKILL.md Agent Skill

name: release-notes description: >- Internal — for Boundless team members only. Generate release notes for a new Boundless version. Fetches PR details, explores code changes, and produces prover-facing documentation with config examples, migration guides, and worked examples. Use when the user wants to write release notes, changelog entries, or upgrade guides.

Release Notes Generator

Generate release notes for a new Boundless release. The audience for broker changes is prover operators -- people running the broker who need to understand what changed, how to configure it, and how to migrate.

Process

Step 1: Gather inputs

Ask the user for:

Version number for this release
Previous release tag to compare against (e.g., v1.2.2)
Key PRs or features to highlight -- the user will tell you which PRs or topics matter. Don't try to cover every commit.
Current market context if relevant (e.g., current pricing in USD/Bcycle, token prices) for realistic examples

Step 2: Research

For each feature the user wants covered:

Fetch PR details with gh pr view <number> --repo boundless-xyz/boundless --json title,body
Read the actual code to understand how the feature works -- don't rely solely on PR descriptions
Read config structs, default values, and broker.toml template to get accurate config examples
Check compose.yml for env var support and justfile for how provers actually run things (just prover up)

Use subagents to research multiple PRs in parallel.

Step 3: Write the notes

Follow these principles:

Structure

Start with a brief overview paragraph summarizing all highlighted features in one sentence
Include a full changelog link: [vOLD...vNEW](https://github.com/boundless-xyz/boundless/compare/vOLD...vNEW)
Each feature gets its own section with: what changed (1-3 sentences on the change, new paragraph, then 1-3 sentences on why it matters), how to use it (how to enable with examples)
End with an "Upgrade Notes" section summarizing action items

Writing style

Write for prover operators, not developers. Focus on config changes, CLI flags, and operational impact.
Lead with what the user needs to do, not how the code works internally
Be direct and concise. No filler, no marketing language.
Use "the broker" not "we" or "the system"
Don't use emojis

Config examples

Show the recommended/minimal config first, not the full config with all options
Use realistic values based on current market rates (ask the user if unsure)
For broker.toml changes, always show the TOML syntax exactly as it would appear in the file. Show before + after if relevant.
For CLI flags, show how to pass them via BROKER_EXTRA_ARGS in .env (since most provers use just prover up) AND as direct CLI flags
For env vars, show the export syntax

Migration guides

Show a clear before/after comparison with labeled TOML blocks
Call out which fields are removed, renamed, or have new defaults
Always note backward compatibility -- existing configs should work without changes unless there's a breaking change

Worked examples

Use real order data where possible. Ask the user for a reference order from the explorer if they don't provide one.
Convert all comparisons to USD when demonstrating USD-based features
Show the math step by step so operators can verify their own config

Features to watch for

When researching broker changes, pay attention to:

Pricing: min_mcycle_price, collateral pricing, pricing overrides in crates/boundless-market/src/prover_utils/config.rs
Config: broker.toml template at broker-template.toml, MarketConfig struct
RPC/monitoring: chain monitors, gas estimation in crates/broker/src/
CLI flags: Args struct in crates/broker/src/lib.rs, check for BROKER_EXTRA_ARGS support in compose.yml
Telemetry: crates/broker/src/telemetry.rs
Hot-reload: note when config changes take effect without restart

Step 4: Iterate

The user will review and give feedback. Common adjustments:

Reordering sections to lead with the most impactful change
Adjusting example values to match current market conditions
Adding or removing detail from specific sections
Changing the framing of a feature (e.g., "show the simplification, not the mechanism")

References

Use v1.4.0 release from https://github.com/boundless-xyz/boundless/releases as a reference for tone, structure, and level of detail.