Azure / Azure/azure-rest-api-specs
ARM API Reviewer agent: support read-only interactive reviews of a local, unmerged specification
- 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
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