pr-first-reader-check

Inspects pull request titles, descriptions, commits, and comments for jargon and readability issues.

Updated Oct 14, 2024
One-click install
npx skills add https://github.com/tktcorporation/food-shop-search --skill pr-first-reader-check-tktcorporation
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: pr-first-reader-check
Source: https://github.com/tktcorporation/food-shop-search/tree/main/.claude/skills/pr-first-reader-check
Command: npx skills add https://github.com/tktcorporation/food-shop-search --skill pr-first-reader-check-tktcorporation

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Pull requests often contain context-dependent jargon (project-only labels like "Phase-2", references to files reviewers cannot open, undefined abbreviations) and hard-to-read sentences (long multi-claim sentences, nominalizations, buried conclusions) that block first-time reviewers from understanding the change without back-and-forth questions. ## Core Features & Use Cases - Context Dependency Detection: Flags issue/PR-only naming, unlinked external references, undefined abbreviations, implicit assumptions, and raw internal IDs that a new team member cannot resolve. - Readability Analysis: Identifies sentences with multiple claims, distant subject-verb pairs, nominalized verbs, roundabout predicates, and conclusions buried at the end, with concrete before/after rewrite patterns. - Full PR Coverage: Inspects the PR title, body, commit messages, diff comments, and newly introduced identifiers using gh pr view, gh pr diff, and git log. - Use Case: Before submitting a PR, run the check to confirm a reviewer from another team could understand it from the PR alone, then apply the suggested fixes and show before/after diffs. ## Quick Start Check whether my current pull request is understandable to a first-time reviewer and fix any jargon or hard-to-read sentences.

Frequently Asked Questions about pr-first-reader-check

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check if my pull request is understandable to new reviewers?▼

Run the check against your PR title, body, commit messages, and diff comments. It flags context-dependent terms like project-only labels and unlinked references, plus readability issues like long multi-claim sentences, and suggests concrete fixes.

What counts as jargon in a pull request description?▼

Jargon includes names that exist only in issues or planning docs (like "Phase-2"), references to files in other repositories, undefined abbreviations, and raw internal IDs. Terms with actual code definitions that reviewers can grep are acceptable.

Does this check require the GitHub CLI?▼

Yes, it uses gh pr view and gh pr diff to fetch the PR title, body, and diff, plus git log for commit messages. It also sets origin/HEAD automatically to avoid missing commits in the range.

Should internal product or service names be removed from PRs?▼

No. Established terms with code-level definitions, UI-visible feature names, and standard technical vocabulary should stay. Only names that exist solely in issue or PR context without any code or product counterpart are flagged.

When should I not run a PR readability check?▼

Skip it for pure renames or changes with zero prose. If the PR contains even one line of comment or description, running the check is worthwhile since context-dependent wording usually slips in somewhere.