From 4a3e1a3651ee93a9508a36a0b21172409ec2492d Mon Sep 17 00:00:00 2001 From: Matt Pauly Date: Tue, 5 Aug 2025 20:48:08 +0000 Subject: [PATCH] chore(review): require inline comments for code-specific suggestions; keep summary brief and non-actionable; adjust formatting and README to reflect inline review flow --- README.md | 2 +- templates/formatting/base.njk | 5 +++-- templates/guidelines/base.njk | 6 +++--- templates/request/base.njk | 7 ++++--- 4 files changed, 11 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 74ed5f0..2871d20 100644 --- a/README.md +++ b/README.md @@ -87,7 +87,7 @@ Each example includes a complete workflow file that you can copy to your `.githu 2. **Data Gathering**: Fetches PR metadata, changed files, and diff content from GitHub API 3. **Template Rendering**: Uses Nunjucks templates to create a structured instruction for the AI 4. **AI Processing**: Calls the Augment Agent to analyze the changes and generate a review -5. **PR Update**: The Augment Agent updates the PR description with the generated review content +5. **PR Review Submission**: The Augment Agent submits a single GitHub review containing a brief summary and multiple inline comments anchored to specific lines in the PR diff (including suggestion blocks where appropriate) ## Custom Guidelines diff --git a/templates/formatting/base.njk b/templates/formatting/base.njk index 9fb9f88..e3fb887 100644 --- a/templates/formatting/base.njk +++ b/templates/formatting/base.njk @@ -14,8 +14,9 @@ ### Code References: - Use backticks for inline code references (function names, variables, etc.) -- Use code blocks for multi-line code examples -- Include file paths and line numbers when referencing specific code locations +- In inline review comments, prefer GitHub suggestion blocks (```suggestion) for concrete code changes; ensure patches are minimal and accurate +- Do not include code blocks or specific code suggestions in the top-level review summary +- Include file paths and line numbers only within inline comments (not in the summary) - Use proper syntax highlighting when showing code examples ### Links and References: diff --git a/templates/guidelines/base.njk b/templates/guidelines/base.njk index 6d99e33..8d82c88 100644 --- a/templates/guidelines/base.njk +++ b/templates/guidelines/base.njk @@ -14,12 +14,12 @@ ### Comment Guidelines: - **HIGH CONFIDENCE ONLY**: Only suggest changes you are highly confident will improve the code -- Be specific and reference exact lines or sections of code -- Provide clear explanations of issues and suggest concrete improvements +- Post one inline comment per distinct issue and location, anchored to the exact file and line in the PR diff +- Provide clear explanations of issues and suggest concrete improvements; when proposing code, use GitHub suggestion blocks in inline comments - Use a constructive, helpful tone - focus on the code, not the person - Include examples of better approaches when suggesting changes - Prioritize critical issues over minor style preferences -- Group related comments together when possible +- Do not group multiple issues into a single comment; if an issue spans multiple locations, post separate inline comments and mention they are related - **Quality over quantity**: Better to miss some issues than create noise with low-value suggestions ### Review Focus Areas: diff --git a/templates/request/base.njk b/templates/request/base.njk index 2ce1b75..68cdfbc 100644 --- a/templates/request/base.njk +++ b/templates/request/base.njk @@ -28,9 +28,10 @@ You are conducting a comprehensive code review for PR #{{ pr.number }}. You have ## Action Required: - Use GitHub's review system to post your feedback directly on the relevant lines of code in the PR -- Suggested changes should be used to make it easier to adopt your suggestions -- **IMPORTANT:** All of your comments should be sent as a single review, not as separate reviews -- Do not post comments outside of the single review +- For any code-specific issue, you MUST post an inline review comment anchored to the exact file and line in the PR diff; when proposing code changes, use GitHub suggestion blocks (```suggestion ... ```) +- The review summary MUST be at most 3 sentences and MUST NOT include code-specific suggestions, code blocks, or file/line references. Do not repeat details from inline comments. +- Submit a single GitHub review containing your inline comments plus the brief summary. Do not create multiple reviews. +- If you cannot find a valid diff anchor for a code-specific suggestion, comment on the closest changed line and clearly reference the exact location; only if no anchor is possible, write one short general comment for that item. - Never use "REQUEST_CHANGES" or "APPROVE" - If no line-specific suggestions, post a general comment like "Review completed. No suggestions at this time." - Only a single review should be created, never multiple reviews