code-review-pr-stinger

Start with README.md for the workflow map and detailed references.

Code review as a culture, not a gate. This skill encodes the full PR lifecycle from description quality through review execution to cultural health: the six-element PR description structure, the three-tier comment taxonomy, the 400-line small-PR threshold with DORA-backed justification, async-first review norms for distributed teams, rubber-stamp detection signals, and the review-as-mentorship lens. All factual claims trace to research/ source files.

Read this file first. Then navigate to the guide or template relevant to your current task.

---

When to activate

Activate code-review-pr-stinger when the user or orchestrator invokes code-review-pr-wasp-drone for any of:

• PR description authoring or audit -- the author needs a structured, reviewable description
• Review checklist generation -- the reviewer needs a context-specific checklist
• Comment coaching -- a review comment is vague, aggressive, or ambiguous
• Small-PR evaluation -- a PR is large and may need to be split
• Rubber-stamp diagnosis -- the team's reviews are approvals-without-substance
• Culture audit -- team lead wants a 30-PR culture scorecard

Do NOT activate for security finding remediation, logic correctness review, CI pipeline authoring, or repo settings.

---

The three cultural axioms

Everything in this skill flows from three axioms backed by the research corpus:

1. Small PRs are a forcing function for good design. PRs of 200-400 lines achieve 75%+ defect detection; PRs over 1,000 lines drop to 31%. AI-assisted coding (2025 DORA Report) caused a 91% increase in review time, making this more urgent than ever. Source: research/external/2026-05-20-gitautoreview-pr-size-metrics.md (source-repository research, not shipped with the plugin).

2. A PR description is a first-class communication artifact. A description that explains the motivation, context, what changed, and what did NOT change lets reviewers do their job without a synchronous call. Source: research/external/2026-05-20-tenthirtyam-pr-template-guide.md, research/external/2026-05-20-pullpanda-pr-description-templates.md (source-repository research, not shipped with the plugin).

3. Review comments have tiers; ambiguous comments erode trust. Every comment is either a blocker (must fix before merge), a suggestion (nice to have), or a nit (cosmetic / optional). A comment that does not state its tier forces the author to guess. Source: research/external/2026-05-20-google-eng-practices-comments.md, research/external/2026-05-20-pillaiinfotech-comment-taxonomy.md (source-repository research, not shipped with the plugin).

---

Canonical taxonomy: three-tier comment system

The Drone uses this taxonomy everywhere. It is derived from Google Engineering Practices, ARDURA, PanDev, and Pillai Infotech research. See guides/00-principles.md for the full decision tree.

Tier	Label	Meaning	Author must act?
1	blocker:	Must fix before merge. Safety, correctness, or design invariant violated.	Yes
2	suggestion:	Improvement worth doing, but merge can proceed.	Author's call
3	nit:	Cosmetic, style, minor. Low cognitive cost, easy to batch.	Optional
+	question:	Seeking understanding, not requesting a change.	Answer only
+	praise:	Positive reinforcement. Names a good decision explicitly.	No action

All five tiers are valid. blocker: and nit: are the most commonly used and the most commonly confused.

---

Canonical PR description structure (six elements)

Every PR description the Drone produces contains these six elements. See guides/01-pr-description.md for the full guide and templates/pr-description.md for the fill-in template.

1. Motivation -- Why does this PR exist? What problem does it solve?
2. Context -- What should the reviewer know before reading the diff? (Links, prior PRs, ADR references.)
3. What changed -- The "what" of the diff in human terms. One bullet per logical change.
4. What did NOT change -- Explicit scope boundary. Names things a reviewer might look for that are intentionally excluded.
5. Testing proof -- How was this tested? Screenshots, CI links, manual steps.
6. Reviewer hints -- Where to focus attention; which files are boilerplate; specific concerns to probe.

---

PR size heuristics (small-PR discipline)

Default threshold: 400 changed lines. This is configurable per team (300 for aggressive TBD teams). Source: research/external/2026-05-20-gitautoreview-pr-size-metrics.md, research/external/2026-05-20-ardura-implementation-guide.md (source-repository research, not shipped with the plugin).

Signal	Threshold	Action
Line count	> 400 lines	Flag; suggest splits per guides/03-small-prs.md
Concern count	> 5 unrelated logical concerns	Flag; suggest split by concern
Review time	> 60 minutes expected	Flag; schedule sync review session
Files changed	> 20 files	Audit for mixed concerns

---

Quick navigation

Task	Guide	Template / Example
Author or audit a PR description	guides/01-pr-description.md	templates/pr-description.md
Generate a review checklist	guides/02-review-checklist.md	templates/review-checklist.md
Evaluate PR size / suggest splits	guides/03-small-prs.md	examples/large-pr-split.md
Review async-first norms	guides/04-async-review.md	--
Diagnose rubber-stamp culture	guides/05-rubber-stamp-detection.md	examples/happy-path-pr-review.md
Coach a review comment	guides/06-comment-coaching.md	examples/happy-path-pr-review.md
Foundational principles	guides/00-principles.md	--

---

Open questions (from research; requires human decision)

These questions survived the scripture-historian sweep. They are documented rather than guessed:

1. Taxonomy naming: Should the Drone default to plain-English labels (blocker: / suggestion: / nit:) or emoji labels (🔴 / 🟡 / 💡)? Default: plain-English unless the team has an existing emoji convention.
2. Size threshold: Is 400 lines the right default, or should it vary by project type (e.g., 200 for security-critical code)? Default: 400, configurable.
3. Review captain scope: The review captain pattern works well for teams of 10+. For smaller teams, the Drone should recommend shared triage rather than a dedicated role. See guides/04-async-review.md.
4. GitHub API audit methodology: The culture scorecard audit uses GitHub API to pull 30 PR timelines. The exact API queries are documented in guides/05-rubber-stamp-detection.md based on first-principles design; no research precedent exists for this specific audit workflow.
5. "What did NOT change" format: This section is novel to this Drone (not found in research corpus). The six-element template treats it as a named H3 section. Teams may prefer an inline note style instead. See templates/pr-description.md.

These are flags for the user, not prompts to invent answers. Surface them when they become relevant to a specific request.

---

Research trail

All factual claims in this skill derive from source research notes (source-repository research, not shipped with the plugin). The shipped research/research-summary.md carries the executive summary and the 5 most influential sources; the full manifest, research/index.md, stays in the source repository.

Key sources (source-repository research, not shipped with the plugin):

• research/external/2026-05-20-google-eng-practices-standard.md (source-repository research, not shipped with the plugin) -- canonical authority
• research/external/2026-05-20-google-eng-practices-comments.md (source-repository research, not shipped with the plugin) -- comment-writing norms
• research/external/2026-05-20-stackfyi-best-practices-guide.md (source-repository research, not shipped with the plugin) -- 2026 synthesis, rubber-stamp signals
• research/external/2026-05-20-gitautoreview-pr-size-metrics.md (source-repository research, not shipped with the plugin) -- 400-line threshold data, DORA 2025
• research/external/2026-05-20-pillaiinfotech-comment-taxonomy.md (source-repository research, not shipped with the plugin) -- five-tier taxonomy with worked rewrites