Add reviewer dimension: Implementation–Documentation Alignment#13834
Open
Copilot wants to merge 1 commit into
Open
Add reviewer dimension: Implementation–Documentation Alignment#13834Copilot wants to merge 1 commit into
Copilot wants to merge 1 commit into
Conversation
Agent-Logs-Url: https://github.com/dotnet/msbuild/sessions/032a52d6-730a-4474-9b68-5ddc4b03f863 Co-authored-by: JanProvaznik <25267098+JanProvaznik@users.noreply.github.com>
Copilot created this pull request from a session on behalf of
JanProvaznik
May 21, 2026 15:54
View session
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new review dimension to the @expert-reviewer methodology to explicitly check that behavior changes and their documentation updates land together, and updates the related skill metadata to reflect the expanded 25-dimension framework.
Changes:
- Added Dimension #25: Implementation–Documentation Alignment (Severity: MAJOR) to the expert reviewer agent methodology.
- Updated all methodology count references/examples from 24 → 25 in the agent doc.
- Updated the
reviewing-msbuild-codeskill description/invocation text to reference the 25-dimension methodology and include the new alignment dimension.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
.github/agents/expert-reviewer.agent.md |
Introduces Dimension #25 and updates count/math/examples to reflect 25 total dimensions. |
.github/skills/reviewing-msbuild-code/SKILL.md |
Updates the skill metadata and invocation line to match the 25-dimension methodology. |
Comment on lines
+525
to
+532
| 1. Any change to user-observable behavior (properties, items, targets, tasks, CLI switches, error codes, environment variables, ChangeWaves) must update the matching docs in the same PR: `documentation/wiki/`, `documentation/specs/`, `documentation/*.md`, and any README in the affected folder. | ||
| 2. XML doc comments (`<summary>`, `<param>`, `<returns>`, `<remarks>`) on touched public/protected members must reflect the new behavior. Update — don't just preserve — them when semantics shift. | ||
| 3. When a property default, target order, or task parameter changes, search the docs tree for references to the old behavior and update every occurrence. Don't leave half-updated docs. | ||
| 4. When introducing a ChangeWave, update `documentation/wiki/ChangeWaves.md` in the same PR (see Dimension 2). | ||
| 5. When adding/changing an `MSBxxxx` error or warning code, update any spec or wiki page that enumerates codes or shows example output. | ||
| 6. When changing public API surface, update XML docs and any API reference / sample referenced from `documentation/`. | ||
| 7. Code comments that describe the algorithm must match the post-change algorithm. Stale `// returns null when X` style comments above edited code are a finding. | ||
| 8. If a spec exists for the feature being changed (`documentation/specs/`), update it — don't write a new spec that contradicts the old one without retiring the old one. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
The expert reviewer's 24-dimension methodology had no dimension explicitly checking that code changes ship with the corresponding doc updates in the same PR. Existing dimension #18 (Documentation Accuracy) covers general doc quality (XML comments, spec completeness,
learn.microsoft.comURLs) but doesn't target alignment — the case where a behavior change lands without updating the wiki/spec/XML-doc/sample that describes the old behavior.Changes Made
.github/agents/expert-reviewer.agent.md(Severity: MAJOR). Rules cover: behavior changes requiring matching updates underdocumentation/wiki/,documentation/specs/, READMEs; XML doc comments on touched members reflecting new semantics; ChangeWave additions updatingChangeWaves.md; new/changedMSBxxxxcodes synced with docs that enumerate them; public API changes synced with reference docs/samples; stale inline// returns null when Xcomments above edited code; full sweep when renames or defaults change so half-updated docs aren't left behind.description, intro line, Wave 1 batch math (4 batches→5 batches of 6), and Wave 4 summary-table examples (22/24→23/25,24/24→25/25)..github/skills/reviewing-msbuild-code/SKILL.md: description and invocation line updated to the 25-dimension methodology, with "implementation/documentation alignment" added to the category list.Testing
N/A — spec/skill text only; no code, build, or test changes.
Notes
Distinct from #18: #18 asks "is the doc well-written and accurate in isolation"; #25 asks "did this PR keep code and docs in sync". Both can fire on the same PR.