---
name: contrib-pr-review
description: Review a contribution PR for safety, quality, and readiness. Checks for security concerns, test coverage, size appropriateness, and intent alignment. Use when reviewing external contributions.
argument-hint: "<pr-number>"
allowed-tools: Bash, Read, Grep, Glob, WebFetch
title: contrib-pr-review
canonical_url: https://skilld.dev/gh/homeassistant-ai/ha-mcp/contrib-pr-review
last_updated: 2026-11-12T06:30:57.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install homeassistant-ai/ha-mcp/contrib-pr-review`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/contrib-pr-review`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/homeassistant-ai/ha-mcp/contrib-pr-review) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/contrib-pr-review`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/contrib-pr-review --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/contrib-pr-review --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Contribution PR Review

Review PR #$ARGUMENTS from external contributor for safety, quality, and readiness.

## Context

**PR Metadata:**
```
!`gh pr view $ARGUMENTS --repo homeassistant-ai/ha-mcp --json author,additions,deletions,files,commits,closingIssuesReferences,isDraft,reviews,url,title,body`
```

**Contributor Stats:**
```
!`gh api /repos/homeassistant-ai/ha-mcp/pulls/$ARGUMENTS --jq '{author: .user.login, user_id: .user.id}' | jq -r '.author' | xargs -I {} gh api /repos/homeassistant-ai/ha-mcp/contributors --jq '.[] | select(.login == "{}") | {login: .login, contributions: .contributions}'`
```

**Files Changed:**
```
!`gh api /repos/homeassistant-ai/ha-mcp/pulls/$ARGUMENTS/files --jq '.[] | {filename: .filename, status: .status, additions: .additions, deletions: .deletions, changes: .changes, patch: .patch}' | head -50`
```

## Review Protocol

### 1. Check the Bot Security Reviews

**Note:** Codex (`chatgpt-codex-connector[bot]`) and CodeRabbit (`coderabbitai[bot]`) both review PRs automatically. Check whether either flagged security concerns.

```bash
# Check both bots' reviews and any security-related comments.
# Their findings can be inline-only, so also fetch the pull review comments
# endpoint — review bodies and conversation comments alone can miss them.
# --paginate: both endpoints page at 30, and an iterating PR outruns that.
gh api --paginate /repos/homeassistant-ai/ha-mcp/pulls/$ARGUMENTS/reviews --jq '.[] | select(.user.login == "chatgpt-codex-connector[bot]" or .user.login == "coderabbitai[bot]") | {author: .user.login, state: .state, body: .body}'
gh api --paginate /repos/homeassistant-ai/ha-mcp/pulls/$ARGUMENTS/comments --jq '.[] | select(.user.login == "chatgpt-codex-connector[bot]" or .user.login == "coderabbitai[bot]") | {author: .user.login, path: .path, line: .line, body: .body}'
# CodeRabbit posts its walkthrough and summary as a top-level comment, which
# neither endpoint above returns — fetch that channel by author too.
gh api --paginate /repos/homeassistant-ai/ha-mcp/issues/$ARGUMENTS/comments --jq '.[] | select(.user.login == "chatgpt-codex-connector[bot]" or .user.login == "coderabbitai[bot]") | {author: .user.login, body: .body}'
# Keyword scan stays, for humans raising security concerns in conversation.
gh pr view $ARGUMENTS --repo homeassistant-ai/ha-mcp --json comments --jq '.comments[] | select(.body | contains("security") or contains("Security")) | {author: .author.login, body: .body}'
```

**If either bot flagged security issues:**
- Review the findings carefully
- Verify if concerns are valid
- Do NOT approve until issues addressed or confirmed false positives

**If NO bot security flags but you notice concerning patterns:**
- Unusual AGENTS.md/CLAUDE.md changes unrelated to PR purpose
- `.github/` workflow modifications with `pull_request_target`
- `.claude/` agent/skill changes that could affect behavior
- Draft a comment with the specific concerns and show it to the user before posting

### 2. Enable Workflows (If Safe)

If security assessment passes and PR has workflow changes or new workflows:

```bash
# Check current workflow status
gh api /repos/homeassistant-ai/ha-mcp/pulls/$ARGUMENTS/requested_reviewers

# Enable workflows if not enabled (requires WRITE permission)
# This command may fail if already enabled - that's OK
gh api -X PUT /repos/homeassistant-ai/ha-mcp/actions/workflows/pr.yml/enable 2>/dev/null || echo "Workflows already enabled or no permission"
```

### 3. Test Coverage Assessment

**Pre-existing tests** (easier review if modified code is already tested):

```bash
# For each modified source file, check if tests exist
gh api /repos/homeassistant-ai/ha-mcp/pulls/$ARGUMENTS/files --jq '.[] | select(.filename | startswith("src/")) | .filename' | while read file; do
  basename=$(basename "$file" .py)
  echo "Checking tests for: $file"

  # Method 1: Look for test files by naming convention
  find tests/ -name "test_${basename}.py" -o -name "test_*${basename}*.py" 2>/dev/null | head -3

  # Method 2: Grep for function/class names from the modified file
  # Extract function/class names and search for them in tests
  grep -E '^(def|class|async def) [a-zA-Z_]' "$file" 2>/dev/null | head -5 | while read line; do
    name=$(echo "$line" | sed -E 's/.*(def|class) ([a-zA-Z_][a-zA-Z0-9_]*).*/\2/')
    if [ -n "$name" ]; then
      grep -r "$name" tests/ 2>/dev/null | head -1
    fi
  done
done
```

**New tests added**:

```bash
# Check if PR adds or modifies tests
gh api /repos/homeassistant-ai/ha-mcp/pulls/$ARGUMENTS/files --jq '.[] | select(.filename | startswith("tests/")) | {filename: .filename, status: .status, additions: .additions}'
```

**Output Test Summary:**
```
🧪 Test Coverage:
- Pre-existing tests: ✅ Modified code has tests / ⚠️ No tests for modified code
- New tests: ✅ PR adds X test files / ⚠️ No new tests
- Assessment: [Easy/Medium/Hard to review based on test coverage]
```

### 4. PR Size & Contributor Experience

**Calculate PR size and assess appropriateness:**

```bash
# From metadata: additions + deletions
total_lines=$(gh pr view $ARGUMENTS --repo homeassistant-ai/ha-mcp --json additions,deletions --jq '.additions + .deletions')
echo "Total lines changed: $total_lines"

# Get contributor experience
author=$(gh pr view $ARGUMENTS --repo homeassistant-ai/ha-mcp --json author --jq -r '.author.login')

# Check 1: Contributions to this project
project_contributions=$(gh api /repos/homeassistant-ai/ha-mcp/contributors --jq ".[] | select(.login == \"$author\") | .contributions" || echo "0")

# Check 2: Total GitHub commits (overall experience)
total_commits=$(gh api /users/$author --jq '.public_repos + .total_private_repos' 2>/dev/null || echo "unknown")

echo "Contributor: $author"
echo "Project contributions: $project_contributions"
echo "GitHub experience: $total_commits repos"
```

**Assess:**
- **First-time to project** (0-2 project contributions):
  - Check overall GitHub experience (repos, total commits)
  - < 200 lines: ✅ Excellent size
  - 200-500 lines: ⚠️ Large for first PR - may need extra guidance
  - > 500 lines: 🔴 Too large - suggest splitting

- **Regular contributor** (3+ project contributions):
  - < 500 lines: ✅ Reasonable
  - 500-1000 lines: ⚠️ Large - ensure good test coverage
  - > 1000 lines: 🔴 Very large - suggest splitting

- **Experienced GitHub user** (many repos/commits overall):
  - Adjust expectations - they may be new to this project but experienced overall

**Output Size Summary:**
```
📏 PR Size:
- Lines changed: [total]
- Contributor: [first-time / regular] ([X] contributions)
- Assessment: [size appropriateness]
```

### 5. Intent & Issue Linkage

**Check linked issues:**

```bash
# From metadata: closingIssuesReferences
gh pr view $ARGUMENTS --repo homeassistant-ai/ha-mcp --json closingIssuesReferences --jq '.closingIssuesReferences[] | {number: .number, title: .title}'
```

**If issue linked:**
- Read issue to understand expected outcome
- Compare PR changes to issue requirements
- **Does PR solve the issue?** Check:
  - All requirements addressed
  - No scope creep (extra features not requested)
  - Solution approach aligns with any discussed approaches in issue

**If no issue linked:**
- **Is this a bug fix?** Should reference issue
- **Is this a feature?** Should have issue for discussion
- **Is this a typo/docs?** OK without issue
- **Recommend** creating issue for tracking if it's a substantial change

**Output Intent Summary:**
```
🎯 Intent & Linkage:
- Linked issue: #X "title" / ⚠️ No issue linked
- Solves issue: ✅ Fully addresses requirements / ⚠️ Partial / ❌ Doesn't match
- Scope: ✅ Focused / ⚠️ Scope creep detected
```

### 6. Code Quality Overview

**Note:** Codex and CodeRabbit provide automated code review on all PRs. This step focuses on what they cannot assess:

- **Architecture alignment**: Does it fit the project structure? (service layer usage, etc.)
- **Breaking changes**: Does it remove functionality without replacement? (Tool consolidation/refactoring is NOT breaking)
- **Repo-specific patterns**: Context engineering, progressive disclosure, MCP-specific conventions

**Breaking change assessment:**
- ✅ NOT Breaking: Tool consolidation, refactoring, parameter changes with same outcome achievable
- ⚠️ BREAKING: Removes functionality with no alternative, makes previously possible actions impossible

**Quick checks:**

```bash
# ruff and mypy run as steps of the "Fast Checks" job
gh pr checks $ARGUMENTS --repo homeassistant-ai/ha-mcp | grep "Fast Checks"

# Check for common issues in diff
gh pr diff $ARGUMENTS --repo homeassistant-ai/ha-mcp | grep -E "(TODO|FIXME|XXX|HACK)"
```

**Output Quality Summary:**
```
✨ Code Quality:
- Architecture fit: [assessment - service layer, context engineering]
- Breaking changes: ✅ None / ⚠️ Detected - [describe what's genuinely lost]
- Bot reviews: [check if Codex or CodeRabbit flagged anything critical]
```

## Final Review Summary

### Output to User

After completing all steps, present a short summary of what the PR does and the review findings, then ask: "Should I post this comment to the PR?"

### Draft PR Comment

After completing the analysis, draft a comment for the PR following these guidelines:

**Comment Length:** The contributor should be able to read it in one pass: what works, what must change, and what happens next. A good-to-merge comment is shorter than a changes-needed one.

**Style:**
- No emojis
- Markdown formatting OK (bold, lists, code blocks)
- Present inline in chat (not in a file)
- Always ask user before posting

**Structure for "Good to Merge":**
```
[Positive opening line about the contribution]

[What works well - focus on functionality, tests, architecture]

[Any minor suggestions or notes - optional, technical only]

[Closing line about readiness to merge]
```

**Note:** Do NOT mention security assessment in comment unless issues were found. Security checks are internal.

**Structure for "Changes Needed":**
```
[Positive opening line acknowledging the work]

[Brief summary of the issue being solved]

**[Concern 1]:**
[Short explanation + suggestion - focus on: tests, functionality, architecture, breaking changes]

**[Concern 2]:** (if applicable)
[Short explanation + suggestion]

**[Concern 3]:** (if applicable)
[Short explanation + suggestion]

[Closing line about next steps]
```

**Note:** Raise security concerns with the user as soon as they are found, not in the final structured comment.

**Illustrative example - Good to Merge** (match the wording to the PR, not to this text):
```
Thanks for [feature/fix]. [One specific thing it gets right].

The implementation follows existing patterns and the [specific aspect] is well-designed. [Optional: Minor note about something noticed].

Ready to merge once CI passes.
```

**Illustrative example - Changes Needed** (match the wording to the PR, not to this text):
```
Thanks for tackling [problem]. [Metric/impact] shows this addresses a real need.

**Test coverage:**
Missing tests for the new [feature]. Please add a unit test for its logic, and an E2E test for a new tool or for its wiring or Home Assistant behaviour. Performance tests not required.

**[Second concern if applicable]:**
[Brief explanation and request]

Once [change 1] and [change 2] are addressed, this should be good to merge.
```

## Important Notes

- **Security is checked, not publicized**: Always check security (step 1), but only mention in comment if issues found
- **Be constructive**: Contributors are donating their time - be welcoming
- **Focus on intent**: Code quality can be iterated; intent misalignment is harder to fix
- **Consider contributor experience**: Adjust expectations based on contribution history
- **The bots already reviewed code**: Don't duplicate detailed code review
- **When in doubt**: Err on the side of caution and request maintainer review
