agents: streamline code review report format to omit passing prose (#4340) Listing passing checks in sub-agent reports and `code-review-results.md` adds noise that obscures actionable violations and questions requiring human sign-off. Update the review report format and `review-code` skill to omit passing prose, return a single status line when clean, and structure `code-review-results.md` around open issues, resolved issues, and a comma-separated list of passing domains.
diff --git a/.agents/rules/pr.md b/.agents/rules/pr.md index cc85c66..fa57882 100644 --- a/.agents/rules/pr.md +++ b/.agents/rules/pr.md
@@ -52,5 +52,5 @@ * During code review, inspect the PR description and comments for open questions, `TODO` items, or "Things we could do / follow-up" notes. Evaluate each item against the diff and project rules, flag unresolved - items with `ACTION_REQUIRED` or `USER_DECISION_REQUIRED`, and verify the + items with `BLOCKER`, `QUESTION`, or `HUMAN-SIGN-OFF`, and verify the `"do not merge"` label is applied if open questions remain.
diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index ee1d222..5cf6e12 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md
@@ -85,12 +85,39 @@ committed and uncommitted branch changes without newer `upstream/main` commits. - Launch all sub-agents concurrently using `invoke_subagent`. -- Update `code-review-results.md` as sub-agent responses come in. -- The artifact must include: - - Overall summary and verdict across audit categories. - - Detailed analysis and findings from each sub-agent. - - Actionable findings and fix suggestions with specific code snippets, diffs, - and clickable file links for any violations found. +- Update `code-review-results.md` as sub-agent responses come in, omitting all + passing-check prose. Do not use bold for the introduction or lead-in of a + bulleted list or bullet item; use **bold** for any questions the user needs + to answer. Structure `code-review-results.md` as follows: + + ````markdown + # Code Review: <Target / PR> + + Verdict: `<PASS | NEEDS_FIXES | NEEDS_HUMAN_SIGN_OFF>` (<N> open, <H> + needing human sign-off, <M> resolved) + + ## Open Issues + + ### <ID>. [<SEVERITY>] <Short title> — [<file>:<line>](file:///...) + * Problem: <1-2 sentences stating what is wrong and why.> + * Proposed Fix: + ```<lang> + <replacement snippet or diff> + ``` + * Draft Comment: `<comment text in user's voice>` + * Author Response: <If the author replied to this comment thread, quote or + summarize their response here, bolding any question to answer.> + * Draft Reply: `<proposed reply in user's voice, if applicable>` + + ## Resolved Issues + + * ~~<ID>. [<SEVERITY>] <Short title> ([<file>:<line>](file:///...))~~ — + Resolved: <How it was fixed or resolved (e.g., fixed in commit N, + updated in working copy, or dismissed per reviewer).> + + ## Passing Domains + <Comma-separated list of audited domains with 0 issues> + ```` - Once all sub-agents finish, finalize `code-review-results.md` and provide a concise summary with the overall verdict and a clickable markdown link to `code-review-results.md` in the response.
diff --git a/.agents/skills/review-code/review-pr-standards-prompt.md b/.agents/skills/review-code/review-pr-standards-prompt.md index c389e30..89a4d90 100644 --- a/.agents/skills/review-code/review-pr-standards-prompt.md +++ b/.agents/skills/review-code/review-pr-standards-prompt.md
@@ -15,8 +15,8 @@ 5. Inspect the PR description and comments for open questions, `TODO` items, or "Things we could do / follow-ups" sections. Evaluate each item against the diff and project rules, flag items requiring resolution or user input - with `ACTION_REQUIRED` or `USER_DECISION_REQUIRED`, and verify the PR has - the `"do not merge"` label when open questions are present (add it or flag - as `ACTION_REQUIRED` if missing). + with `BLOCKER`, `QUESTION`, or `HUMAN-SIGN-OFF`, and verify the PR has the + `"do not merge"` label when open questions are present (add it or flag as + `BLOCKER` if missing). @.agents/skills/review-code/review-report-format.md
diff --git a/.agents/skills/review-code/review-report-format.md b/.agents/skills/review-code/review-report-format.md index a5c45c7..b468f2d 100644 --- a/.agents/skills/review-code/review-report-format.md +++ b/.agents/skills/review-code/review-report-format.md
@@ -1,6 +1,17 @@ -Provide a structured report containing: -- Status: PASS, WARNING, ACTION_REQUIRED, USER_DECISION_REQUIRED, or - NOT_APPLICABLE -- Detailed analysis and findings for each item checked -- Actionable findings and fix suggestions with specific code snippets, diffs, - and clickable file links for any violations found +Report ONLY problems/violations found. Omit passing checks entirely. If no +issues or rule-exception justifications requiring sign-off are found, return a +single line: `Status: PASS` (or `NOT_APPLICABLE`). + +Do not use bold for the introduction or lead-in of a bulleted list or bullet +item. Use **bold** for any questions the user needs to answer. + +For each issue found, provide: + +- Title: `<Short issue title>` +- Severity: `BLOCKER` | `SHOULD-FIX` | `NIT` | `QUESTION` | `HUMAN-SIGN-OFF` +- Location: `[<file>:<line>](file:///...#L...)` (or `PR Description`) +- Problem: 1-2 sentences stating what is wrong and why (or, for + `HUMAN-SIGN-OFF`, quoting the author's justification and evaluating whether + it holds up). +- Proposed Fix: Concrete code snippet, diff, or replacement text. +- Draft Comment: Ready-to-post comment in user's voice.