/review-pr

Reviewing PR: $ARGUMENTS

READ-ONLY MODE: This command analyzes the PR and posts a review to GitHub WITHOUT making any code changes. Use /fix-pr to apply fixes.

Options

• --local - Show findings locally only, skip GitHub posting

Step 1: Determine Posting Mode

If --local flag is provided: Skip prompt, proceed in local-only mode.

If no flag provided: Use AskUserQuestion to prompt BEFORE starting review:

Question: "Would you like to post this review to GitHub when complete?"
Options:
  - "Yes, post to GitHub" (default)
  - "No, show locally only"

Store the user's choice and proceed with the review.

---

Step 2: Determine Which PR to Review

# Parse arguments for --local flag
LOCAL_ONLY=false
PR_ARG=""
for arg in $ARGUMENTS; do
    if [ "$arg" = "--local" ]; then
        LOCAL_ONLY=true
    else
        PR_ARG="$arg"
    fi
done

If no PR argument provided: Use AskUserQuestion to ask for the PR:

Question: "Which PR would you like to review?"
Header: "PR"
Options:
  - "Enter PR number" (e.g., 6390)
  - "Enter PR name/title" (e.g., "Arkansas TANF")

Then use the provided value to find the PR.

# If argument is a number, use it directly
if [[ "$PR_ARG" =~ ^[0-9]+$ ]]; then
    PR_NUMBER=$PR_ARG
# Otherwise, search for PR by description/title
else
    PR_NUMBER=$(gh pr list --search "$PR_ARG" --json number,title --jq '.[0].number')
    if [ -z "$PR_NUMBER" ]; then
        echo "No PR found matching: $PR_ARG"
        exit 1
    fi
fi

echo "Reviewing PR #$PR_NUMBER"
if [ "$LOCAL_ONLY" = true ]; then
    echo "Mode: Local only (will not post to GitHub)"
fi

---

Phase 1: Gather Context

Collect information about the PR:

gh pr view $PR_NUMBER --json title,body,author,baseRefName,headRefName
gh pr checks $PR_NUMBER
gh pr diff $PR_NUMBER

Document:

• PR type: New program, bug fix, enhancement, or refactor
• CI status: Passing, failing, or pending
• Files changed: Parameters, variables, tests
• Existing comments: Any prior review feedback

---

Phase 2: Run Validators

Run 4 focused validators. Each reports issues but does NOT make changes.

Check 1: Regulatory Accuracy (Critical)

Invoke program-reviewer to:

• Research regulations FIRST (independent of code)
• Compare implementation to legal requirements
• Identify discrepancies between code and law
• Flag missing program components

Key question: Does this implementation correctly reflect the law?

Check 2: Reference Quality (Critical)

Invoke reference-validator to:

• Find parameters missing references
• Check reference format (page numbers, detailed sections)
• Verify references corroborate values
• Check jurisdiction match (federal vs state sources)

Key question: Can every value be traced to an authoritative source?

Check 3: Code Patterns (Critical + Should)

Invoke implementation-validator to:

• Find hard-coded values in formulas
• Check variable naming conventions
• Verify correct patterns (adds, add(), add() > 0)
• Check period usage (period vs period.this_year)
• Identify entity-level issues
• Flag incomplete implementations (TODOs, stubs)

Key question: Does the code follow PolicyEngine standards?

Check 4: Test Coverage (Should)

Invoke edge-case-generator to:

• Identify missing boundary tests
• Find untested edge cases
• Check parameter combinations not tested
• Verify integration test exists

Key question: Are the important scenarios tested?

---

Phase 3: Compile Findings

Aggregate and prioritize all findings:

Priority Levels

Critical (Must Fix Before Merge):

• Regulatory mismatches (code doesn't match law)
• Hard-coded values (can't update when law changes)
• Missing or non-corroborating references
• CI failures
• Incorrect implementations

Should Address:

• Code pattern violations
• Missing edge case tests
• Naming convention issues
• Period usage errors

Suggestions:

• Documentation improvements
• Performance optimizations
• Code style refinements

Deduplication

If multiple validators flag the same issue, combine into one finding with the highest priority level.

---

Phase 4: Post Review

If user chose local-only mode: Display findings locally and skip GitHub posting.

If user chose to post to GitHub: Continue with posting.

Check for Existing Reviews (if posting)

Before posting, check if you have a prior review on this PR:

# Get current GitHub user
CURRENT_USER=$(gh api user --jq '.login')

# Check for existing reviews from current user
EXISTING=$(gh api "/repos/{owner}/{repo}/pulls/$PR_NUMBER/comments" \
  --jq "[.[] | select(.user.login == \"$CURRENT_USER\")] | length")

if [ "$EXISTING" -gt 0 ]; then
    echo "Found existing review comments - will post updated review"
fi

Post the Review (if user confirms)

Post a single, clear review:

gh pr comment $PR_NUMBER --body "## PR Review

### 🔴 Critical (Must Fix)

1. **Regulatory mismatch**: [Description with specific file:line]
2. **Hard-coded value**: [Value] in [file:line] - create parameter
3. **Reference issue**: [File] - [specific problem]

### 🟡 Should Address

1. **Pattern violation**: Use \`add()\` instead of manual sum in [file:line]
2. **Missing test**: Add edge case for [scenario]
3. **Formatting issue**: [file] - [issue: parameter description/label/values, variable reference format]

### 🟢 Suggestions

1. Consider adding calculation example in docstring

---

### Validation Summary

| Check | Result |
|-------|--------|
| Regulatory Accuracy | X issues |
| Reference Quality | X issues |
| Code Patterns | X issues |
| Formatting (params & vars) | X issues |
| Test Coverage | X gaps |
| CI Status | Passing/Failing |

### Next Steps

To auto-fix issues: \`/fix-pr $PR_NUMBER\`

Or address manually and re-request review."

CI Failures

If CI is failing, add to the Critical section:

gh pr checks $PR_NUMBER --json name,conclusion \
  --jq '.[] | select(.conclusion == "failure") | "- **CI Failure**: " + .name'

---

Review Severity

Based on findings, set the review type:

Severity	When to Use
APPROVE	No critical issues, minor suggestions only
COMMENT	Has issues but not blocking (educational)
REQUEST_CHANGES	Has critical issues that must be fixed

---

Usage Examples

/review-pr              # Review PR for current branch (prompts before posting)
/review-pr 6390         # Review PR #6390 (prompts before posting)
/review-pr "Arkansas"   # Search for PR by title (prompts before posting)
/review-pr --local      # Review current branch's PR, show locally only
/review-pr 6390 --local # Review PR #6390, show locally only

---

Critical Issues (Always Flag)

These MUST be fixed before merge:

1. Regulatory mismatch - Implementation doesn't match law
2. Hard-coded values - Numbers in formulas instead of parameters
3. Missing references - Can't verify where values came from
4. Non-corroborating references - Reference doesn't support value
5. CI failures - Tests or linting failing
6. Incorrect formula - Wrong calculation logic

---

Pre-Flight Checklist

Before starting:

• I will ask user about posting mode FIRST (unless --local flag used)
• I will NOT make any code changes
• I will run all 4 validators
• I will prioritize findings (Critical > Should > Suggestions)
• I will be constructive and actionable

Start by asking the user about posting mode, then proceed through the phases.