Azure / Azure/azure-rest-api-specs

ARM API Reviewer agent: support read-only interactive reviews of a local, unmerged specification

Open
#45,947 0 comments 0 reactions 0 assignees View on GitHub
ARM API Reviewer agent
Dominant language
TypeSpec
Stars
3.1k
Forks
5.9k
Avg merge
3d 2h
Merged PRs (30d)
424

Description

## Problem

The interactive ARM API Reviewer agent's workflow is written around reviewing a pull request: it fetches PR metadata, diffs, and file contents through `gh`/GitHub MCP tools, and its reconciliation logic inventories PR review threads and comments. A user working in VS Code or the GitHub Copilot app who wants the agent to review a specification directory that is still under local development — not yet pushed, not yet a PR — had no supported path to do so, even though the same rule set and breaking-change checks are exactly what would be useful at that earlier stage, before a PR even exists.

## Evidence

- Raised directly as a follow-up question during this session: whether a user could ask the agent to review a local, in-progress spec path (e.g., a `resource-manager/Microsoft.Contoso/...preview/...` folder on disk) and get the same findings and breaking-change checks as a PR review.
- The agent's existing Review Workflow steps (PR fetch, diff construction, PR-comment reconciliation) have no local-filesystem equivalent path documented; a user attempting this today gets undefined behavior rather than a supported "local mode."
- This is one of the two RP Day themes (consistency and reliability) extended to a new entry point rather than just the two existing ones (automated PR workflow, interactive PR review).

## Proposed Solution (implemented in PR #45841)

1. Add a read-only local specification review mode to the interactive agent: when the user points the agent at a local directory instead of a PR, it applies the same instruction files, shared skill references, and breaking-change comparison logic, using the local filesystem in place of PR file-fetch calls.
2. Scope this mode explicitly as read-only — it must not attempt to post PR comments, resolve threads, or apply labels, since none of those exist for an unmerged local spec. Findings are reported directly in the chat/Copilot session instead.
3. For breaking-change comparison, use the same immutable-base-SHA-derived previous-version fetch used elsewhere in this hardening effort, so a local review's "previous version" baseline is unambiguous and matches what a subsequent PR review of the same change would compare against.
4. Document the new mode and a worked example path (using a generic placeholder such as `Microsoft.Contoso`, no real PR numbers) in `documentation/api-reviewer-agent.md`.

## Labels

`ARM API Reviewer agent`

Contributor guide

Open the contributing guide

Research direction

Start by reviewing PR #45841 and the interactive agent's existing Review Workflow, including its PR fetch, diff, and reconciliation steps. Then read documentation/api-reviewer-agent.md and compare the documented local-mode example with the proposed read-only behavior. Done means local specifications use the shared review and breaking-change logic without PR comments, thread resolution, or labels.

Written by the indexing model from the issue text.

Assessment

Tech stack
github, vscode
Domain
documentation, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.