reader-protocol-pr-review

Reader Protocol PR Review

Use this when reviewing a PR in the Reader's social/atmosphere/mastodon territory — slice work for the protocol-adapter pattern, optimistic mutations, or the shared post-card components. The recurring findings are concrete enough to be a checklist; the rubric below comes from the CM-658/CM-660 cycle where the same issues appeared in both PRs.

Rubric

For each finding write:

| Severity | File:line | Issue (1-2 sentences) | Suggested fix |

• Severity tags: blocker (PR can't merge), important (real bug, would cause user-visible issues), nit (cleanup or hardening).
• File:line: anchor with absolute path or repo-relative path so the comment can be left inline on GitHub. Use gh api repos/Automattic/wp-calypso/pulls/{n}/comments to post inline replies (not top-level PR comments) when the line is in the diff.
• In-PR vs follow-up: explicitly call this out. Architectural changes that span multiple slices belong in a follow-up issue. Defensive hardening, missing default arms, etc. are cheap to fold in.
• Verdict line: Approve / Request changes / Needs more discussion. If approve, list any follow-ups worth filing as separate tickets.

Cap reviews at ~700 words. The reviewer's signal-to-noise ratio matters — detailed prose drowns out the actual blockers.

When to dispatch the code-reviewer agent

The superpowers:code-reviewer agent is independent and reads the diff fresh. Dispatch it when:

• The PR is large (>20 files or >500 lines).
• The PR shape is structurally similar to a sibling PR you've already reviewed (it'll surface the same recurring smells consistently).
• You authored adjacent code and want an independent eye.

Brief the agent with: PR number, branch path, what the PR does, and a list of recurring smells from references/common-smells.md to specifically check. The agent's response is the body of your review.

Reply convention on PR threads

• No "thanks for the review" — superpowers:receiving-code-review rules apply. State the fix or push back; actions speak.
• Reply on inline comment threads for inline review comments (gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies), not as top-level PR comments. The threading matters for context.
• Top-level comment for review-summary acknowledgement, listing which findings landed in commit X and which are deferred follow-ups (with rationale).
• No fabricated wp.me shortlinks — never invent a shortlink for a *.wordpress.com URL. See a8c-url-shorthand:a8c-url-shorthand.

Common smells

See references/common-smells.md — checklist of 9+ recurring findings from the recent slice cycle. Walk it before submitting your review.

Cross-pollinating fixes between sibling PRs

When two slice PRs are open simultaneously (CM-658 + CM-660 was the canonical case), review feedback on one almost always applies to the other. The architectural patterns mirror each other.

After landing a fix on PR A, check whether PR B has the same issue:

git -C /Users/pfefferle/Code/wp-calypso show <fix-commit-on-A> -- <relevant-paths>
git -C /Users/pfefferle/Code/wp-calypso show <branch-of-B>:<relevant-path> | grep <smell>

If yes, apply the fix to B too. Don't wait for the reviewer to file the same finding twice.

File-shape expectations

These are the Reader-protocol files that consistently need attention. Reviewers should check each:

Reference

• references/common-smells.md — the smell catalog, with concrete examples from the slice cycle.
• client/reader/social/AGENTS.md — describes the provider-adapter pattern + naming convention.
• client/reader/AGENTS.md § "Optimistic-mutation hardening checklist" — engineering-side pre-flight for the patterns this skill reviews.