Skip to content

docs(pr-review): tighten weak language and add trigger phrase - #753

Open
ralphbean wants to merge 4 commits into
mainfrom
skillsaw/fix-pr-review
Open

docs(pr-review): tighten weak language and add trigger phrase#753
ralphbean wants to merge 4 commits into
mainfrom
skillsaw/fix-pr-review

Conversation

@ralphbean

Copy link
Copy Markdown
Member

Ran skillsaw (evaluating it per #188) against the repo's skills.
Adds a "Use when..." trigger phrase to the description, replaces
three "note that" hedges with direct "state"/"must state" instructions,
converts two bare file paths into markdown links, and makes the
action-hints footer condition explicit (the post-review pipeline only
appends it when the outcome is request-changes).

Related to #188

Assisted-by: Claude Opus 4.6 noreply@anthropic.com
Signed-off-by: Ralph Bean rbean@redhat.com


Stack created with GitHub Stacks CLIGive Feedback 💬

@ralphbean
ralphbean requested a review from a team as a code owner August 11, 2026 16:59
@qodo-code-review

Copy link
Copy Markdown

PR Summary by Qodo

PR review skill docs: add trigger phrase and tighten verification/footers language

📝 Documentation 🕐 10-20 Minutes

Grey Divider

AI Description

• Add a clear “Use when…” trigger phrase to the PR Review skill description.
• Replace hedging language with explicit “state/must state” instructions for unverifiable files.
• Improve readability with markdown links and clarify when action-hints footer is appended.
Diagram

graph TD
  D["skills/pr-review/SKILL.md"] --> O(["PR review orchestrator"])
  R(["Reviewer"]) --> O --> C["Structured review comment"]
  O --> S["Sub-agents"]
  O --> P(["Post-review pipeline"]) --> C
Loading
High-Level Assessment

The approach (tightening normative language and clarifying conditions inline) is the most effective and lowest-risk way to reduce ambiguity in an instruction/spec document; alternatives like adding separate “glossary/terminology” sections would add indirection without improving compliance.

Files changed (1) +8 / -7

Documentation (1) +8 / -7
SKILL.mdClarify usage trigger, strengthen unverifiable-file language, and improve link/footers text +8/-7

Clarify usage trigger, strengthen unverifiable-file language, and improve link/footers text

• Adds a “Use when…” trigger phrase to the skill description. Replaces several “note that” hedges with explicit instructions to state when PR-head verification is not possible, including protected-path guidance. Converts referenced file paths to markdown links and clarifies that action hints are appended only for 'request-changes'.

skills/pr-review/SKILL.md

@fullsend-ai-review

fullsend-ai-review Bot commented Aug 11, 2026

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 5:01 PM UTC · Completed 5:14 PM UTC

Commit: e82599f · View workflow run →

@qodo-code-review

qodo-code-review Bot commented Aug 11, 2026

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (1)

Grey Divider


Action required

1. Protected skills/ file modified 📜 Skill insight § Compliance
Description
This PR modifies a protected governance/infrastructure path under skills/, so it must not be
auto-approved and requires human review. Failing to treat protected-path changes as requiring human
approval increases governance and security risk.
Code

skills/pr-review/SKILL.md[R8-9]

+  file. Use when reviewing a pull request end-to-end and producing a
+  structured review result.
Relevance

●●● Strong

Repo actively enforces protected-path governance; surfacing skills/ changes for human review matches
accepted protected-path hardening.

PR-#569

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The compliance checklist defines skills/ as a protected governance/infrastructure path that must
not be auto-approved and must be surfaced as a finding when modified. The diff shows
skills/pr-review/SKILL.md was changed, which falls under the protected skills/ directory.

skills/pr-review/SKILL.md[1-12]
Skill: pr-review

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
This PR changes a file under a protected path (`skills/`), which must always trigger a human approval requirement and must not be auto-approved.

## Issue Context
Protected governance/infrastructure paths require explicit human review per the compliance checklist.

## Fix Focus Areas
- skills/pr-review/SKILL.md[1-12]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools



Informational

2. Quoted markdown link ✓ Resolved 🐞 Bug ⚙ Maintainability
Description
The docs-currency instruction wraps a valid markdown link in literal double quotes, so the rendered
text includes unnecessary punctuation and is inconsistent with other links in the same document.
Code

skills/pr-review/SKILL.md[R694-695]

+   "docs-currency", read "[../docs-review/SKILL.md](../docs-review/SKILL.md)" and include its
   contents verbatim
Relevance

●●● Strong

Trivial documentation formatting nit; similar pr-review doc-style consistency tweaks have been
accepted before.

PR-#172

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The docs-review link is currently wrapped in literal quotes, while other links in the same document
(e.g., the security-triage link) are not, indicating an introduced inconsistency in markdown style.

skills/pr-review/SKILL.md[690-695]
skills/pr-review/SKILL.md[438-439]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
In `skills/pr-review/SKILL.md`, the docs-review skill path was converted to a markdown link but is wrapped in literal double quotes (e.g., `"[...](...)"`). Markdown still renders the link, but the quotes show up as visible punctuation and are inconsistent with other link formatting in the file.

### Issue Context
Elsewhere in the same document, links are formatted without surrounding quotes (and often with backticked link text).

### Fix Focus Areas
- skills/pr-review/SKILL.md[693-695]

### Suggested change
Replace:

`read "[../docs-review/SKILL.md](../docs-review/SKILL.md)"`

With something consistent like:

`read [`../docs-review/SKILL.md`](../docs-review/SKILL.md)`

(or at minimum remove the surrounding `"` characters).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


Grey Divider

Context
✅ Compliance rules (platform): 55 rules
✅ Skills: 4 invoked
  code-review
  code-implementation
  pr-review
  docs-review

Grey Divider

Tip of the day
💡 Did you know, you can describe a rule in plain language on the Rules page and Qodo drafts it for you

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

Comment thread skills/pr-review/SKILL.md Outdated
Comment thread skills/pr-review/SKILL.md Outdated
@fullsend-ai-review

fullsend-ai-review Bot commented Aug 11, 2026

Copy link
Copy Markdown

Review

Findings

Medium

  • [protected-path] skills/pr-review/SKILL.md — This PR modifies skills/pr-review/SKILL.md, a file under the protected skills/ path. The PR links to issue Evaluate skillsaw for linting agent instructions #188 and explains the rationale (applying skillsaw linting findings). Human approval is always required for protected-path changes, regardless of context.
Previous run

Review

Findings

Medium

  • [protected-path] skills/pr-review/SKILL.md — This PR modifies skills/pr-review/SKILL.md, a file under the protected skills/ path. The PR links to issue Evaluate skillsaw for linting agent instructions #188 and explains the rationale (applying skillsaw linting findings). Human approval is always required for protected-path changes, regardless of context.
Previous run (2)

Review

Findings

Medium

  • [protected-path] skills/pr-review/SKILL.md — This PR modifies skills/pr-review/SKILL.md, a file under the protected skills/ path. The PR links to issue Evaluate skillsaw for linting agent instructions #188 and explains the rationale (applying skillsaw linting findings). Human approval is always required for protected-path changes, regardless of context.
Previous run (3)

Review

Findings

Medium

  • [protected-path] skills/pr-review/SKILL.md — This PR modifies skills/pr-review/SKILL.md, a file under the protected skills/ path. The PR links to issue Evaluate skillsaw for linting agent instructions #188 and explains the rationale (applying skillsaw linting findings). Human approval is always required for protected-path changes, regardless of context.
Previous run (4)

Review

Findings

Medium

  • [protected-path] skills/pr-review/SKILL.md — This PR modifies a file under the protected skills/ path. The PR links to issue Evaluate skillsaw for linting agent instructions #188 and explains the rationale (applying skillsaw linting findings). Human approval is always required for protected-path changes, regardless of context.
Previous run (5)

Review

Findings

Medium

  • [protected-path] skills/pr-review/SKILL.md — This PR modifies a file under the protected skills/ path. The PR links to issue Evaluate skillsaw for linting agent instructions #188 and explains the rationale (applying skillsaw linting findings). Human approval is always required for protected-path changes, regardless of context.
Previous run (6)

Review

Findings

Medium

  • [protected-path] skills/pr-review/SKILL.md — This PR modifies a file under the protected skills/ path. The PR links to issue Evaluate skillsaw for linting agent instructions #188 and explains the rationale (applying skillsaw linting findings). Human approval is always required for protected-path changes, regardless of context.

Low

  • [internal-consistency] skills/pr-review/SKILL.md:694 — The docs-review file path was converted to a markdown link inside double quotes, producing read "[../docs-review/SKILL.md](../docs-review/SKILL.md)". This is inconsistent with how the security-triage link was done at line 438 (Read sub-agents/security-triage.md), where the markdown link uses backtick-wrapped display text with no surrounding double quotes.
    Remediation: Match the security-triage pattern — remove the wrapping double quotes and use backtick-quoted text for the display portion.
Previous run (7)

Review

Findings

Medium

  • [protected-path] skills/pr-review/SKILL.md — This PR modifies a file under the protected skills/ path. The PR links to issue Evaluate skillsaw for linting agent instructions #188 and explains the rationale (applying skillsaw linting findings). Human approval is always required for protected-path changes, regardless of context.

Low

  • [internal-consistency] skills/pr-review/SKILL.md:694 — The docs-review file path was converted to a markdown link inside double quotes, producing read "[../docs-review/SKILL.md](../docs-review/SKILL.md)". This is inconsistent with how the security-triage link was done at line 438 (Read sub-agents/security-triage.md), where the markdown link uses backtick-wrapped display text with no surrounding double quotes.
    Remediation: Match the security-triage pattern — remove the wrapping double quotes and use backtick-quoted text for the display portion.
Previous run (8)

Review

Findings

Medium

  • [protected-path] skills/pr-review/SKILL.md — This PR modifies a file under the protected skills/ path. The PR links to issue Evaluate skillsaw for linting agent instructions #188 and explains the rationale (applying skillsaw linting findings). Human approval is always required for protected-path changes, regardless of context.

Low

  • [internal-consistency] skills/pr-review/SKILL.md:693 — The docs-review file path was converted to a markdown link inside double quotes, producing read "[../docs-review/SKILL.md](../docs-review/SKILL.md)". This is inconsistent with how the security-triage link was done at line 437 (Read [`sub-agents/security-triage.md`](sub-agents/security-triage.md)), where the markdown link uses backtick-wrapped display text with no surrounding double quotes.
    Remediation: Match the security-triage pattern — remove the wrapping double quotes and use backtick-quoted text for the display portion.

Labels: PR modifies the pr-review skill definition (skills/pr-review/SKILL.md), a documentation-only change to the review agent orchestrator skill

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review fullsend-ai-review Bot added requires-manual-review Review requires human judgment documentation Improvements or additions to documentation review-agent labels Aug 11, 2026

@waynesun09 waynesun09 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MEDIUM: Parallel 'Insufficient context' bullet still hedges with "note that" instead of "state that"

File: skills/pr-review/SKILL.md (line ~1039, outside this PR's diff hunks, so not addressable as an inline comment)

The PR converts exactly three "note that" -> "state that" instances (the omitted-files line, the PR-head-verification line, and the case-2 "Sufficient context" protected-path bullet), but leaves the structurally identical case-1 "Insufficient context" bullet two lines above untouched. It still reads:

The description MUST list the affected protected files and note that the PR lacks justification for modifying governance or infrastructure files.

while the case-2 sibling now reads "...and state that human approval is always required...". Both bullets share the same "MUST list ... and {note|state} that ..." template for the two branches of the protected-path check, so leaving one on the old hedge word reintroduces the exact weak-language inconsistency this PR is meant to eliminate.

Suggestion: Change the case-1 bullet's "...and note that the PR lacks justification..." to "...and state that the PR lacks justification..." to match the sibling bullet.

Comment thread skills/pr-review/SKILL.md Outdated
@ralphbean

Copy link
Copy Markdown
Member Author

/fs-fix address @waynesun09's findings.

@fullsend-ai-coder

fullsend-ai-coder Bot commented Aug 12, 2026

Copy link
Copy Markdown
Contributor

🤖 Finished Fix · ✅ Success · Started 8:44 PM UTC · Completed 8:49 PM UTC

Commit: e82599f · View workflow run →

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

🔧 Fix agent — iteration 1 (human-triggered)

Addressed waynesun09's finding: replaced the remaining 'note that' hedge in the protected-path Insufficient context bullet with 'state that' to match its sibling bullet. One pre-existing test failure (prerequisites-creates-allowed-issue) is unrelated to this change.

Fixed (1):

  1. Insufficient context bullet still hedges with 'note that' instead of 'state that': Changed 'and note' to 'and state' on the case-1 Insufficient context bullet (line 1039) to match the sibling Sufficient context bullet, closing the weak-language inconsistency.

Tests: passed

Next steps:

  • /fs-review — request a re-review of the changes
  • /fs-fix <your instruction> — run another fix pass with specific guidance
  • Push commits directly — review re-runs automatically on push
    Updated by fullsend fix agent

fullsend-ai-coder Bot added a commit that referenced this pull request Aug 12, 2026
Change the 'Insufficient context' bullet's 'and note that' to 'and
state that' to match the sibling 'Sufficient context' bullet, closing
the weak-language inconsistency flagged by @waynesun09.

Addresses review feedback on #753
@fullsend-ai-review

fullsend-ai-review Bot commented Aug 12, 2026

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 8:50 PM UTC · Completed 9:02 PM UTC

Commit: bc717f2 · View workflow run →

fullsend-ai-review[bot]

This comment was marked as outdated.

@ralphbean
ralphbean force-pushed the skillsaw/fix-pr-review branch from bc717f2 to 2d76cd1 Compare August 13, 2026 21:38
@fullsend-ai-review

fullsend-ai-review Bot commented Aug 13, 2026

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 9:39 PM UTC · Completed 9:53 PM UTC

Commit: 2d76cd1 · View workflow run →

fullsend-ai-review[bot]

This comment was marked as outdated.

@waynesun09 waynesun09 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed via 4-agent squad (claude-coder, claude-researcher, grok-review-agent, cursor-code-review) + verification pass at head 2d76cd1 — no CRITICAL/HIGH/MEDIUM findings survived verification.

@ralphbean

Copy link
Copy Markdown
Member Author

/fs-fix fix the "New trigger phrase appended" problem.

@fullsend-ai-coder

fullsend-ai-coder Bot commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

🤖 Finished Fix · ✅ Success · Started 10:40 PM UTC · Completed 10:49 PM UTC

Commit: 2d76cd1 · View workflow run →

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

🔧 Fix agent — iteration 2 (human-triggered)

Addressed 2 findings: (1) rewrote the redundant trigger phrase that repeated 'structured review result' from the preceding description sentence, and (2) fixed the docs-review link formatting to match the security-triage link pattern. Pre-existing test failures in post-retro-test.sh (10 tests) are unrelated to this change.

Fixed (2):

  1. Redundant trigger phrase repeats 'structured review result' (skills/pr-review/SKILL.md): Rewrote the trigger phrase from 'Use when reviewing a pull request end-to-end and producing a structured review result.' (which redundantly repeated 'structured review result' from the preceding sentence) to 'Use when a pull request needs end-to-end review encompassing triage, code quality, security, and documentation.' — non-redundant and descriptive of the skill's review dimensions.
  2. Docs-review link wrapped in double quotes inconsistent with security-triage link (skills/pr-review/SKILL.md): Removed double quotes around the docs-review markdown link and switched to backtick-wrapped display text to match the security-triage link pattern at line 438, addressing the review agent's standing internal-consistency finding.

Tests: passed

Next steps:

  • /fs-review — request a re-review of the changes
  • /fs-fix <your instruction> — run another fix pass with specific guidance
  • Push commits directly — review re-runs automatically on push
    Updated by fullsend fix agent

fullsend-ai-coder Bot added a commit that referenced this pull request Aug 13, 2026
Rewrites the "Use when" trigger phrase to avoid repeating "structured
review result" from the preceding sentence. Also removes double quotes
around the docs-review markdown link to match the security-triage link
pattern at line 438.

Addresses review feedback on #753
@fullsend-ai-review

fullsend-ai-review Bot commented Aug 13, 2026

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 10:50 PM UTC · Completed 11:01 PM UTC

Commit: 02825fa · View workflow run →

@ralphbean

Copy link
Copy Markdown
Member Author

/fs-fix move the "use when" trigger language to the beginning of the description

@fullsend-ai-coder

fullsend-ai-coder Bot commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

🤖 Finished Fix · ✅ Success · Started 11:25 PM UTC · Completed 11:29 PM UTC

Commit: 02825fa · View workflow run →

fullsend-ai-coder Bot added a commit that referenced this pull request Aug 13, 2026
Moves the "Use when" trigger sentence from the end of the YAML
frontmatter description to the beginning, per human instruction.

Addresses review feedback on #753
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

🔧 Fix agent — iteration 3 (human-triggered)

Moved the trigger phrase to the beginning of the description as instructed. The 'Use when...' sentence was at the end of the YAML frontmatter description and is now the first sentence.

Fixed (1):

  1. move the 'use when' trigger language to the beginning of the description (skills/pr-review/SKILL.md): Moved the 'Use when a pull request needs end-to-end review encompassing triage, code quality, security, and documentation.' sentence from the end of the YAML frontmatter description to the beginning.

Tests: passed

Next steps:

  • /fs-review — request a re-review of the changes
  • /fs-fix <your instruction> — run another fix pass with specific guidance
  • Push commits directly — review re-runs automatically on push
    Updated by fullsend fix agent

@fullsend-ai-review

fullsend-ai-review Bot commented Aug 13, 2026

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 11:31 PM UTC · Completed 11:45 PM UTC

Commit: 40664c3 · View workflow run →

@ralphbean
ralphbean force-pushed the skillsaw/fix-pr-review branch from 40664c3 to 43bc250 Compare August 14, 2026 15:37
@fullsend-ai-review

fullsend-ai-review Bot commented Aug 14, 2026

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 3:38 PM UTC · Completed 3:52 PM UTC

Commit: 43bc250 · View workflow run →

@ralphbean
ralphbean force-pushed the skillsaw/fix-pr-review branch from 43bc250 to bb51782 Compare August 14, 2026 16:09
@fullsend-ai-review

fullsend-ai-review Bot commented Aug 14, 2026

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 4:11 PM UTC · Completed 4:23 PM UTC

Commit: bb51782 · View workflow run →

ralphbean pushed a commit that referenced this pull request Aug 14, 2026
Change the 'Insufficient context' bullet's 'and note that' to 'and
state that' to match the sibling 'Sufficient context' bullet, closing
the weak-language inconsistency flagged by @waynesun09.

Addresses review feedback on #753
ralphbean pushed a commit that referenced this pull request Aug 14, 2026
Rewrites the "Use when" trigger phrase to avoid repeating "structured
review result" from the preceding sentence. Also removes double quotes
around the docs-review markdown link to match the security-triage link
pattern at line 438.

Addresses review feedback on #753
ralphbean pushed a commit that referenced this pull request Aug 14, 2026
Moves the "Use when" trigger sentence from the end of the YAML
frontmatter description to the beginning, per human instruction.

Addresses review feedback on #753
@ralphbean
ralphbean force-pushed the skillsaw/fix-pr-review branch from bb51782 to 8263546 Compare August 14, 2026 18:41
@fullsend-ai-review

fullsend-ai-review Bot commented Aug 14, 2026

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 6:42 PM UTC · Completed 6:52 PM UTC

Commit: 8263546 · View workflow run →

Base automatically changed from skillsaw/fix-issue-labels to main August 14, 2026 18:54
ralphbean and others added 4 commits August 14, 2026 14:54
Ran skillsaw (evaluating it per #188) against the repo's skills.
Adds a "Use when..." trigger phrase to the description, replaces
three "note that" hedges with direct "state"/"must state" instructions,
converts two bare file paths into markdown links, and makes the
action-hints footer condition explicit (the post-review pipeline only
appends it when the outcome is `request-changes`).

Related to #188

Assisted-by: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Ralph Bean <rbean@redhat.com>
Change the 'Insufficient context' bullet's 'and note that' to 'and
state that' to match the sibling 'Sufficient context' bullet, closing
the weak-language inconsistency flagged by @waynesun09.

Addresses review feedback on #753
Rewrites the "Use when" trigger phrase to avoid repeating "structured
review result" from the preceding sentence. Also removes double quotes
around the docs-review markdown link to match the security-triage link
pattern at line 438.

Addresses review feedback on #753
Moves the "Use when" trigger sentence from the end of the YAML
frontmatter description to the beginning, per human instruction.

Addresses review feedback on #753
@ralphbean
ralphbean force-pushed the skillsaw/fix-pr-review branch from 8263546 to a994da0 Compare August 14, 2026 18:55
@fullsend-ai-review

fullsend-ai-review Bot commented Aug 14, 2026

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 6:56 PM UTC · Completed 7:06 PM UTC

Commit: a994da0 · View workflow run →

@waynesun09 waynesun09 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review-only sweep: 2 findings below.

Comment thread skills/pr-review/SKILL.md
- **No footer.** Do not append any footer, action-hints block, or
boilerplate after findings. The post-review pipeline appends
action hints deterministically when appropriate.
action hints deterministically when the outcome is `request-changes`.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MEDIUM: Action-hints footer condition is precise for request-changes but silently omits reject, which also becomes a GitHub REQUEST_CHANGES review

The new wording states: "The post-review pipeline appends action hints deterministically when the outcome is request-changes." Verified against scripts/post-review.sh at PR head (a994da05): the ACTION_HINTS_FOOTER block is gated by the literal bash check if [ "${ACTION}" = "request-changes" ] (line 384), so the statement is technically accurate for that one internal action value. However, the schema documented a few dozen lines below in this same file (the outcome/action table) lists reject as a distinct, valid action with its own required fields, and fullsend/internal/cli/postreview.go maps both request-changes and reject to the same GitHub review event REQUEST_CHANGES (lines 183-188). So a PR reviewed with action=reject is posted to GitHub identically to a request-changes review, but per post-review.sh it will NOT receive the "Next steps" action-hints footer, since the script only checks for the literal string request-changes. The new, more "precise" sentence therefore creates a documentation gap: a reader could reasonably assume any REQUEST_CHANGES-style outcome (including reject) gets the footer, when only the literal request-changes action does. This doesn't currently cause an agent to violate the (unconditional) "No footer" rule, since that rule already applies regardless of outcome, but it is a real, verifiable inaccuracy/incompleteness introduced by this PR's tightening pass.

Suggestion: Either broaden the condition to reflect both cases if that's the intent (and file a companion fix in post-review.sh to also cover reject), or make the sentence non-exclusive/accurate as-is, e.g.: "the post-review pipeline appends action hints deterministically for the request-changes action (not for reject, approve, or comment)."

Comment thread skills/pr-review/SKILL.md
For omitted changed files in large PRs, sub-agents should treat those
files as unavailable for PR-head verification. Any findings about
omitted files should note that the file contents could not be verified
omitted files must state that the file contents could not be verified

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MEDIUM: Omitted-file instruction strength diverges between orchestrator body ("must state") and spawn-prompt template ("state") sent verbatim to sub-agents

Verified at PR head (a994da05): line 203, in the orchestrator-facing guidance (step 3), now reads "...omitted files must state that the file contents could not be verified against the PR head." Line 727, inside the literal "Context package" spawn-prompt template that is assembled and sent verbatim to each dispatched sub-agent (Part 4, under "### 4. Dispatch sub-agents"), reads "...state that the file contents could not be verified against the PR head" — without the "must". Since sub-agents only ever receive the copy at line 727 (they never see the orchestrator-body text at line 203), the RFC-2119-style MUST strength this PR intentionally added to the orchestrator's own description of the requirement is not carried through to the actual instruction text the sub-agents act on.

Suggestion: Change line 727's spawn-prompt template text to "must state that the file contents could not be verified against the PR head" to match line 203's strength, or document why the two are deliberately different (e.g. because the orchestrator body is a summary and 203's MUST is meant only as a paraphrase, not a literal instruction).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation fullsend-fix requires-manual-review Review requires human judgment review-agent

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants