diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 0896333..175cd9d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -17,6 +17,14 @@ "./skills/diataxis-gen-readme", "./skills/diataxis-organize-docs" ] + }, + { + "name": "gh", + "description": "GitHub workflow skills for enriching PR descriptions, automating code review context, and streamlining collaboration through the gh CLI", + "source": "./", + "skills": [ + "./skills/gh-enrich-pr-description" + ] } ] } diff --git a/skills/gh-enrich-pr-description/SKILL.md b/skills/gh-enrich-pr-description/SKILL.md new file mode 100644 index 0000000..47e87bf --- /dev/null +++ b/skills/gh-enrich-pr-description/SKILL.md @@ -0,0 +1,126 @@ +--- +name: gh-enrich-pr-description +description: Enrich GitHub PR descriptions with root-cause context, related issues/PRs, and CC mentions. Use when creating or editing a PR, when a PR has an empty or sparse description, or when the user asks to improve a PR description. +--- + +# Enrich PR Description + +Analyze branch changes and git history to build a rich PR description with three sections: a contextual summary, related issues/PRs, and people to CC. + +## When to Use + +- User asks to create a PR (before `gh pr create`) +- User asks to improve/fix a PR description +- A PR has an empty or sparse body +- User asks who to CC or what to reference + +## Workflow + +### 1. Gather Context + +Run these in parallel to understand the full picture: + +```bash +# Current branch and diff against base +git log --oneline main..HEAD +git diff main...HEAD + +# PR if it already exists +gh pr view --json number,title,body,url,baseRefName,headRefName 2>/dev/null +``` + +### 2. Investigate the "Why" + +For each changed file, dig into the history to understand the origin of the problem: + +```bash +# Blame the changed lines on the base branch to find who introduced them +git blame main -- | sed -n ',p' + +# Show the originating commit +git log -1 --format='%H %an <%ae> %s' + +# Find the PR that introduced the commit +gh pr list --search " OR " --state merged --json number,title,author,url +``` + +Key questions to answer: +- What is the root cause of the problem? +- Is this a permanent vs transient condition being mishandled? +- What contract or convention was violated? +- Is there a sibling/similar function that handles the same case correctly? + +### 3. Find Related Issues and PRs + +Search for related work using ticket IDs, keywords, and function names: + +```bash +# By ticket ID from branch name or commit messages +gh pr list --search "" --state all --json number,title,author,url,state + +# By keywords from the change +gh pr list --search "" --state all --limit 10 --json number,title,author,url,state +``` + +Classify each related PR/issue: +- **Origin** -- introduced the code being fixed +- **Related** -- touches the same area or feature +- **Alternate** -- different approach to the same problem +- **Blocked by / Blocks** -- dependency relationship + +### 4. Identify People to CC + +From git blame and related PRs, collect GitHub usernames of people who: +- Authored the code being changed (from `git blame`) +- Authored related open PRs in the same area +- Are reviewers on related PRs + +Extract GitHub usernames from PR data: + +```bash +gh pr view --json author --jq '.author.login' +``` + +### 5. Compose the Description + +Use this structure: + +```markdown +## Summary + +[2-4 sentences explaining WHAT changed and WHY. Focus on the root cause +and why the previous behavior was wrong. Include the mechanism of failure.] + +> [!NOTE] +> [Optional callout for additional context, such as a sibling function +> that handles the same case correctly, or a related convention.] + +## Related + +- # -- : +- # -- : + +CC @ @ +``` + +### 6. Apply the Description + +For an existing PR: + +```bash +gh pr edit --body "$(cat <<'EOF' + +EOF +)" +``` + +For a new PR, pass it to `gh pr create --body`. + +## Quality Checks + +- [ ] Summary explains the root cause, not just the symptom +- [ ] Summary describes the mechanism (how the bug manifests) +- [ ] Related PRs include the one that introduced the issue +- [ ] Each related PR has a relationship label (origin, related, alternate) +- [ ] CC list includes the author of the originating code +- [ ] No speculative CC -- only people with direct involvement