ai-pull-request-handbook

PR Workflows & Processes

PR Workflow Diagram

The AI-Enhanced Pull Request workflow integrates human expertise with AI assistance and automated validation to ensure consistent, high-quality code changes.

High-Level Workflow

graph TD
    A[Developer Opens PR with Template] --> B[AI Gate Check]
    B --> C[Fix Gaps & Add Evidence]
    C --> D[CI/CD Validation]
    D --> E[Human Review]
    E --> F[Merge to Production]
    
    B --> G[AI Identifies Missing Requirements]
    G --> C
    
    D --> H[Automated Rule Enforcement]
    H --> I[Core Rules Validated]
    I --> E
    
    E --> J[Design & Risk Assessment]
    J --> K[Business Logic Review]
    K --> F

Detailed Workflow Steps

1. Developer Opens PR with Template

graph LR
    A[Feature Complete] --> B[Open PR]
    B --> C[Template Auto-Fills]
    C --> D[Fill Core Sections]
    D --> E[Add Evidence Links]

What happens:

2. AI Gate Check

graph LR
    A[PR Opened] --> B[AI Analyzes Content]
    B --> C[Load Relevant Rules]
    C --> D[Identify Gaps]
    D --> E[Generate Feedback]

What happens:

3. Fix Gaps & Add Evidence

graph LR
    A[AI Feedback] --> B[Developer Reviews]
    B --> C[Add Missing Tests]
    C --> D[Add Security Scans]
    D --> E[Add Observability]
    E --> F[Update PR Description]

What happens:

4. CI/CD Validation

graph LR
    A[PR Updated] --> B[GitHub Actions Trigger]
    B --> C[Validate Core Rules]
    C --> D[Check Evidence Links]
    D --> E[Run Security Scans]
    E --> F[Validate Templates]
    F --> G[Post Results]

What happens:

5. Human Review

graph LR
    A[CI Passes] --> B[Human Reviewer Assigned]
    B --> C[Review Design Quality]
    C --> D[Assess Business Logic]
    D --> E[Evaluate Risk]
    E --> F[Approve/Request Changes]

What happens:

6. Merge to Production

graph LR
    A[Review Approved] --> B[All Gates Satisfied]
    B --> C[Merge to Main]
    C --> D[Deploy to Production]
    D --> E[Monitor & Validate]

What happens:

Workflow Variations by Delivery Model

Trunk-Based Delivery Workflow

graph TD
    A[Small Feature Slice] --> B[Quick PR]
    B --> C[Fast AI Check]
    C --> D[Rapid CI Validation]
    D --> E[Focused Human Review]
    E --> F[Immediate Merge]
    F --> G[Continuous Deployment]
    
    style A fill:#e1f5fe
    style F fill:#c8e6c9
    style G fill:#c8e6c9

Characteristics:

Batch Release Workflow

graph TD
    A[Multiple Features] --> B[Individual PRs]
    B --> C[Standard Validation]
    C --> D[Feature Integration]
    D --> E[Release Planning]
    E --> F[Integrated Testing]
    F --> G[Staged Rollout]
    G --> H[Full Deployment]
    
    style A fill:#fff3e0
    style E fill:#fff3e0
    style F fill:#fff3e0
    style G fill:#fff3e0

Characteristics:

Role-Based Workflow Responsibilities

Developer Workflow

graph TD
    A[Start Feature] --> B[Implement Code]
    B --> C[Add Tests]
    C --> D[Open PR with Template]
    D --> E[Run AI Gate Check]
    E --> F[Fix AI Feedback]
    F --> G[Push Updates]
    G --> H[Address Review Comments]
    H --> I[Monitor Deployment]

Developer Responsibilities:

AI Assistant Workflow

graph TD
    A[PR Opened] --> B[Load Rule Files]
    B --> C[Analyze PR Content]
    C --> D[Identify Gaps]
    D --> E[Generate Feedback]
    E --> F[Validate Evidence]
    F --> G[Update Assessment]

AI Assistant Responsibilities:

CI/CD Workflow

graph TD
    A[PR Updated] --> B[Run Security Scans]
    B --> C[Execute Tests]
    C --> D[Validate Templates]
    D --> E[Check Evidence Links]
    E --> F[Generate Report]
    F --> G[Post Results]

CI/CD Responsibilities:

Human Reviewer Workflow

graph TD
    A[PR Ready] --> B[Review Design]
    B --> C[Assess Business Logic]
    C --> D[Evaluate Risk]
    D --> E[Check Maintainability]
    E --> F[Approve/Request Changes]

Human Reviewer Responsibilities:

Workflow Integration Points

GitHub Integration

graph LR
    A[GitHub PR] --> B[Template Auto-Fill]
    B --> C[AI Analysis]
    C --> D[CI/CD Validation]
    D --> E[Human Review]
    E --> F[Merge Protection]

GitHub Features Used:

AI Tool Integration

graph LR
    A[Claude/Copilot] --> B[Rule File Loading]
    B --> C[Content Analysis]
    C --> D[Gap Identification]
    D --> E[Feedback Generation]
    E --> F[Evidence Validation]

AI Tool Features:

CI/CD Integration

graph LR
    A[GitHub Actions] --> B[Security Scans]
    B --> C[Test Execution]
    C --> D[Template Validation]
    D --> E[Link Checking]
    E --> F[Report Generation]

CI/CD Features:

Workflow Optimization Strategies

Speed Optimization

graph LR
    A[Parallel Processing] --> B[Fast Feedback]
    B --> C[Early Validation]
    C --> D[Quick Iteration]
    D --> E[Reduced Cycle Time]

Strategies:

Quality Optimization

graph LR
    A[Comprehensive Rules] --> B[Thorough Validation]
    B --> C[Evidence-Based Reviews]
    C --> D[Consistent Quality]
    D --> E[Reduced Production Issues]

Strategies:

Collaboration Optimization

graph LR
    A[Clear Roles] --> B[Focused Reviews]
    B --> C[Reduced Friction]
    C --> D[Better Communication]
    D --> E[Improved Team Dynamics]

Strategies:

Workflow Monitoring & Metrics

Key Performance Indicators

graph TD
    A[Workflow Metrics] --> B[Cycle Time]
    A --> C[Quality Metrics]
    A --> D[Collaboration Metrics]
    
    B --> E[PR Creation to Merge]
    C --> F[Defect Rate]
    C --> G[Test Coverage]
    D --> H[Review Time]
    D --> I[Approval Rate]

Metrics to Track:

Monitoring Dashboard

graph LR
    A[Workflow Events] --> B[Metrics Collection]
    B --> C[Dashboard Updates]
    C --> D[Alert Generation]
    D --> E[Team Notifications]

Dashboard Components:

Workflow Troubleshooting

Common Issues and Solutions

Issue: AI Check Fails

Problem: AI assistant reports missing requirements Solution:

  1. Review AI feedback carefully
  2. Add missing evidence links
  3. Mark Conditional rules as N/A if appropriate
  4. Re-run AI check after updates

Issue: CI/CD Validation Fails

Problem: GitHub Actions reports rule violations Solution:

  1. Check CI logs for specific failures
  2. Ensure all Core rules are satisfied
  3. Verify evidence links are accessible
  4. Fix formatting issues in PR description

Issue: Human Review Takes Too Long

Problem: Reviewers spend too much time on checklist items Solution:

  1. Ensure AI and CI have validated all mechanical requirements
  2. Focus human review on design and business logic
  3. Provide clear evidence links for quality measures
  4. Train reviewers on new workflow

Issue: Merge Conflicts

Problem: Multiple PRs cause merge conflicts Solution:

  1. Keep PRs small and focused
  2. Coordinate with team on overlapping changes
  3. Use feature flags to avoid conflicts
  4. Implement proper branching strategy

Workflow Evolution

Continuous Improvement

graph LR
    A[Current Workflow] --> B[Collect Feedback]
    B --> C[Identify Improvements]
    C --> D[Implement Changes]
    D --> E[Measure Impact]
    E --> F[Iterate Process]

Improvement Process:

  1. Collect feedback from team
  2. Identify pain points and bottlenecks
  3. Implement workflow improvements
  4. Measure impact of changes
  5. Iterate based on results

Workflow Scaling

graph LR
    A[Small Team] --> B[Basic Workflow]
    B --> C[Growing Team]
    C --> D[Enhanced Workflow]
    D --> E[Large Organization]
    E --> F[Enterprise Workflow]

Scaling Considerations:

Next Steps

Ready to implement the workflow? Start with our User Guides for step-by-step instructions! 🚀

This site is open source. Improve this page.