/prepare-implementation-review-comments

name: Prepare implementation review comments on a pull request
description: Post reviewer-facing evidence on a pull request - reading order, requirement traceability, risks, discussion points, screenshots, API calls, BDD results and unit coverage.
user-invocable: false

Prepare implementation review comments on a pull request

Overview

Helps reviewers by posting, as one review on each pull request:

• inline comments on the lines they concern: risks, discussion points, screenshots, accessibility violations, API calls, failed BDD scenarios and coverage gaps
• a summary of what belongs to no single line: TL;DR, reading order, requirement traceability, BDD results and coverage

Instructions

Phase 1: Find the code host

• Work out the host from each PR URL given, else from `git remote get-url origin` (e.g. GitHub, Azure DevOps, GitLab).
• For each operation below, use the host's MCP server tools if the project has one, else the host's CLI (e.g. `gh`, `az repos`, `glab`), else its REST API through `curl` with a token from the environment. If none works, tell the developer what to install or log into (`/mcp` to check status) and stop — never guess.
• Operations:
• Read the PR: number, author, URL, changed files, head commit and diff.
• List the PR's existing comments, to find ones carrying a `<!-- story-flow:prepare-implementation-review... -->` marker.
• Post a review: a summary body with inline comments, each on a file and a line on the new side of the diff. Where the host has no single review, post the summary and each inline comment separately (e.g. Azure DevOps threads, GitLab discussions).
• Post a file-level comment, where the host supports one (e.g. GitHub `subject_type: file`).
• Edit a comment.
• Reply to a comment's thread.
• Resolve a thread (e.g. GitHub `resolveReviewThread` through GraphQL, Azure DevOps thread status `fixed`, GitLab `resolved=true`).
• Link to a file and line in the PR.
• Host an image for a comment. Use the host's upload where it has one (e.g. Azure DevOps PR attachments, GitLab project uploads). Otherwise (e.g. GitHub), commit it to a `pr-evidence` orphan branch through a temporary `git worktree`, so the developer's checkout is untouched, push, and link the raw file at that commit.

Phase 2: Gather

• Resolve the PRs: each given URL (ignoring trailing segments such as `/changes` or `/files`) or ID, else the PR whose source branch is the current branch. Several PRs are one story split across repositories; prepare them together.
• For a URL in another repository, find its local clone: a sibling of the current repository whose `git remote get-url origin` matches it. If there is none, ask the developer for its path. Run everything for that PR in its clone.
• Read each PR. If `git rev-parse HEAD` in its clone isn't its head commit, ask the developer to check it out (e.g. `git checkout <head commit>` for a merged PR whose branch is gone) and stop — never switch branches or stash on their behalf.
• Find the story markdown and `.feature` files among the changed files of all the PRs, or use the story path given.
• Every item below belongs to the PR whose diff holds its line. Requirement traceability and reading order span all the PRs: a requirement met in another PR links there rather than being marked ❌, and the reading order starts at the PR holding the `.feature`.
• **Risks**: changes where a mistake would break behaviour beyond this story, such as a schema or public API contract, a data migration or persisted-state shape, authentication, authorisation or payments, or a shared component or utility with other callers. Each risk is anchored to the changed line that carries it and says what could break.
• **Blast radius**: for each changed export imported outside the PR, Grep for its callers. Give the caller count and up to five caller paths. Attach it to the risk on that export, or make it a risk when there are callers the PR doesn't touch.
• **Discussion points**: choices in the change a reviewer could reasonably dispute, such as departing from an existing pattern or a sibling implementation that does the same job, a new pattern, abstraction or dependency, fetching more data than it displays, a TODO, workaround or temporary check, or meeting a requirement in only one of its readings. Each is a question for reviewers, anchored to the hunk that makes the choice.
• **Requirement traceability** (only with a story markdown): for each requirement, the hunks that implement it (linked) and the scenario IDs that prove it. Mark ❌ a requirement with no code or no scenario, and ⚠️ a hunk that maps to no requirement.
• **Reading order**: changed files in the order to review them — `.feature` scenarios (the intended behaviour), then contracts and types, logic, UI, and unit tests. Start at contracts when no `.feature` changed. List skim-only files separately with the reason: recorded `.spec.js` files, lockfiles, generated code, snapshots, pure renames or moves (`git diff -M --stat`) and whitespace-only changes (`git diff -w`).

Phase 3: Evidence

• **BDD results**: the scenarios added or changed in the PR's `.feature` files. Run them through their recorded `.spec.js` filtered to their IDs (e.g. `npx playwright test <spec> --grep "<ID>:"`), or through `/execute-scenario` for scenarios not recorded yet. Note which way each ran.
• **Screenshots**: one for each changed hunk whose effect a user can see: a change to what renders (e.g. a component's markup), or to when or whether it shows (e.g. a condition, timer or event handler that decides when a toast, banner or dialog appears). Only hunks with no visible effect, such as a pure refactor, a type or a log line, get none.
• Trace the component's usages up to the screen that shows it. Reach that screen and state through the steps and stubs of a changed scenario that passes through it, else navigate there directly. When the hunk adds a state, such as an error, empty or loading view, bring the