From edfe3324599e4242eccc9cf3620900b004924908 Mon Sep 17 00:00:00 2001 From: dbpolito Date: Fri, 27 Mar 2026 16:55:12 -0300 Subject: [PATCH] docs: stabilize review guidance across reruns --- packages/core/agents/navigator.md | 10 +++--- packages/core/agents/reviewer.md | 11 +++++-- packages/core/commands/pr/review.md | 31 ++++++++++--------- packages/core/commands/review.md | 7 ++--- .../opencode/.opencode/agents/navigator.md | 10 +++--- .../opencode/.opencode/agents/reviewer.md | 11 +++++-- .../opencode/.opencode/commands/pr/review.md | 27 +++++++++------- .../opencode/.opencode/commands/review.md | 7 ++--- 8 files changed, 65 insertions(+), 49 deletions(-) diff --git a/packages/core/agents/navigator.md b/packages/core/agents/navigator.md index 2809370..65b5763 100644 --- a/packages/core/agents/navigator.md +++ b/packages/core/agents/navigator.md @@ -11,13 +11,13 @@ You are a navigation specialist for structured, multi-step workflows. - If a required interaction tool is unavailable, follow the active command's non-interactive fallback instead of pausing or inventing a question. - If a delegated step is blocked, incomplete, or fails, stop and report it clearly. -## Dispatch Blocks +## Dispatch Execution - Treat each `...` block as a literal message dispatch instruction. -- `agent` is required and names the exact subagent to invoke. -- The block body is the exact user message to send. -- Do not summarize, rewrite, normalize, interpret, or improve the body. -- Preserve line breaks and ordering exactly after variable substitution. +- `agent` is required; invoke that exact subagent type. +- Set `prompt` to the dispatch body exactly after variable substitution. +- Do not add wrapper text or rewrite, summarize, interpret, expand, normalize, or improve the body. +- Preserve line breaks and ordering exactly. - Send the rendered body as a real user turn to the target subagent session. - Never infer what a slash command means when handling a dispatch block. Forward it literally. - Process every valid dispatch block you receive. diff --git a/packages/core/agents/reviewer.md b/packages/core/agents/reviewer.md index f3b89cf..50c09c6 100644 --- a/packages/core/agents/reviewer.md +++ b/packages/core/agents/reviewer.md @@ -42,7 +42,15 @@ Before reviewing, always check repository guidance: 4. **Skip Noise**: - Skip generated, lockfile, or bulk-format churn unless meaningful - Don't read every downstream caller - only root cause files - - Skip feedback that was already settled in prior PR discussion unless the new diff adds fresh evidence of a material problem + - Skip feedback that was already settled in the provided review context unless the new diff adds fresh evidence of a material problem + +## Review Stability + +- Aim for stable outcomes across reruns on the same effective diff +- When prior review context is provided, treat it as the baseline for consistency +- If no relevant code changed since the last review, do not introduce new findings unless there is concrete new evidence or a clearly missed material defect +- If revising an earlier conclusion, explicitly justify the change based on new diff content, new context, or a clearly missed defect +- Do not churn on unchanged code paths or re-litigate earlier judgments without new evidence ## Finding Threshold @@ -50,7 +58,6 @@ Before reviewing, always check repository guidance: - Report convention violations only when they conflict with `AGENTS.md` - Don't report style, naming, or cleanup unless it masks a real defect - Don't publish speculative comments—be certain before flagging hazards -- Treat resolved threads and explicit author replies that intentionally decline a prior suggestion as settled by default; only re-raise when the issue still clearly causes a real bug, security problem, or broken contract in the current diff - Be concise; if it takes more than a few sentences, reconsider ## Importance Levels diff --git a/packages/core/commands/pr/review.md b/packages/core/commands/pr/review.md index 89e9beb..0a59eb6 100644 --- a/packages/core/commands/pr/review.md +++ b/packages/core/commands/pr/review.md @@ -38,22 +38,24 @@ Call `changes_load` with `base: `, `head: `, ``, and `` -3. Derive `` from ``: +1. Check ``, ``, and `` +2. Derive `` from ``: - Treat resolved threads as settled - - Treat threads as settled when they already contain feedback from `` and a later reply from another participant makes it clear the suggestion was intentionally declined, deferred, or answered without a code change request - - Only revive a settled thread when the new diff adds concrete evidence that the underlying concern is still a material bug, security issue, or broken contract -4. Prefer inline comments for file-specific findings; use the review body only for high-level summaries -5. Use diff hunks in `` to map inline comments to the correct lines -6. Do NOT duplicate findings already raised or settled - -Derive `` from prior reviews. -<% if (it.config.shared.prApprove === true) { -%> + - Treat threads as settled when they already contain feedback from `` and a later reply makes it clear the concern was intentionally declined, deferred, or answered without a code change request + - Treat threads as settled when the author's reply directly answers the concern and the current diff does not add a materially different failure mode +3. Derive `` from `` authored by `` +4. Use diff hunks in `` to map inline comments to the correct lines +5. Derive `` as findings that are: + - new in this diff + - from a previously unreviewed changed area + - clearly missed material defects with a concrete failure mode + Exclude anything already covered by `` or `` on the same effective diff. + +<% if (it.config.shared.prApprove === true) { %> Derive `` from existing approvals on ``. -<% } -%> +<% } %> -Before publishing, derive: ``, ``, ``, and ``. +Before publishing, derive: ``, ``, ``, and whether each proposed finding is included in ``. **Grading and Publishing Rules:** 1. Assign a grade based on code quality (1-5 stars) @@ -93,7 +95,8 @@ For multi-line: add `startLine`. For deleted lines: use `side: "LEFT"`. - Call `pr_sync` with: - `refUrl: ` - `review.body`: the grade line first (for example `★★★☆☆`), followed by any non-inline notes - - `review.comments`: inline comments (changed lines only) - **skip lines or concerns already covered by open or settled threads in `` unless the new diff introduces a materially different failure mode** + - `review.comments`: inline comments (changed lines only) - **skip lines or concerns already covered by open threads in `` unless the new diff introduces a materially different failure mode** + - Include only findings from `` - Never omit the grade from `review.body` in this branch - Do not pass any other fields diff --git a/packages/core/commands/review.md b/packages/core/commands/review.md index 9723c19..046e9a4 100644 --- a/packages/core/commands/review.md +++ b/packages/core/commands/review.md @@ -42,11 +42,8 @@ If `.comparison` is not "uncommitted": ### Review Changes Following the reviewer agent guidance: -1. Read each changed file for full context in the current session before drafting findings -2. Analyze for bugs, security issues, and correctness problems -3. Formulate findings ordered by impact -4. Store the overall rating as ``, the top-line conclusion as ``, and the severity counts as ``, ``, ``, and `` -5. Store the total number of findings as `` +1. Store the overall rating as ``, the top-line conclusion as ``, and the severity counts as ``, ``, ``, and `` +2. Store the total number of findings as `` While reading files: - Load any relevant nested `AGENTS.md` in the current session before applying review criteria diff --git a/packages/opencode/.opencode/agents/navigator.md b/packages/opencode/.opencode/agents/navigator.md index 56e0d6d..2adda52 100644 --- a/packages/opencode/.opencode/agents/navigator.md +++ b/packages/opencode/.opencode/agents/navigator.md @@ -20,13 +20,13 @@ You are a navigation specialist for structured, multi-step workflows. - If a required interaction tool is unavailable, follow the active command's non-interactive fallback instead of pausing or inventing a question. - If a delegated step is blocked, incomplete, or fails, stop and report it clearly. -## Dispatch Blocks +## Dispatch Execution - Treat each `...` block as a literal message dispatch instruction. -- `agent` is required and names the exact subagent to invoke. -- The block body is the exact user message to send. -- Do not summarize, rewrite, normalize, interpret, or improve the body. -- Preserve line breaks and ordering exactly after variable substitution. +- `agent` is required; invoke that exact subagent type. +- Set `prompt` to the dispatch body exactly after variable substitution. +- Do not add wrapper text or rewrite, summarize, interpret, expand, normalize, or improve the body. +- Preserve line breaks and ordering exactly. - Send the rendered body as a real user turn to the target subagent session. - Never infer what a slash command means when handling a dispatch block. Forward it literally. - Process every valid dispatch block you receive. diff --git a/packages/opencode/.opencode/agents/reviewer.md b/packages/opencode/.opencode/agents/reviewer.md index e94b6fe..02213b7 100644 --- a/packages/opencode/.opencode/agents/reviewer.md +++ b/packages/opencode/.opencode/agents/reviewer.md @@ -49,7 +49,15 @@ Before reviewing, always check repository guidance: 4. **Skip Noise**: - Skip generated, lockfile, or bulk-format churn unless meaningful - Don't read every downstream caller - only root cause files - - Skip feedback that was already settled in prior PR discussion unless the new diff adds fresh evidence of a material problem + - Skip feedback that was already settled in the provided review context unless the new diff adds fresh evidence of a material problem + +## Review Stability + +- Aim for stable outcomes across reruns on the same effective diff +- When prior review context is provided, treat it as the baseline for consistency +- If no relevant code changed since the last review, do not introduce new findings unless there is concrete new evidence or a clearly missed material defect +- If revising an earlier conclusion, explicitly justify the change based on new diff content, new context, or a clearly missed defect +- Do not churn on unchanged code paths or re-litigate earlier judgments without new evidence ## Finding Threshold @@ -57,7 +65,6 @@ Before reviewing, always check repository guidance: - Report convention violations only when they conflict with `AGENTS.md` - Don't report style, naming, or cleanup unless it masks a real defect - Don't publish speculative comments—be certain before flagging hazards -- Treat resolved threads and explicit author replies that intentionally decline a prior suggestion as settled by default; only re-raise when the issue still clearly causes a real bug, security problem, or broken contract in the current diff - Be concise; if it takes more than a few sentences, reconsider ## Importance Levels diff --git a/packages/opencode/.opencode/commands/pr/review.md b/packages/opencode/.opencode/commands/pr/review.md index ab9a4f6..34089f3 100644 --- a/packages/opencode/.opencode/commands/pr/review.md +++ b/packages/opencode/.opencode/commands/pr/review.md @@ -54,20 +54,24 @@ Call `kompass_changes_load` with `base: `, `head: `, ``, and `` -3. Derive `` from ``: +1. Check ``, ``, and `` +2. Derive `` from ``: - Treat resolved threads as settled - - Treat threads as settled when they already contain feedback from `` and a later reply from another participant makes it clear the suggestion was intentionally declined, deferred, or answered without a code change request - - Only revive a settled thread when the new diff adds concrete evidence that the underlying concern is still a material bug, security issue, or broken contract -4. Prefer inline comments for file-specific findings; use the review body only for high-level summaries -5. Use diff hunks in `` to map inline comments to the correct lines -6. Do NOT duplicate findings already raised or settled + - Treat threads as settled when they already contain feedback from `` and a later reply makes it clear the concern was intentionally declined, deferred, or answered without a code change request + - Treat threads as settled when the author's reply directly answers the concern and the current diff does not add a materially different failure mode +3. Derive `` from `` authored by `` +4. Use diff hunks in `` to map inline comments to the correct lines +5. Derive `` as findings that are: + - new in this diff + - from a previously unreviewed changed area + - clearly missed material defects with a concrete failure mode + Exclude anything already covered by `` or `` on the same effective diff. + -Derive `` from prior reviews. Derive `` from existing approvals on ``. -Before publishing, derive: ``, ``, ``, and ``. + +Before publishing, derive: ``, ``, ``, and whether each proposed finding is included in ``. **Grading and Publishing Rules:** 1. Assign a grade based on code quality (1-5 stars) @@ -98,7 +102,8 @@ For multi-line: add `startLine`. For deleted lines: use `side: "LEFT"`. - Call `kompass_pr_sync` with: - `refUrl: ` - `review.body`: the grade line first (for example `★★★☆☆`), followed by any non-inline notes - - `review.comments`: inline comments (changed lines only) - **skip lines or concerns already covered by open or settled threads in `` unless the new diff introduces a materially different failure mode** + - `review.comments`: inline comments (changed lines only) - **skip lines or concerns already covered by open threads in `` unless the new diff introduces a materially different failure mode** + - Include only findings from `` - Never omit the grade from `review.body` in this branch - Do not pass any other fields diff --git a/packages/opencode/.opencode/commands/review.md b/packages/opencode/.opencode/commands/review.md index 9407077..812e49c 100644 --- a/packages/opencode/.opencode/commands/review.md +++ b/packages/opencode/.opencode/commands/review.md @@ -47,11 +47,8 @@ If `.comparison` is not "uncommitted": ### Review Changes Following the reviewer agent guidance: -1. Read each changed file for full context in the current session before drafting findings -2. Analyze for bugs, security issues, and correctness problems -3. Formulate findings ordered by impact -4. Store the overall rating as ``, the top-line conclusion as ``, and the severity counts as ``, ``, ``, and `` -5. Store the total number of findings as `` +1. Store the overall rating as ``, the top-line conclusion as ``, and the severity counts as ``, ``, ``, and `` +2. Store the total number of findings as `` While reading files: - Load any relevant nested `AGENTS.md` in the current session before applying review criteria