chore(review): require inline comments for code-specific suggestions; keep summary brief and non-actionable; adjust formatting and README to reflect inline review flow (#1)

Author: mtpauly

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
 

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:

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:

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