Skip to content

Add opt-in change narrative and focus areas to review-pull-request template#257

Merged
abeltrano merged 3 commits into
mainfrom
add-executive-summary-to-pr-review
May 12, 2026
Merged

Add opt-in change narrative and focus areas to review-pull-request template#257
abeltrano merged 3 commits into
mainfrom
add-executive-summary-to-pr-review

Conversation

@abeltrano
Copy link
Copy Markdown
Collaborator

@abeltrano abeltrano commented May 12, 2026

Summary

Adds an opt-in change_narrative parameter to the review-pull-request
template. When triggered, the template produces:

  1. A holistic, grounded change narrative of what the PR is actually
    doing — what changes functionally, how it changes things
    architecturally, why per the author's stated motivation, and what
    scope boundaries exist.
  2. A short suggested focus areas list naming the specific files or
    regions that warrant the closest reviewer scrutiny — each anchored to
    an observable impact signal or concentration of complexity in the
    diff.

Motivation

This came up during a very large code review that was going to take a
long time to perform. A reviewer facing a broad-scope, large-diff PR
needs two things before drilling in:

  • A grounded overview so the reviewer's interpretation of the change
    is verifiably tied to the diff itself, not just the author's
    description.
  • A prioritization signal so finite review attention lands on the
    parts of the diff most likely to harbor risk.

The narrative addresses the first; the focus areas address the second.

Design

  • New parameter: change_narrative: 'auto' (default) | 'always' | 'never'
  • In auto, the template inspects size, breadth, impact, and
    description-gap signals and produces the narrative when any trigger
    fires (with a skip clause if the existing PR description already
    gives a clear, accurate overview).
  • Suggested focus areas are produced only when the narrative is
    produced AND at least one impact signal fired or concentration of
    complexity is observable. If neither holds, the focus-areas element
    is omitted rather than fabricated. Focus areas are advisory only —
    every changed file remains subject to Phase 2 analysis.
  • Output surfacing:
    • Document mode: narrative + focus areas appear at the head of
      the report's Problem Statement section, followed by author
      motivation. When narrative or focus areas are produced, the
      report uses the full investigation-report format so Problem
      Statement is guaranteed present.
    • Action mode: narrative + focus areas (when produced) are
      presented to the reviewer in step 1, before walking through
      individual findings.
  • Narrative and focus areas are never auto-posted to the GitHub
    review body — reviewer feedback should focus on verdict and findings,
    not on re-summarizing what the author already wrote.
  • A normalization clause maps blank/invalid change_narrative values
    to auto so the feature works correctly when the template is
    packaged as a Copilot prompt file or agentic workflow.

Additive with respect to existing flows

  • Phase 1 Steps 1–4 and Phases 2, 3, 4 are byte-for-byte unchanged.
  • Phase 2's per-file coverage requirement is unchanged; focus areas
    advise reviewer attention only and never reduce coverage.
  • Action-mode user-confirmation contract is unchanged. The only added
    action-mode rules are (a) explicit Step 1 instruction to surface
    the narrative/focus areas before walking findings, and (b) a Step 3
    body-construction guardrail preventing them from being posted to
    GitHub.
  • Quality Checklist additions are strictly conditional on the
    narrative or focus areas being produced.
  • Non-Goal additions are explicitly scoped to the narrative and
    suggested focus areas.
  • manifest.yaml, bootstrap.md, and all other components are
    unchanged.

The default mode is auto, which produces new content for PRs that
trip the size / breadth / impact / description-gap triggers. Users who
want strict pre-existing behavior can set change_narrative: never.

Validation

  • python tests/validate-manifest.py passes.

Adds a new `executive_summary` parameter to the `review-pull-request`
template (`auto` default, plus `always` and `never`). When triggered,
the template produces a holistic change narrative and a short
suggested-focus-areas list to help a reviewer orient themselves on
broad-scope or large-diff PRs and decide where to concentrate
attention.

The narrative and focus areas are surfaced via the report's Problem
Statement section in document mode and presented to the reviewer
before findings walk-through in action mode. They are never auto-posted
to the GitHub review body. Phase 2 per-file coverage is preserved;
focus areas advise reviewer attention only and never reduce coverage.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@abeltrano abeltrano requested a review from Copilot May 12, 2026 18:57
@abeltrano abeltrano marked this pull request as ready for review May 12, 2026 18:57
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

Adds an opt-in “change narrative + suggested focus areas” capability to the review-pull-request template, helping reviewers quickly ground themselves in what a broad/large PR actually does and where to prioritize scrutiny—without reducing Phase 2 per-file coverage.

Changes:

  • Introduces an executive_summary parameter with auto|always|never behavior plus normalization for blank/invalid values.
  • Adds Phase 1 logic to conditionally generate a grounded change narrative and optional suggested focus areas based on size/breadth/impact/description-gap signals.
  • Updates document/action-mode instructions to surface the narrative/focus areas appropriately and explicitly prevent auto-posting them into the GitHub review body.

Comment thread templates/review-pull-request.md Outdated
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

Comment thread templates/review-pull-request.md Outdated
Addresses PR review feedback on #257: the original `executive_summary`
name conflicted with the report's hard-spec'd "Executive Summary"
section meaning. The behavior actually controls a change narrative
(plus optional focus areas) surfaced in `Problem Statement`, so the
new name reflects intent.

Pure rename — no behavioral changes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@abeltrano abeltrano changed the title Add opt-in executive summary and focus areas to review-pull-request template Add opt-in change narrative and focus areas to review-pull-request template May 12, 2026
@abeltrano abeltrano merged commit e3fe288 into main May 12, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants