Add changelog-reviewer custom agent for on-demand GitHub Changelog reviews

[MariusStorhaug]

Maintainers of the PSModule/GitHub PowerShell module — which wraps the GitHub REST and GraphQL APIs — need to keep the module current with new GitHub platform capabilities. The GitHub Changelog is the primary public feed of such announcements, but not every entry is relevant: many concern the GitHub.com UI, GitHub Enterprise Server, GitHub Desktop, GitHub Mobile, or GitHub Copilot product features that do not translate into REST/GraphQL surface changes.

Reading the changelog, deciding what is relevant, de-duplicating against existing issues, and authoring a well-structured issue in the repository's three-section issue-driven development format is a repetitive, manual task. The repository already uses Copilot custom agents — issue-manager, pr-manager, and pr-reviewer — to standardize other repetitive maintainer workflows. A similar custom agent is the natural fit for the changelog-review workflow: it is an on-demand, prompt-driven task, not something that needs to run on a cron.

Request

Desired capability

A new Copilot custom agent — invokable on demand by a maintainer from a chat prompt — scans the GitHub Changelog for entries within a specified timespan, filters them for relevance to this module, de-duplicates against existing open issues, and produces a well-structured issue (following the repository's issue-driven development three-section format) for each remaining entry.

The agent must be:

• Manually invokable with a custom prompt — a maintainer triggers it from chat with natural-language instructions.
• Timespan-configurable via prompt — examples of valid prompts include:
  • "review the GitHub Changelog" → uses the default timespan
  • "get all changelog entries for the last year"
  • "get changes for the last 3 months"
  • "get today's entries"
  • "review changelog entries between 2026-01-01 and 2026-03-31"
• Default-sensible — when no timespan is specified, the agent reviews entries from the past 7 days (past week).

Important

The default timespan is the past week (last 7 days). This is an explicit, documented default and must be called out in the agent description and in its prompt.

The agent should generalize the process so that the timespan is just one input parameter to a repeatable pipeline:

1. Fetch changelog entries from the GitHub Changelog RSS feed within the requested timespan.
2. Filter for relevance to a PowerShell module that wraps the GitHub REST and GraphQL APIs — excluding UI-only, GHES-only, Desktop, Mobile, and Copilot-product-only entries.
3. Dedupe against existing open issues in PSModule/GitHub using entry URL and title keywords.
4. Structure each remaining entry into the repository's three-section issue format (Context and request → Technical decisions → Implementation plan) by delegating to the existing issue-manager custom agent.

Acceptance criteria

• A new Copilot custom agent exists in the same location as the other custom agents (issue-manager, pr-manager, pr-reviewer).
• The agent can be invoked manually from chat with a natural-language prompt.
• When no timespan is specified, the agent defaults to the past 7 days. This default is documented in the agent's description.
• The agent accepts arbitrary timespan overrides via prompt (last N days/weeks/months/years, today, explicit date ranges).
• The agent documents the four-step pipeline (fetch → filter → dedupe → structure) so the timespan is clearly just one input parameter.
• For each relevant, non-duplicate entry, an issue is created in PSModule/GitHub following the three-section format, with a link back to the originating changelog entry.
• Relevance filtering rules (include/exclude signals) are described in the agent prompt.
• Deduplication checks existing open issues before creating new ones.
• The agent references and complements issue Add automated GitHub Changelog and API change monitoring workflow #583 (automated scheduled workflow) rather than replacing it.

Relationship to existing work

Issue #583 tracks a scheduled GitHub Actions workflow that performs similar monitoring (RSS parsing + OpenAPI diffing + state persistence + automatic weekly runs). That issue is workflow-focused and automation-first. This issue is complementary, not duplicative:

Aspect	#583 (workflow)	This issue (custom agent)
Trigger	Scheduled (weekly cron) + workflow_dispatch	On-demand chat prompt
Data sources	RSS feed + OpenAPI spec diff	RSS feed
State	Persisted in a changelog-state branch	Stateless — relies on the prompt timespan and open-issue dedupe
Use case	Hands-off, continuous monitoring	Ad-hoc catch-up, backfill, or custom-range reviews
Formats issues	Delegates to issue-manager	Delegates to issue-manager

The scheduled workflow from #583 can, in the future, invoke this custom agent to do its per-entry work — they are designed to compose.

---

Technical decisions

Agent name: changelog-reviewer. Follows the <noun>-<role> naming pattern established by the existing custom agents (issue-manager, pr-manager, pr-reviewer). Chosen over alternatives like changelog-watcher (implies continuous monitoring, which is #583's scope) and changelog-scanner (less aligned with the existing -manager/-reviewer vocabulary). changelog-reviewer correctly conveys that the agent reviews a feed and produces curated output.

Location: The agent definition lives alongside the existing custom agents (issue-manager, pr-manager, pr-reviewer) in the repository's custom agents directory, following the Copilot custom agents convention already in use in this repo — no new location or mechanism is introduced.

Invocation contract:

• Default invocation (no timespan specified): the agent reviews changelog entries from the past 7 days.
• Custom timespan via prompt: the agent parses natural-language timespan instructions from the user's prompt. Supported forms include:
  • Relative windows: "last N days / weeks / months / years", "past week", "yesterday", "today".
  • Explicit ranges: "between YYYY-MM-DD and YYYY-MM-DD", "since YYYY-MM-DD".
• Ambiguous prompts: if the timespan is ambiguous or malformed, the agent asks the maintainer to clarify before proceeding — it does not silently fall back to the default.

Data source: The GitHub Changelog RSS feed is the single data source. Each RSS item provides a title, link, publication date, and HTML body — sufficient to filter, dedupe, and populate a new issue. HTML scraping of https://github.blog/changelog/ is explicitly not used because the RSS feed is more stable and structured. OpenAPI spec diffing is out of scope for this agent (it belongs to #583).

Relevance filter: The agent applies the following rules, documented directly in its prompt:

Signal in entry	Decision
Mentions REST API, GraphQL API, webhook, or an endpoint path (/repos/..., /users/..., etc.)	Include
Title/body contains "API", "endpoint", "REST", "GraphQL", "webhook", or a new API version	Include
Concerns only the GitHub.com UI	Exclude
Scoped to GitHub Enterprise Server only	Exclude
Concerns GitHub Desktop or GitHub Mobile	Exclude
Concerns GitHub Copilot product features with no API surface	Exclude
Ambiguous	Include and flag in the issue for maintainer review

Deduplication: Before creating any issue, the agent searches existing open issues in PSModule/GitHub via the GitHub search API for the exact changelog entry URL in the issue body and for distinctive keywords from the changelog entry title. If any candidate match is found, the agent reports the existing issue number to the maintainer and skips issue creation.

Issue formatting — delegation to issue-manager: The changelog-reviewer agent does not duplicate issue-formatting logic. For each relevant, non-duplicate entry it builds a seed payload (entry title, URL, publication date, summary, suggested labels), then delegates to the existing issue-manager custom agent, which owns the canonical three-section issue format. This keeps a single source of truth for issue structure.

Output to the maintainer: At the end of each run, the agent prints a summary table with: entries fetched, entries filtered out (with reason), entries skipped as duplicates (with existing issue number), and issues created (with new issue number and URL).

Relationship to #583: Documented in the agent prompt. The scheduled workflow in #583 can invoke changelog-reviewer per entry rather than reimplementing the filter/dedupe/format logic.

Breaking changes: None. Adding a new custom agent does not affect module code or existing workflows.

Scope exclusions:

• No OpenAPI spec diffing (belongs to Add automated GitHub Changelog and API change monitoring workflow #583).
• No persistent state / cursor tracking (the timespan is always derived from the prompt or the default).
• No scheduled execution (belongs to Add automated GitHub Changelog and API change monitoring workflow #583).

---

Implementation plan

Agent definition

• Add a new custom agent changelog-reviewer in the same location as issue-manager, pr-manager, pr-reviewer.
• Write the agent description explicitly stating the default timespan is the past 7 days.
• Document supported prompt forms for overriding the timespan (relative windows, explicit date ranges, "today", "yesterday").
• Document behavior on ambiguous timespan prompts (ask for clarification).

Pipeline specification in the agent prompt

• Describe step 1 — fetch: use the GitHub Changelog RSS feed and filter items by publication date to the requested timespan.
• Describe step 2 — filter: include/exclude rules for REST/GraphQL-API relevance (see table in Technical decisions).
• Describe step 3 — dedupe: search open issues in PSModule/GitHub by changelog URL and title keywords.
• Describe step 4 — structure: delegate to issue-manager with a seed payload for each relevant, non-duplicate entry.

Output contract

• Specify the end-of-run summary table format (fetched / filtered / duplicate / created, with reasons and links).
• Specify that each created issue links back to its originating changelog entry.

Documentation

• Add a short note in the repository README (or contributor docs) explaining when to invoke changelog-reviewer vs. letting the scheduled workflow in Add automated GitHub Changelog and API change monitoring workflow #583 run.
• Add example invocation prompts (default, "last 3 months", "today", explicit date range).
• Reference #583 as complementary and describe how the scheduled workflow can invoke changelog-reviewer.

Validation

• Manually invoke the agent with no timespan and verify it reviews the past 7 days.
• Manually invoke with "last 3 months", "today", and an explicit date range, and verify correct timespan handling.
• Verify an entry that matches an existing open issue is skipped, and the existing issue is referenced in the summary.
• Verify a UI-only/GHES-only/Desktop/Mobile/Copilot-only entry is filtered out with a clear reason.
• Verify each created issue follows the three-section format (handled by issue-manager) and links back to the originating changelog entry.