diff --git a/internal/scaffold/fullsend-repo/skills/pr-review/SKILL.md b/internal/scaffold/fullsend-repo/skills/pr-review/SKILL.md index a0ecf414b..4cb199040 100644 --- a/internal/scaffold/fullsend-repo/skills/pr-review/SKILL.md +++ b/internal/scaffold/fullsend-repo/skills/pr-review/SKILL.md @@ -181,6 +181,29 @@ rewrite), or if `total_commits` exceeds 250 (the compare API silently truncates file lists at 300 files), treat all files as changed — no anchoring for this run. +### 2b. Human review comments + +Fetch human review comments from the PR to provide sub-agents with +context about human-authorized scope changes. Human reviewers may +request changes that deviate from the linked issue's original +specification — sub-agents need visibility into these requests to +avoid flagging human-directed changes as unauthorized scope creep. + +```bash +# Fetch all review comments (not inline diff comments) +PR_REVIEWS=$(gh api "repos/${REPO_FULL_NAME}/pulls/${PR_NUMBER}/reviews" \ + --jq '[.[] | select(.user.type != "Bot") | {author: .user.login, state: .state, body: .body}]') +``` + +Filter to **human-authored reviews only** (exclude bot reviews by +checking `.user.type != "Bot"`). Include the review state (`APPROVED`, +`CHANGES_REQUESTED`, `COMMENTED`) so sub-agents can distinguish +between casual comments and explicit change requests. + +If no human reviews exist, set `human_review_comments` to an empty +list. This is normal for first-review PRs or PRs that have only +received bot reviews. + ### 3. Triage Classify the change and prepare context packages for sub-agents. This @@ -303,6 +326,10 @@ For each selected sub-agent, assemble a context package containing: - `pr_metadata`: title, body, author, labels - `issue_context`: linked issue title, body, comments (for `intent-coherence`) +- `human_review_comments`: human-authored review comments from prior + PR review cycles (from 2b), for `intent-coherence`. These provide + context about human-authorized scope amendments that may deviate + from the linked issue's original specification. - `cross_repo_context`: findings from 3a for `cross-repo-contracts` ### 4. Dispatch sub-agents @@ -349,6 +376,9 @@ For each selected sub-agent: ### Issue context + + ### Human review comments + ``` **Part 5 — Dispatch guard flag:** diff --git a/internal/scaffold/fullsend-repo/skills/pr-review/sub-agents/intent-coherence.md b/internal/scaffold/fullsend-repo/skills/pr-review/sub-agents/intent-coherence.md index 1e8f789d2..6905bd8c4 100644 --- a/internal/scaffold/fullsend-repo/skills/pr-review/sub-agents/intent-coherence.md +++ b/internal/scaffold/fullsend-repo/skills/pr-review/sub-agents/intent-coherence.md @@ -42,6 +42,48 @@ Calibrate investigation to the diff size and nature. scope. If there is no linked issue, flag a `missing-authorization` finding — non-trivial changes require explicit authorization. +## Human-authorized scope amendments + +When the context package includes human review comments, check whether +a human reviewer has explicitly requested changes that deviate from +the linked issue's original specification. Human reviewers have the +authority to amend the scope of work — their review comments function +as addenda to the issue's authorization. + +**Identifying human-authorized deviations:** + +A deviation is human-authorized when a human reviewer (not a bot) has +explicitly requested it in a review comment with state +`CHANGES_REQUESTED` or `COMMENTED`. Look for: + +- Direct instructions to rename, restructure, or change approach + (e.g., "rename this to X", "use Y instead of Z", "change the + category from A to B") +- Explicit approval of a deviation the PR author proposed +- Requests that expand or narrow the scope beyond the issue's + original specification + +**How to handle human-authorized deviations:** + +- **Do not raise medium+ findings** for deviations that a human + reviewer explicitly requested. Flagging human-directed changes as + unauthorized scope creep is a false positive. +- **Report as info-level** with category `scope-exceeded` so the + deviation is visible and the issue can be updated to reflect the + amended scope. The description should note both the deviation from + the issue and the human review comment that authorized it. +- If the PR includes changes **beyond** what the human authorized, + flag only the unauthorized portion at the appropriate severity. + +**Ambiguous cases:** + +- If the human comment is vague or does not clearly authorize the + specific deviation (e.g., "looks good" without addressing the + change), treat the deviation as unauthorized and flag at the + normal severity. +- If multiple human reviewers give conflicting feedback about the + same change, flag for human resolution at medium severity. + ## Revert PR authorization A PR is a candidate revert if **at least two** of the following signals