PR Management

The PR Management script suite automates the full pull request lifecycle in Portfolio OS: from creating and configuring PRs, to analyzing quality, coordinating reviews, and keeping GitHub Projects in sync.

These scripts are designed to work together with the CI/CD workflows and multi-agent automation system documented elsewhere in the docs.

Overview

Folder Structure

scripts/pr-management/
├── automate-pr-unified.ps1          # Main PR automation entrypoint
├── configure-pr-auto.ps1            # Configure PR fields and project metadata
├── assign-pr-agents.ps1             # Assign PRs to agents / reviewers
├── configure-sprint-estimate.ps1    # Sprint estimation and capacity planning
├── get-pr-aliases.ps1               # PR alias and quick access utilities
├── test-pr-identification.ps1       # PR identification and validation
├── pr-monitor.ps1                   # Real-time PR monitoring
├── pr-analyzer.ps1                  # Comprehensive PR analysis
├── pr-quality-checker.ps1           # Quality checks and test orchestration
└── DEVELOPER_GUIDE.md               # In-depth implementation details

Common Requirements

• PowerShell 7+ (pwsh)
• GitHub CLI (gh) with repo, project, and workflow scopes
• Run from the repo root (portfolio-os)
• GITHUB_TOKEN available to scripts (typically provided by gh or CI)

Most scripts also support common flags:

Use Get-Help .\script-name.ps1 -Full for the authoritative parameter list.

automate-pr-unified.ps1

Path: scripts/pr-management/automate-pr-unified.ps1
Purpose: Unified automation entrypoint for PR analysis, CR-GPT integration, monitoring, and response handling.

Capabilities

• Analyze PRs and their code changes
• Coordinate with CR-GPT-based review automation
• Generate suggested responses to review feedback
• Monitor PR status and keep project fields updated

Key Parameters

Usage Examples

# Run complete PR automation (analysis + responses + monitoring)
.\scripts\pr-management\automate-pr-unified.ps1 `
  -PRNumber 150 `
  -Action all `
  -AutoFix

# Analyze a PR and CR-GPT feedback without modifying anything
.\scripts\pr-management\automate-pr-unified.ps1 `
  -PRNumber 150 `
  -Action analyze `
  -Detailed `
  -DryRun

# Generate suggested responses to existing review/CR-GPT comments
.\scripts\pr-management\automate-pr-unified.ps1 `
  -PRNumber 150 `
  -Action respond `
  -AutoFix

Common Issues

• "PR not found"

  • Check that -PRNumber is correct and the PR exists in the target repo.
  • Ensure you are in the portfolio-os repo directory.

• GitHub authentication errors

  • Run gh auth status and, if needed, gh auth login.
  • Make sure you have repo and project scopes.

• CR-GPT / AI service errors

  • Ensure any required API keys are configured (see core-utilities/manage-ai-services.ps1).
  • Review logs with -Verbose to see the underlying error.

configure-pr-auto.ps1

Path: scripts/pr-management/configure-pr-auto.ps1
Purpose: Configure PR fields and GitHub Project data consistently based on PR content.

Capabilities

• Set PR status, priority, size, app, and area
• Update project board fields for the PR’s associated issue(s)
• Apply labels and maintain naming conventions

Key Parameters

Usage Examples

# Configure a PR using defaults inferred from content
.\scripts\pr-management\configure-pr-auto.ps1 -PRNumber 150

# Configure a high-priority backend PR for the dashboard
.\scripts\pr-management\configure-pr-auto.ps1 `
  -PRNumber 150 `
  -Priority P0 `
  -Size L `
  -App "Dashboard" `
  -Area "Backend"

# Preview all configuration changes without applying them
.\scripts\pr-management\configure-pr-auto.ps1 `
  -PRNumber 150 `
  -DryRun

Troubleshooting

• If project fields are not updated, confirm the underlying GitHub Project IDs and field configuration in your environment matches what the script expects.

assign-pr-agents.ps1

Path: scripts/pr-management/assign-pr-agents.ps1
Purpose: Assign PRs to agents or reviewers based on workload and domain.

Capabilities

• Distribute PRs across agents using workload and priority information
• Generate assignment reports for review
• Support dry-run preview before applying assignments

Key Parameters

Usage Examples

# Propose assignments for all PRs in a project (preview only)
.\scripts\pr-management\assign-pr-agents.ps1 `
  -ProjectNumber "20" `
  -Owner "jschibelli" `
  -DryRun

# Apply assignments and export a markdown report
.\scripts\pr-management\assign-pr-agents.ps1 `
  -ProjectNumber "20" `
  -Owner "jschibelli" `
  -ExportTo "assignment-report.md"

pr-monitor.ps1

Path: scripts/pr-management/pr-monitor.ps1
Purpose: Monitor PRs in real time and export status reports.

Key Parameters

Usage Examples

# Monitor open PRs once
.\scripts\pr-management\pr-monitor.ps1 -Filter open

# Watch open PRs with CR-GPT-related activity every 30 seconds
.\scripts\pr-management\pr-monitor.ps1 `
  -Filter open `
  -WatchMode `
  -Interval 30 `
  -IncludeCRGPT

# Generate a snapshot report of open PRs
.\scripts\pr-management\pr-monitor.ps1 `
  -Filter open `
  -ExportTo "pr-report.json"

pr-analyzer.ps1

Path: scripts/pr-management/pr-analyzer.ps1
Purpose: Perform detailed PR analysis (scope, risk, complexity, and review status).

Analysis Modes

• comprehensive – Full PR analysis
• security – Security-focused checks
• performance – Performance-related impact
• complexity – Code complexity and review effort
• review – Review status, feedback, and blockers
• changes – Focus on change impact and touched areas

Key Parameters

Usage Examples

# Run full analysis with detailed console output
.\scripts\pr-management\pr-analyzer.ps1 `
  -PRNumber 150 `
  -Analysis comprehensive `
  -Detailed

# Generate a security analysis report
.\scripts\pr-management\pr-analyzer.ps1 `
  -PRNumber 150 `
  -Analysis security `
  -ExportTo "security-report.json"

pr-quality-checker.ps1

Path: scripts/pr-management/pr-quality-checker.ps1
Purpose: Run automated quality checks and tests for a given PR.

Check Types

• all – Run the full suite of checks
• linting – Lint and formatting
• formatting – Formatting only
• security – Security scanning
• performance – Performance-related checks
• documentation – Documentation completeness
• tests – Run associated test suites

Key Parameters

Usage Examples

# Run full quality check with auto-fix
.\scripts\pr-management\pr-quality-checker.ps1 `
  -PRNumber 150 `
  -Checks all `
  -AutoFix

# Run security + performance checks and export report
.\scripts\pr-management\pr-quality-checker.ps1 `
  -PRNumber 150 `
  -Checks security,performance `
  -ExportTo "quality-report.json"

# Focus on tests and documentation
.\scripts\pr-management\pr-quality-checker.ps1 `
  -PRNumber 150 `
  -Checks tests,documentation `
  -RunTests

Supporting Utilities

In addition to the main automation scripts, the PR Management folder includes:

• configure-sprint-estimate.ps1 – Manage sprint estimates and capacity for PR-related work.
• get-pr-aliases.ps1 – Create and use human-friendly aliases for PRs.
• test-pr-identification.ps1 – Validate that PR metadata and identification logic works as expected.

Each of these scripts follows the same conventions as above: use Get-Help for the complete parameter list and -DryRun + -Verbose during first use.

Troubleshooting & Best Practices

• Always start with -DryRun when integrating a script into CI/CD or new workflows.
• Check gh auth status before running scripts that interact with GitHub.
• Prefer smaller, focused PRs – the automation works best when changes are well scoped.
• Use the CI/CD workflows in combination with these scripts to enforce quality gates on every PR.

For deeper architectural context and advanced usage patterns, see the in-repo scripts/pr-management/DEVELOPER_GUIDE.md.