BMAD-METHOD/samples/sample-custom-modules/cc-agents-commands/commands/pr.md

---
description: "Simple PR workflow helper - delegates to pr-workflow-manager agent"
argument-hint: "[action] [details] | Examples: 'create story 8.1', 'status', 'merge', 'fix CI', '--fast'"
allowed-tools: ["Task", "Bash", "SlashCommand"]
---

# PR Workflow Helper

Understand the user's PR request: "$ARGUMENTS"

## Fast Mode (--fast flag)

**When the user includes `--fast` in the arguments, skip all local validation:**

If "$ARGUMENTS" contains "--fast":
1. Stage all changes (`git add -A`)
2. Auto-generate a commit message based on the diff
3. Commit with `--no-verify` (skip pre-commit hooks)
4. Push with `--no-verify` (skip pre-push hooks)
5. Trust CI to catch any issues

**Use fast mode for:**
- Trusted changes (formatting, docs, small fixes)
- When you've already validated locally
- WIP commits to save progress

```bash
# Fast mode example
git add -A
git commit --no-verify -m "$(cat <<'EOF'
<auto-generated message>

🤖 Generated with [Claude Code](https://claude.ai/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"
git push --no-verify
```

## Default Behavior (No Arguments or "update")

**When the user runs `/pr` with no arguments, default to "update" with standard validation:**

If "$ARGUMENTS" is empty, "update", or doesn't contain "--fast":
1. Stage all changes (`git add -A`)
2. Auto-generate a commit message based on the diff
3. Commit normally (triggers pre-commit hooks - ~5s)
4. Push normally (triggers pre-push hooks - ~15s with parallel checks)

**The optimized hooks are now fast:**
- Pre-commit: <5s (formatting only)
- Pre-push: <15s (parallel lint + type check, no tests)
- CI: Full validation (tests run there)

## Pre-Push Conflict Check (CRITICAL)

**BEFORE any push operation, check for merge conflicts that block CI:**

```bash
# Check if current branch has a PR with merge conflicts
BRANCH=$(git branch --show-current)
PR_INFO=$(gh pr list --head "$BRANCH" --json number,mergeStateStatus -q '.[0]' 2>/dev/null)

if [[ -n "$PR_INFO" && "$PR_INFO" != "null" ]]; then
    MERGE_STATE=$(echo "$PR_INFO" | jq -r '.mergeStateStatus // "UNKNOWN"')
    PR_NUM=$(echo "$PR_INFO" | jq -r '.number')

    if [[ "$MERGE_STATE" == "DIRTY" ]]; then
        echo ""
        echo "⚠️  WARNING: PR #$PR_NUM has merge conflicts with base branch!"
        echo ""
        echo "🚫 GitHub Actions LIMITATION: pull_request events will NOT trigger"
        echo "   Jobs affected: E2E Tests, UAT Tests, Performance Benchmarks"
        echo "   Only push event jobs will run (Lint + Unit Tests)"
        echo ""
        echo "📋 To fix, sync with main first:"
        echo "   /pr sync     - Auto-merge main into your branch"
        echo "   Or manually: git fetch origin main && git merge origin/main"
        echo ""
        # Ask user if they want to sync or continue anyway
    fi
fi
```

**This check prevents the silent CI skipping issue where E2E/UAT tests don't run.**

## Sync Action (/pr sync)

If the user requests "sync", merge the base branch to resolve conflicts:

```bash
# Sync current branch with base (usually main)
BASE_BRANCH=$(gh pr view --json baseRefName -q '.baseRefName' 2>/dev/null || echo "main")
echo "🔄 Syncing with $BASE_BRANCH..."

git fetch origin "$BASE_BRANCH"
if git merge "origin/$BASE_BRANCH" --no-edit; then
    echo "✅ Synced successfully with $BASE_BRANCH"
    git push
else
    echo "⚠️  Merge conflicts detected. Please resolve manually:"
    git diff --name-only --diff-filter=U
fi
```

## Quick Status Check

If the user asks for "status" or similar, show a simple PR status:
```bash
# Enhanced status with merge state check
PR_DATA=$(gh pr view --json number,title,state,statusCheckRollup,mergeStateStatus 2>/dev/null)
if [[ -n "$PR_DATA" ]]; then
    echo "$PR_DATA" | jq '.'

    MERGE_STATE=$(echo "$PR_DATA" | jq -r '.mergeStateStatus')
    if [[ "$MERGE_STATE" == "DIRTY" ]]; then
        echo ""
        echo "⚠️  PR has merge conflicts - E2E/UAT/Benchmark CI jobs will NOT run!"
        echo "   Use '/pr sync' to resolve."
    fi
else
    echo "No PR for current branch"
fi
```

## Delegate Complex Operations

For any PR operation (create, update, merge, review, fix CI, etc.), delegate to the pr-workflow-manager agent:

```
Task(
    subagent_type="pr-workflow-manager",
    description="Handle PR request: ${ARGUMENTS:-update}",
    prompt="User requests: ${ARGUMENTS:-update}

    **FAST MODE:** If '--fast' is in the arguments:
    - Use --no-verify on commit AND push
    - Skip all local validation
    - Trust CI to catch issues

    **STANDARD MODE (default):** If '--fast' is NOT in arguments:
    - Use normal commit and push (hooks will run)
    - Pre-commit hooks are now fast (~5s)
    - Pre-push hooks are now fast (~15s, parallel, no tests)

    **IMPORTANT:** If the request is empty or 'update':
    - Stage ALL changes (git add -A)
    - Auto-generate a commit message based on the diff
    - Push to the current branch

    **CRITICAL - CONFLICT CHECK:** Before any push, check if PR has merge conflicts:
    - If mergeStateStatus == 'DIRTY', warn user that E2E/UAT/Benchmark CI jobs won't run
    - Offer to sync with main first

    Please handle this PR operation which may include:
    - **update** (DEFAULT): Stage all, commit, and push (with conflict check)
    - **--fast**: Skip all local validation (still warn about conflicts)
    - **sync**: Merge base branch into current branch to resolve conflicts
    - Creating PRs for stories
    - Checking PR status (include merge state warning if DIRTY)
    - Managing merges
    - Fixing CI failures (use /ci_orchestrate if needed)
    - Running quality reviews
    - Setting up auto-merge
    - Resolving conflicts
    - Cleaning up branches

    The pr-workflow-manager agent has full capability to handle all PR operations."
)
```

## Common Requests the Agent Handles

| Command | What it does |
|---------|--------------|
| `/pr` or `/pr update` | Stage all, commit, push (with conflict check + hooks ~20s) |
| `/pr --fast` | Stage all, commit, push (skip hooks ~5s, still warns about conflicts) |
| `/pr status` | Show PR status (includes merge conflict warning) |
| `/pr sync` | **NEW:** Merge base branch to resolve conflicts, enable full CI |
| `/pr create story 8.1` | Create PR for a story |
| `/pr merge` | Merge current PR |
| `/pr fix CI` | Delegate to /ci_orchestrate |

**Important:** If your PR has merge conflicts, E2E/UAT/Benchmark CI jobs will NOT run (GitHub Actions limitation). Use `/pr sync` to fix this.

The pr-workflow-manager agent will handle all complexity and coordination with other specialist agents as needed.

## Intelligent Chain Invocation

When the pr-workflow-manager reports CI failures, automatically invoke the CI orchestrator:

```bash
# After pr-workflow-manager completes, check if CI failures were detected
# The agent will report CI status in its output
if [[ "$AGENT_OUTPUT" =~ "CI.*fail" ]] || [[ "$AGENT_OUTPUT" =~ "Checks.*failing" ]]; then
    echo "CI failures detected. Invoking /ci_orchestrate to fix them..."
    SlashCommand(command="/ci_orchestrate --fix-all")
fi
```