--- name: "code-review-pr-stinger" description: "Improve PR descriptions and review practice. Use for checklists, PR size, comment quality, or rubber-stamp diagnosis. Read README.md for the guide map." license: AGPL-3.0-or-later --- # code-review-pr-stinger Start with [README.md](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`. 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`. 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`. --- ## 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`. | 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 sources in `research/`. See `research/index.md` for the full manifest and `research/research-summary.md` for the executive summary and the 5 most influential sources. Key sources: - `research/external/2026-05-20-google-eng-practices-standard.md` -- canonical authority - `research/external/2026-05-20-google-eng-practices-comments.md` -- comment-writing norms - `research/external/2026-05-20-stackfyi-best-practices-guide.md` -- 2026 synthesis, rubber-stamp signals - `research/external/2026-05-20-gitautoreview-pr-size-metrics.md` -- 400-line threshold data, DORA 2025 - `research/external/2026-05-20-pillaiinfotech-comment-taxonomy.md` -- five-tier taxonomy with worked rewrites