From 385576880d23e5d62994bbda205d54cd285da258 Mon Sep 17 00:00:00 2001 From: Nabin Mulepati Date: Mon, 30 Mar 2026 09:56:25 -0600 Subject: [PATCH 1/3] chore: update review-code skill output and tone - Remove Overview metadata table from review output - Add cordial tone guidelines and thank-you opening - Tie verdict strictly to highest-severity finding - Soften severity section headers - Add Step 7 to post review as GitHub PR comment - Omit empty severity sections from output Closes #476 Made-with: Cursor --- .agents/skills/review-code/SKILL.md | 74 ++++++++++++++--------------- 1 file changed, 36 insertions(+), 38 deletions(-) diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index 910664269..3febfeba3 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -191,38 +191,21 @@ If the branch isn't checked out locally (e.g., external fork in PR mode), skip t ## Step 6: Produce the Review -Output a structured review using the format below. Use the **PR template** or **Branch template** for the overview depending on the mode. +Write the review as **GitHub-flavored Markdown** ready to post as a PR comment. Save it to a temporary file outside the repository (e.g. `/tmp/review-.md`) so it doesn't pollute `git status`. Do not commit this file; treat it as ephemeral. -Write the review to a **temporary markdown file outside the repository** (e.g. `/tmp/review-.md`) so other agents or tools can consume it without polluting `git status`. Do not commit this file; treat it as ephemeral. +Use the template below exactly — omit a severity section if it has no findings, but keep all other sections. --- -### Overview (PR mode) +Open with a brief, genuine thank-you to the author (e.g. "Thanks for putting this together, @author!" or "Nice work on this one, @author — here are my thoughts."). Keep it to one sentence; don't over-do it. Do NOT add a top-level title like "## Code Review" — the comment speaks for itself. -| | | -|---|---| -| **PR** | [#\ \](\) | -| **Author** | `` | -| **Base** | `` | -| **Files changed** | `` | -| **Insertions/Deletions** | `+ / -` | +### Summary -### Overview (Branch mode) - -| | | -|---|---| -| **Branch** | `` | -| **Commits** | `` commits ahead of `` | -| **Files changed** | `` | -| **Insertions/Deletions** | `+ / -` | - -### (Both modes) - -**Summary**: 1-2 sentence description of what the changes accomplish. In PR mode, note whether the implementation matches the stated intent in the PR description. +1-2 sentence description of what the changes accomplish. In PR mode, note whether the implementation matches the stated intent in the PR description. ### Findings -Group findings by severity. Format each finding as a heading + bullet list — do NOT use numbered lists: +Group findings by severity. Omit any severity section that has no findings. Format each finding as a heading + bullet list — do NOT use numbered lists: ``` **`path/to/file.py:42` — Short title** @@ -231,39 +214,54 @@ Group findings by severity. Format each finding as a heading + bullet list — d - **Suggestion**: Concrete fix or improvement (with code snippet when helpful). ``` -Separate each finding with a blank line. Use bold file-and-title as a heading line, then bullet points for What/Why/Suggestion. Never use numbered lists (`1.`, `2.`) for findings or their sub-items — they render poorly in terminals. +Separate each finding with a blank line. Use bold file-and-title as a heading line, then bullet points for What/Why/Suggestion. Never use numbered lists (`1.`, `2.`) for findings or their sub-items. -#### Critical — Must fix before merge +#### Critical — Let's fix these before merge > Issues that would cause bugs, data loss, security vulnerabilities, or broken functionality. -#### Warnings — Strongly recommend fixing +#### Warnings — Worth addressing > Design issues, missing error handling, test gaps, or violations of project standards that could cause problems later. -#### Suggestions — Consider improving +#### Suggestions — Take it or leave it > Style improvements, minor simplifications, or optional enhancements that would improve code quality. ### What Looks Good -Call out 2-3 things done well (good abstractions, thorough tests, clean refactoring, etc.). Positive feedback is part of a good review. +Call out 2-3 things done well (good abstractions, thorough tests, clean refactoring, etc.). Be genuine — positive feedback is part of a good review and helps the author know what to keep doing. ### Verdict -One of: -- **Ship it** — No critical issues, ready to merge -- **Ship it (with nits)** — Minor suggestions but nothing blocking -- **Needs changes** — Has issues that should be addressed before merge -- **Needs discussion** — Architectural or design questions that need team input +Choose the verdict that matches the **highest severity** finding in the review: + +- **Ship it** — No findings. Ready to merge as-is. +- **Ship it (with nits)** — Only Suggestions (minor stylistic preferences that may vary between developers while still conforming to the style guide). Nothing blocking. +- **Needs changes** — Any Critical or Warning findings. List the items that must be addressed before merge. +- **Needs discussion** — Architectural or design questions that need team input before a decision can be made. + +--- + +## Step 7: Post the Review (PR mode only) -### Next steps (optional) +In PR mode, post the review as a comment on the pull request: -After the summary, you may suggest follow-ups when useful: +```bash +gh pr comment --body-file /tmp/review-.md +``` -- Deep dive into a specific file or finding -- Check a specific concern in more detail -- Install dev deps and add smoke tests (e.g. `uv sync --all-extras`, then run tests or suggest minimal smoke tests) +In branch mode, skip this step — display the review to the user and note the temp file path. --- +## Tone + +Write as a supportive teammate, not a gatekeeper. The goal is to help the author ship great code, not to prove you found problems. + +- **Be cordial and collaborative.** Use "we" language and frame findings as questions or suggestions ("Could we …?", "What do you think about …?", "Nice approach — one thought: …"). +- **Assume good intent.** If something looks off, ask before assuming it's wrong — the author may have context you don't. +- **Lead with what's good.** Acknowledge effort and smart decisions before raising concerns. +- **Keep it conversational.** Avoid stiff, formal phrasing. Write the way you'd talk to a colleague at a whiteboard. +- **Be direct, not blunt.** Clearly state what needs to change and why, but without harsh or commanding language ("This must be fixed" → "This could bite us in production — worth addressing before merge"). + ## Review Principles - **Only flag what's new**: Report issues introduced by this changeset — not pre-existing patterns or style in untouched code, unless explicitly asked by the user From 5ac0ba2148cb78fde4250a82249d3a4e0e194481 Mon Sep 17 00:00:00 2001 From: Nabin Mulepati Date: Mon, 30 Mar 2026 10:14:30 -0600 Subject: [PATCH 2/3] address greptile comments --- .agents/skills/review-code/SKILL.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index 3febfeba3..263d5db44 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -189,6 +189,16 @@ Run the linter on all changed files (requires local checkout). Use the venv dire If the branch isn't checked out locally (e.g., external fork in PR mode), skip this step and note it in the review. +## Tone + +Write as a supportive teammate, not a gatekeeper. The goal is to help the author ship great code, not to prove you found problems. + +- **Be cordial and collaborative.** Use "we" language and frame findings as questions or suggestions ("Could we …?", "What do you think about …?", "Nice approach — one thought: …"). +- **Assume good intent.** If something looks off, ask before assuming it's wrong — the author may have context you don't. +- **Lead with what's good.** Acknowledge effort and smart decisions before raising concerns. +- **Keep it conversational.** Avoid stiff, formal phrasing. Write the way you'd talk to a colleague at a whiteboard. +- **Be direct, not blunt.** Clearly state what needs to change and why, but without harsh or commanding language ("This must be fixed" → "This could bite us in production — worth addressing before merge"). + ## Step 6: Produce the Review Write the review as **GitHub-flavored Markdown** ready to post as a PR comment. Save it to a temporary file outside the repository (e.g. `/tmp/review-.md`) so it doesn't pollute `git status`. Do not commit this file; treat it as ephemeral. @@ -242,7 +252,7 @@ Choose the verdict that matches the **highest severity** finding in the review: ## Step 7: Post the Review (PR mode only) -In PR mode, post the review as a comment on the pull request: +In PR mode, display the review to the user and note the temp file path (`/tmp/review-.md`). Then ask if they'd like you to post it as a PR comment. Only run the command after the user confirms: ```bash gh pr comment --body-file /tmp/review-.md @@ -252,16 +262,6 @@ In branch mode, skip this step — display the review to the user and note the t --- -## Tone - -Write as a supportive teammate, not a gatekeeper. The goal is to help the author ship great code, not to prove you found problems. - -- **Be cordial and collaborative.** Use "we" language and frame findings as questions or suggestions ("Could we …?", "What do you think about …?", "Nice approach — one thought: …"). -- **Assume good intent.** If something looks off, ask before assuming it's wrong — the author may have context you don't. -- **Lead with what's good.** Acknowledge effort and smart decisions before raising concerns. -- **Keep it conversational.** Avoid stiff, formal phrasing. Write the way you'd talk to a colleague at a whiteboard. -- **Be direct, not blunt.** Clearly state what needs to change and why, but without harsh or commanding language ("This must be fixed" → "This could bite us in production — worth addressing before merge"). - ## Review Principles - **Only flag what's new**: Report issues introduced by this changeset — not pre-existing patterns or style in untouched code, unless explicitly asked by the user From ec811a43e0aa44192f2a3433113d2c55dc274423 Mon Sep 17 00:00:00 2001 From: Nabin Mulepati Date: Tue, 31 Mar 2026 16:19:01 -0600 Subject: [PATCH 3/3] add signature portion --- .agents/skills/review-code/SKILL.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index 263d5db44..7e0b59ae7 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -244,10 +244,21 @@ Call out 2-3 things done well (good abstractions, thorough tests, clean refactor Choose the verdict that matches the **highest severity** finding in the review: - **Ship it** — No findings. Ready to merge as-is. -- **Ship it (with nits)** — Only Suggestions (minor stylistic preferences that may vary between developers while still conforming to the style guide). Nothing blocking. +- **Ship it (with nits)** — Only Suggestions (see above — style improvements, simplifications, or optional enhancements). Nothing blocking. - **Needs changes** — Any Critical or Warning findings. List the items that must be addressed before merge. - **Needs discussion** — Architectural or design questions that need team input before a decision can be made. +### Signature (PR mode only) + +When the review will be posted as a PR comment, end with a signature line so readers can distinguish agent-generated reviews from human ones: + +``` +--- +*This review was generated by an AI assistant.* +``` + +In branch mode (local only), omit the signature. + --- ## Step 7: Post the Review (PR mode only)