agents: structure review-code draft comments with suggested fix and where (#4431) Free-form draft review comments can omit concrete remediation steps, include overly long code blocks, or fail to note other locations where the same issue occurs. Update `.agents/skills/review-code/SKILL.md` and `review-report-format.md` to structure `Draft Comment` entries with a concise issue description, a bounded `Suggested fix:` (under 20 lines / 10 sentences), and a `Where:` line listing any additional locations.
diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index 0d19668..580db85 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md
@@ -147,7 +147,15 @@ ```<lang> <replacement snippet or diff> ``` - * Draft Comment: `<comment text in user's voice>` + * Draft Comment (in user's voice): + ```markdown + <brief/concise description of issue> + + Suggested fix: <fix, under 20 lines / 10 sentences> + + Where: <other locations where this is applicable, if more than just the + commented location> + ``` * 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>`
diff --git a/.agents/skills/review-code/review-report-format.md b/.agents/skills/review-code/review-report-format.md index b468f2d..30ba9c7 100644 --- a/.agents/skills/review-code/review-report-format.md +++ b/.agents/skills/review-code/review-report-format.md
@@ -14,4 +14,12 @@ `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. +- Draft Comment: Ready-to-post comment in user's voice, structured as: + ```markdown + <brief/concise description of issue> + + Suggested fix: <fix, under 20 lines / 10 sentences> + + Where: <other locations where this is applicable, if more than just the + commented location> + ```