gh-policyengine-policyengine-claude/commands/fix-pr.md

description

description
Apply fixes to an existing PR, addressing all review comments and validation issues

Fixing PR: $ARGUMENTS

Determining Which PR to Review

First, determine which PR to review based on the arguments:

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

echo "Reviewing PR #$PR_NUMBER"

Orchestrate agents to review, validate, and fix issues in PR #$PR_NUMBER, addressing all GitHub review comments.

⚠️ CRITICAL: Agent Usage is MANDATORY

You are a coordinator, NOT an implementer. You MUST:

1. NEVER make direct code changes - always use agents
2. INVOKE agents with specific, detailed instructions
3. WAIT for each agent to complete before proceeding
4. VERIFY agent outputs before moving to next phase

If you find yourself using Edit, Write, or MultiEdit directly, STOP and invoke the appropriate agent instead.

Phase 1: PR Analysis

After determining PR_NUMBER above, gather context about the PR and review comments:

gh pr view $PR_NUMBER --comments
gh pr checks $PR_NUMBER  # Note: CI runs on draft PRs too!
gh pr diff $PR_NUMBER

Document findings:

• Current CI status (even draft PRs have CI)
• Review comments to address
• Files changed
• Type of implementation (new program, bug fix, enhancement)

Phase 2: Enhanced Domain Validation

Run comprehensive validation using specialized agents:

Step 1: Domain-Specific Validation

Invoke implementation-validator to check:

• Federal/state jurisdiction separation
• Variable naming conventions and duplicates
• Hard-coded value patterns
• Performance optimization opportunities
• Documentation placement
• PolicyEngine-specific patterns

Step 2: Reference Validation

Invoke reference-validator to verify:

• All parameters have references
• References actually corroborate values
• Federal sources for federal params
• State sources for state params
• Specific citations, not generic links

Step 3: Implementation Validation

Invoke implementation-validator to check:

• No hard-coded values in formulas
• Complete implementations (no TODOs)
• Proper entity usage
• Correct formula patterns

Create a comprehensive checklist:

• Domain validation issues
• Reference validation issues
• Implementation issues
• Review comments to address
• CI failures to fix

Phase 3: Sequential Fix Application

CRITICAL: You MUST use agents for ALL fixes. DO NOT make direct edits yourself.

Based on issues found, invoke agents IN ORDER to avoid conflicts.

Why Sequential: Unlike initial implementation where we need isolation, PR fixes must be applied sequentially because:

• Each fix builds on the previous one
• Avoids merge conflicts
• Tests need to see the fixed implementation
• Documentation needs to reflect the final code

MANDATORY AGENT USAGE - Apply fixes in this exact order:

Step 1: Fix Domain & Parameter Issues

YOU MUST INVOKE THESE AGENTS - DO NOT FIX DIRECTLY:

1. First, invoke implementation-validator:
   "Scan all files in this PR and create a comprehensive list of all domain violations and implementation issues"

2. Then invoke parameter-architect (REQUIRED for ANY hard-coded values):
   "Design parameter structure for these hard-coded values found: [list all values]
    Create the YAML parameter files with proper federal/state separation"

3. Then invoke rules-engineer (REQUIRED for code changes):
   "Refactor all variables to use the new parameters created by parameter-architect.
    Fix all hard-coded values in: [list files]"

4. Then invoke reference-validator:
   "Add proper references to all new parameters created"

5. ONLY AFTER all agents complete: Commit changes

Step 2: Add Missing Tests (MANDATORY)

REQUIRED - Must generate tests even if none were failing:

1. Invoke edge-case-generator:
   "Generate boundary tests for all parameters created in Step 1.
    Test edge cases for: [list all new parameters]"

2. Invoke test-creator:
   "Create integration tests for the refactored Idaho LIHEAP implementation.
    Include tests for all new parameter files created."

3. VERIFY tests pass before committing
4. Commit test additions

Step 3: Enhance Documentation

1. documentation-enricher: Add examples and references to updated code
2. Commit documentation improvements

Step 4: Optimize Performance (if needed)

1. performance-optimizer: Vectorize and optimize calculations
2. Run tests to ensure no regressions
3. Commit optimizations

Step 5: Validate Integrations

1. cross-program-validator: Check benefit interactions
2. Fix any cliff effects or integration issues found
3. Commit integration fixes

Phase 4: Apply Fixes

For each issue identified:

1. Read current implementation

   gh pr checkout $PR_NUMBER
   

2. Apply agent-generated fixes

   • Use Edit/MultiEdit for targeted fixes
   • Preserve existing functionality
   • Add only what's needed

3. Verify fixes locally

   make test
   make format
   

Phase 5: Address Review Comments

For each GitHub comment:

1. Parse comment intent

   • Is it requesting a change?
   • Is it asking for clarification?
   • Is it pointing out an issue?

2. Generate response

   • If change requested: Apply fix and confirm
   • If clarification: Add documentation/comment
   • If issue: Fix and explain approach

3. Post response on GitHub

   gh pr comment $PR_NUMBER --body "Addressed: [explanation of fix]"
   

Phase 6: CI Validation

Invoke ci-fixer to ensure all checks pass:

1. Push fixes

   git add -A
   git commit -m "Address review comments
   
   - Fixed hard-coded values identified in review
   - Added missing tests for edge cases
   - Enhanced documentation with examples
   - Optimized performance issues
   
   Addresses comments from @reviewer"
   git push
   

2. Monitor CI

   gh pr checks $PR_NUMBER --watch
   

3. Fix any CI failures

   • Format issues: make format
   • Test failures: Fix with targeted agents
   • Lint issues: Apply corrections

Phase 7: Final Review & Summary

Invoke implementation-validator for final validation:

• All comments addressed?
• All tests passing?
• No regressions introduced?

Post summary comment:

gh pr comment $PR_NUMBER --body "## Summary of Changes

### Issues Addressed
✅ Fixed hard-coded values in [files]
✅ Added parameterization for [values]
✅ Enhanced test coverage (+X tests)
✅ Improved documentation
✅ All CI checks passing

### Review Comments Addressed
- @reviewer1: [Issue] → [Fix applied]
- @reviewer2: [Question] → [Clarification added]

### Ready for Re-Review
All identified issues have been addressed. The implementation now:
- Uses parameters for all configurable values
- Has comprehensive test coverage  
- Includes documentation with examples
- Passes all CI checks"

Command Options

Usage Examples

• /review-pr - Review PR for current branch
• /review-pr 6444 - Review PR #6444
• /review-pr "Idaho LIHEAP" - Search for and review PR by title/description

Quick Fix Mode

/review-pr [PR] --quick

• Only fix CI failures
• Skip comprehensive review
• Focus on getting checks green

Deep Review Mode

/review-pr [PR] --deep

• Run all validators
• Generate comprehensive tests
• Full documentation enhancement
• Cross-program validation

Comment Only Mode

/review-pr [PR] --comments-only

• Only address GitHub review comments
• Skip additional validation
• Faster turnaround

Success Metrics

The PR is ready when:

• ✅ All CI checks passing
• ✅ All review comments addressed
• ✅ No hard-coded values
• ✅ Comprehensive test coverage
• ✅ Documentation complete
• ✅ No performance issues

Common Review Patterns

"Hard-coded value" Comment

1. Identify the value
2. Create parameter with parameter-architect
3. Update implementation with rules-engineer
4. Add test with test-creator

"Missing test" Comment

1. Identify the scenario
2. Use edge-case-generator for boundaries
3. Use test-creator for integration tests
4. Verify with implementation-validator

"Needs documentation" Comment

1. Use documentation-enricher
2. Add calculation examples
3. Add regulatory references
4. Explain edge cases

"Performance issue" Comment

1. Use performance-optimizer
2. Vectorize operations
3. Remove redundant calculations
4. Test with large datasets

Error Handling

If agents produce conflicting fixes:

1. Prioritize fixes that address review comments
2. Ensure no regressions
3. Maintain backward compatibility
4. Document any tradeoffs

Pre-Flight Checklist

Before starting, confirm:

• I will NOT make direct edits (no Edit/Write/MultiEdit by coordinator)
• I will invoke agents for ALL changes
• I will wait for each agent to complete
• I will generate tests even if current tests pass
• I will commit after each agent phase

Start with determining which PR to review, then proceed to Phase 1: Analyze the PR and review comments.