/review-configuration

PR/MR Review: Configuration & Options

Command options, configuration, best practices, and integration details.

> **See Also**: [Main Command](../../pr-review.md) | [Workflow](review-workflow.md) | [Framework](review-framework.md)

**Platform Note**: Commands below show GitHub (`gh`) examples. Check session context for `git_platform:` and consult `Skill(leyline:git-platform)` for GitLab (`glab`) / Bitbucket equivalents.

Advanced Features

1. Automated Issue Creation

# For each backlog item:
gh issue create \
  --title "[Enhancement] <title>" \
  --body="## Context
Identified during PR #<number> review

## Details
<finding details>

## Suggested Approach
<implementation notes>

## Priority
Medium - Improvement opportunity

---
*Auto-created by pr-review*" \
  --label="enhancement,backlog"

2. Quality Metrics Integration

### Quality Metrics
- **Code Coverage**: 85% (target: 80%) PASS
- **Complexity**: Low (new functions < 10 cyclomatic) PASS
- **Duplication**: 2% (target: <5%) PASS
- **Security**: 0 high-severity issues PASS

3. Reviewer Guidance

### Review Focus Areas
Based on scope and analysis:
1. Verify JWT implementation (security)
2. Check password hashing (security)
3. Validate error handling (robustness)
4. Review test coverage (quality)

Integration Benefits

For Reviewers

• Clear understanding of PR scope
• Prioritized feedback (blocking vs suggestions)
• Context-aware recommendations
• Reduced review time through automation

For Authors

• Specific, actionable feedback
• Clear path to approval
• Backlog items automatically created
• Quality metrics provided

For Teams

• Consistent review standards
• Scope discipline enforced
• Technical debt tracked
• Quality gates automated

Error Handling

No Scope Artifacts Found

Warning: No plan/spec found for this PR
Using PR description as scope baseline
Recommendation: Create plan.md for future PRs

Analysis Failures

Error: Superpowers code review failed
Falling back to manual review mode

GitHub API Issues

Warning: Cannot create backlog issues (rate limit)
Please create manually from backlog section

GitHub Review Submission Errors

**No PR Found:**

# If no PR exists for current branch
gh pr view --json number -q '.number'
# Returns empty - skip GitHub submission
Warning: No PR found for current branch. Review saved locally only.
# Tip: Use --local to intentionally write to a file

**Cannot Approve Own PR:**

# Error: "Review Can not approve your own pull request"
# This occurs when using --approve or REQUEST_CHANGES on your own PR

# SOLUTION: Check authorship first, use COMMENT event for own PRs
PR_AUTHOR=$(gh pr view $PR_NUMBER --json author -q '.author.login')
CURRENT_USER=$(gh api user -q '.login')
if [[ "$PR_AUTHOR" == "$CURRENT_USER" ]]; then
  # Use COMMENT instead of APPROVE/REQUEST_CHANGES
  gh pr review $PR_NUMBER --comment --body "Review summary..."
fi

**Line Comment API Errors:**

# Error: "line is not a permitted key" or "No subschema in oneOf matched"
# This happens when using the comments endpoint with line/side parameters

# WRONG - Individual comments endpoint doesn't support line/side:
gh api repos/{owner}/{repo}/pulls/{pr}/comments \
  -f body="..." -f path="file.rs" -f line=45 -f side="RIGHT"  # FAILS

# CORRECT - Use the reviews endpoint with comments array:
gh api repos/{owner}/{repo}/pulls/{pr}/reviews \
  --method POST \
  -f event="COMMENT" \
  -f body="" \
  -f 'comments[][path]=file.rs' \
  -F 'comments[][line]=45' \              # Note: -F for integer
  -f 'comments[][body]=Comment text'

**Line Not In Diff (422 Unprocessable Entity):**

# Error: "Line could not be resolved"
# This occurs when the line number isn't part of the PR diff

# SOLUTION: Post as a general PR comment instead
gh pr comment $PR_NUMBER --body "**[G2] Suggestion**

Location: app.rs:1933 (not in PR diff - general observation)
Issue: File approaching size threshold

**Suggestion:** Consider modularization."

**Integer vs String Parameters:**

# Error: "128 is not an integer" (when passed as string)

# WRONG - Using -f passes as string:
-f 'comments[][line]=128'

# CORRECT - Using -F passes as raw/integer:
-F 'comments[][line]=128'

**Pending Review Already Exists:**

# Check for existing pending review
gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews \
  --jq '.[] | select(.state == "PENDING")'

A pending draft review of yours blocks creating another, and submitting it would publish your unsent comments with the new findings. `plugins/sanctum/scripts/post_formal_review.py` exits 3 with the draft's comment count. Ask before rerunning with `--pending join`, which adds the findings to the draft and submits it as one review.

**Authentication Issues:**

# Verify gh is authenticated
gh auth status
# If not authenticated, proceed with dry-run mode
Warning: GitHub CLI not authenticated. Running in dry-run mode.

**GraphQL Token Scope Errors:**

# Error: "Your token has not been granted the required scopes to execute this query.
#         The 'login' field requires one of the following scopes: ['read:org']"

# This happens when using `gh pr edit` which uses GraphQL and queries org data
# even for personal repos. The workflow handles this automatically:

# 1. First attempts direct API (only needs repo scope):
gh api repos/{owner}/{repo}/pulls/$PR_NUMBER -X PATCH -f body="..."

# 2. Falls back to posting as comment if API fails:
gh pr comment $PR_NUMBER --body "## PR Summary (Auto-generated)..."

# To avoid this error, ensure your GitHub token has these scopes:
# - repo (required)
# - read:org (optional, enables gh pr edit)

Configuration

pr_review:
  default_scope_mode: "standard"
  auto_approve_threshold: 0  # No blocking issues
  auto_create_issues: true   # Automatic issue creation for out-of-scope items (