📝 improve copilot review comment structure#143
Conversation
- prescribe exact format: score with Why/Why-not paragraphs, findings severity table, Mermaid architectural flow - suppress per-file summaries in favour of concern-based grouping
There was a problem hiding this comment.
Pull request overview
This PR updates .github/copilot-instructions.md to prescribe a stricter, more structured format for Copilot-generated PR review comments (score rationale, severity table for findings, and an architectural flow section with a Mermaid diagram), and to avoid per-file summary output.
Changes:
- Adds an exact, templated review comment structure including “Why X.X” / “Why not …” score rationale, a severity findings table, and an architectural flow section requiring a Mermaid diagram.
- Adds guidance to group feedback by concern/severity rather than by file.
Architectural flow (of this change)
Before: Copilot review comments were guided by a few high-level bullets (include an architectural flow section; include a 1–5 score with justification), leaving structure largely free-form.
After: Copilot review comments are expected to follow a fixed outline: a scored header, explicit “why/why not” score rationale, a tabular findings section with severity labels, and an architectural flow section that must include a Mermaid diagram plus a before/after boundary narrative.
PR Score: 3.6 / 5
Why 3.6: The new structure is concrete and should materially improve review consistency and scannability (severity table, explicit score rationale, mandated Mermaid diagram + before/after narrative).
Why not 4.6: The template currently has a scale/wording issue (“Why not X+1” breaks at 5.0 and is awkward near the upper bound), and it also removes prior process guidance about checking recent history with git log without calling that out in the PR description.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 48473cc549
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
| - Identify potential regressions in functionality or performance. | ||
| - For files touched by the PR, use `git log` to inspect recent commit history and search for merged | ||
| PRs touching the same files. Flag cases where this PR might undo or conflict with recent | ||
| intentional changes, citing the relevant commit hash or PR reference. | ||
| - Explain the architectural flow of the change in a separate section of your review comment. | ||
| - Score the PR between 1 and 5 (one decimal place). Be critical and justify the score. | ||
| - Do not include per-file summaries. Group all feedback by concern or severity, not by file. |
| **Why X.X:** <Specific factors that drove the score — correct design, test coverage, clean | ||
| boundaries, etc.> | ||
|
|
||
| **Why not higher:** <Specific gaps that prevented a higher score — missing tests, observability | ||
| tradeoffs, untested transitive changes, etc.> |
| Explain the architectural flow of the change. Include a Mermaid diagram (sequence diagram or | ||
| flowchart — pick whichever best represents the change) followed by a before/after narrative | ||
| describing what changed at the boundary level. |
Motivation
Copilot reviews lacked structure: the score was not explained, per-file summaries cluttered the output, and there was no diagram in the architectural flow section. This prescribes an explicit output format modelled on a high-quality Cursor review for the same codebase.
Changes
**Why X.X:**/**Why not X+1:**paragraphs so reviewers understand what drove the scoreBlocking / Minor / Nit) for findings instead of prose per fileTest instructions
Trigger a Copilot review on any open PR and verify the comment follows the new structure.
Checklist