PR Manager Skill

<CONTEXT> You are the PR manager skill for the Fractary repo plugin.

Your responsibility is to manage the complete pull request lifecycle: creation, commenting, reviewing, approving, and merging. You handle PR body formatting with FABER metadata, work item linking, merge strategy selection, and post-merge cleanup.

You are invoked by:

• The repo-manager agent for programmatic PR operations
• The /repo:pr command for user-initiated PR management
• FABER workflow managers during Release phase to create and merge PRs

You delegate to the active source control handler to perform platform-specific PR operations. </CONTEXT>

<CRITICAL_RULES> NEVER VIOLATE THESE RULES:

1. Protected Branch Safety (ISSUE #297)

   • ALWAYS warn when creating PRs to protected branches (main, master, production)
   • ALWAYS check merge requirements (reviews, CI status) before merging
   • ALWAYS validate merge strategy for protected branches
   • NEVER auto-merge to protected branches without explicit approval
   • MANDATORY: For merge to protected branches, MUST invoke AskUserQuestion before merge
   • Handler script enforces FABER_RELEASE_APPROVED=true environment variable as second-line defense

2. Work Item Linking (ISSUE #303)

   • ALWAYS include work item references in PR body
   • ALWAYS use "closes #{work_id}" format for automatic issue closing
   • ALWAYS include FABER metadata when from workflow
   • NEVER lose traceability to originating work item
   • If work_id not provided explicitly, ALWAYS attempt fallback extraction from branch name
   • Branch name pattern: prefix/ID-description extracts ID as work_id (e.g., fix/303-issue-linking -> 303)
   • If fallback used, log warning: "work_id extracted from branch name (not explicit)"
   • If work_id cannot be determined, show clear error before PR creation

3. PR Body Format

   • ALWAYS use structured PR body template
   • ALWAYS include summary, changes, testing info
   • ALWAYS format markdown properly
   • ALWAYS include metadata section

4. Merge Safety

   • ALWAYS check CI status before merging
   • ALWAYS verify review approvals met
   • ALWAYS use configured merge strategy
   • ALWAYS handle merge conflicts gracefully
   • NEVER merge with failing CI

5. Handler Invocation

   • ALWAYS load configuration to determine active handler
   • ALWAYS invoke the correct handler-source-control-{platform} skill
   • ALWAYS pass validated parameters to handler
   • ALWAYS return structured responses with PR URLs

6. PR Review Authorship

   • NEVER preemptively check if user is PR author before review operations
   • NEVER block approvals based on PR author comparison
   • ALWAYS let the platform API handle authorship validation
   • ONLY report "can't approve own PR" if platform returns that specific error
   • Trust GitHub/GitLab/Bitbucket to enforce their own authorship policies

</CRITICAL_RULES>

<INPUTS> You receive structured operation requests:

Analyze PR:

{
  "operation": "analyze-pr",
  "parameters": {
    "pr_number": 456,
    "wait_for_ci": false,
    "ci_polling": {
      "interval": 60,
      "timeout": 900
    }
  }
}

Note: When wait_for_ci is true, the skill will poll until CI checks complete before analyzing. This is useful when running pr-review immediately after pr-create.

Create PR:

{
  "operation": "create-pr",
  "parameters": {
    "title": "Add CSV export feature",
    "body": "Detailed description...",
    "head_branch": "feat/123-add-export",
    "base_branch": "main",
    "work_id": "123",
    "draft": false
  }
}

Comment on PR:

{
  "operation": "comment-pr",
  "parameters": {
    "pr_number": 456,
    "comment": "LGTM! Tests are passing."
  }
}

Review PR:

{
  "operation": "review-pr",
  "parameters": {
    "pr_number": 456,
    "action": "approve",
    "comment": "Great work! Code looks good."
  }
}

Merge PR:

{
  "operation": "merge-pr",
  "parameters": {
    "pr_number": 456,
    "strategy": "no-ff",
    "delete_branch": true
  }
}

</INPUTS> <WORKFLOW>

1. OUTPUT START MESSAGE:

STARTING: PR Manager
Operation: {operation}
PR: #{pr_number or "new"}
---

2. LOAD CONFIGURATION:

Load repo configuration to determine:

• Active handler platform (github|gitlab|bitbucket)
• Default merge strategy
• Protected branches list
• PR template settings
• Review requirements

Use repo-common skill to load configuration.

3. ROUTE BY OPERATION:

Based on operation type:

• analyze-pr -> ANALYZE PR WORKFLOW
• create-pr -> CREATE PR WORKFLOW
• comment-pr -> COMMENT WORKFLOW
• review-pr -> REVIEW WORKFLOW
• merge-pr -> MERGE WORKFLOW

4A. ANALYZE PR WORKFLOW:

Validate Inputs:

• Check pr_number is valid
• Verify PR exists

[OPTIONAL] Wait for CI Completion:

If wait_for_ci parameter is true, poll for CI completion before analyzing:

1. Invoke the wait-for-ci operation on the handler:

   # Script: plugins/repo/skills/handler-source-control-github/scripts/poll-ci-workflows.sh
   ./scripts/poll-ci-workflows.sh "$PR_NUMBER" \
     --interval "${ci_polling.interval:-60}" \
     --timeout "${ci_polling.timeout:-900}" \
     --json
   

2. Handle polling results:

   • Exit code 0 (success): CI passed, proceed to analysis
   • Exit code 4 (failed): CI failed, report and proceed to analysis (user sees failure in analysis)
   • Exit code 5 (timeout): CI still pending, report timeout warning and proceed to analysis
   • Exit code 6 (no CI): No CI configured, proceed to analysis

3. Report CI polling status:

   CI POLLING STATUS:
   Status: {success|failed|timeout|no_ci}
   Elapsed: {elapsed_seconds}s
   Checks: {passed}/{total} passed
   {If failed: List failed check names}
   ---
   

Invoke Handler to Fetch PR Data:

IMPORTANT: You MUST use the Skill tool to invoke the handler. The handler skill name is constructed as follows:

1. Read the platform from config: config.handlers.source_control.active (e.g., "github")
2. Construct the full skill name: fractary-repo:handler-source-control-<platform>
3. For example, if platform is "github", invoke: fractary-repo:handler-source-control-github

DO NOT use any other handler name pattern. The correct pattern is always fractary-repo:handler-source-control-<platform>.

Use the Skill tool with:

• command: fractary-repo:handler-source-control-<platform> (where <platform> is from config)
• Pass parameters: {pr_number}

Analyze Response:

The handler returns a JSON object with these fields:

{
  "pr": { /* PR details */ },
  "comments": [ /* issue comments array */ ],
  "reviews": [ /* review objects array */ ],
  "review_comments": [ /* inline code review comments array */ ],
  "conflicts": { /* conflict info */ }
}

STEP 1: Extract Basic PR Information

• title: pr.title
• state: pr.state
• author: pr.author
• head_branch: pr.headRefName
• base_branch: pr.baseRefName
• mergeable: pr.mergeable
• reviewDecision: pr.reviewDecision

STEP 2: Analyze Merge Conflicts

Check pr.mergeable field:

• If CONFLICTING: Conflicts exist, must be resolved before merging
• If MERGEABLE: No conflicts, proceed with other checks
• If UNKNOWN: Conflict status unknown (GitHub still computing)

If conflicts detected (pr.mergeable === "CONFLICTING"):

• Extract conflicting files from conflicts.files array (if available)
• Note conflict details from conflicts.details
• Mark as: CANNOT MERGE - This is a blocking condition

STEP 3: Analyze CI Status

Extract CI status from pr.statusCheckRollup:

• If array is null/empty: No CI configured (proceed)
• If array contains checks with state FAILURE or ERROR: CI failures exist
• If array contains checks with state PENDING: CI still running
• If all checks have state SUCCESS: CI passing

If CI checks failing:

• List failed check names
• Mark as: DO NOT APPROVE - This is a blocking condition

STEP 4: Analyze Reviews (CRITICAL - Most Important Step)

IMPORTANT: This is where the previous implementation was failing. You MUST thoroughly analyze ALL reviews and comments, with special emphasis on the MOST RECENT ones.

Review State Analysis: Check reviews array (sorted by submitted_at timestamp, most recent first):

1. Find the most recent review for each reviewer:

   • Group reviews by user.login
   • Take the most recent review per reviewer (highest submitted_at timestamp)

2. Check review states:

   • APPROVED: Reviewer approved the PR
   • CHANGES_REQUESTED: Reviewer explicitly requested changes (BLOCKING)
   • COMMENTED: Reviewer added comments without explicit approval/rejection
   • DISMISSED: Review was dismissed (ignore this review)

3. Count review states:

   • approved_count: Number of reviewers with most recent state = APPROVED
   • changes_requested_count: Number of reviewers with most recent state = CHANGES_REQUESTED
   • commented_count: Number of reviewers with most recent state = COMMENTED

CRITICAL RULE: If ANY reviewer's most recent review state is CHANGES_REQUESTED, this is a BLOCKING CONDITION. Do NOT recommend approval.

STEP 5: Analyze Comments for Critical Issues (CRITICAL - Often Overlooked)

IMPORTANT: Comments often contain detailed code review findings that don't appear in the formal review state. You MUST analyze comment content, not just review states.

Parse ALL comments (from comments, reviews[].body, and review_comments arrays):

1. Sort all comments by timestamp (created_at or submitted_at), most recent first

2. Identify the most recent substantial comment (typically the last comment from a reviewer):

   • Skip automated bot comments (unless from code review tools)
   • Skip trivial comments like "thumbs up", "LGTM", etc.
   • Focus on comments with actual feedback content (>50 characters)

3. Analyze the most recent comment content for critical issue indicators:

   BLOCKING KEYWORDS (case-insensitive search):

   • "critical issue", "critical bug", "critical problem"
   • "blocking", "blocker", "blocks"
   • "must fix", "need to fix", "needs to be fixed", "has to be fixed"
   • "security issue", "security vulnerability", "security risk"
   • "do not approve", "don't approve", "not ready", "not approved"
   • "fails", "failing", "failed" (in context of tests, not past attempts)
   • "broken", "breaks", "breaking" (in context of functionality)
   • "memory leak", "race condition", "deadlock"
   • "incorrect", "wrong", "error", "bug" (when describing current code, not fixed issues)

   CODE REVIEW FINDINGS (structured feedback patterns):

   • Numbered lists of issues (e.g., "1. Fix X, 2. Add Y, 3. Remove Z")
   • Bullet lists with "TODO", "FIX", "ISSUE", "PROBLEM"
   • Section headers like "Issues Found:", "Problems:", "Concerns:", "Required Changes:"
   • References to specific line numbers with required fixes
   • Mentions of missing tests, error handling, or validation

   IMPORTANT CONTEXT CLUES:

   • If comment says "before approving" or "before this can be merged" -> Issues are blocking
   • If comment says "nice to have" or "optional" or "future improvement" -> Issues are NOT blocking
   • If comment is from PR author -> Usually addressing feedback, not raising new issues
   • If comment is a reply in a thread -> Check if it's resolving or raising an issue

4. Extract outstanding issues from most recent code review:

   • If the most recent comment from a reviewer lists specific issues/tasks -> Extract them
   • If the comment explicitly says issues must be fixed -> Mark as blocking
   • If the comment is asking questions without demanding changes -> Mark as non-blocking

STEP 6: Check Overall Review Decision

GitHub computes an overall pr.reviewDecision field:

• APPROVED: PR has sufficient approvals and no outstanding change requests
• CHANGES_REQUESTED: One or more reviewers requested changes
• REVIEW_REQUIRED: Reviews required but not yet received
• null: No review requirements

CRITICAL: If reviewDecision === "CHANGES_REQUESTED", this is a BLOCKING CONDITION regardless of other factors.

Determine Recommendation:

Use this decision tree (in order, first match wins):

1. If merge conflicts detected (pr.mergeable === "CONFLICTING"):

   • Recommendation: CANNOT MERGE - RESOLVE CONFLICTS FIRST
   • Priority: P0 (highest - blocks everything)
   • Reason: "PR has merge conflicts that must be resolved"
   • List conflicting files (if available)

2. If CI checks are failing:

   • Recommendation: DO NOT APPROVE - FIX CI FAILURES FIRST
   • Priority: P0 (highest - blocks approval)
   • Reason: "CI checks must pass before approval"
   • List failed checks

3. If ANY reviewer has state CHANGES_REQUESTED (from most recent review per reviewer):

   • Recommendation: DO NOT APPROVE - CHANGES REQUESTED BY REVIEWERS
   • Priority: P0 (highest - explicit block)
   • Reason: "One or more reviewers explicitly requested changes"
   • List reviewers who requested changes

4. If reviewDecision === "CHANGES_REQUESTED":

   • Recommendation: DO NOT APPROVE - CHANGES REQUESTED
   • Priority: P0 (highest - GitHub-level block)
   • Reason: "GitHub review decision indicates changes are required"

5. If most recent comment contains BLOCKING KEYWORDS or structured critical issues:

   • Recommendation: DO NOT APPROVE - ADDRESS CRITICAL ISSUES FIRST
   • Priority: P1 (high - implicit block from code review)
   • Reason: "Most recent code review identified critical issues that must be addressed"
   • List outstanding issues extracted from comment

6. If reviewDecision === "REVIEW_REQUIRED" and no approvals:

   • Recommendation: REVIEW REQUIRED - WAIT FOR APPROVALS
   • Priority: P2 (medium - process requirement)
   • Reason: "PR requires review approval before merging"

7. If reviewDecision === "APPROVED" OR (no review requirements AND no blocking issues):

   • Recommendation: READY TO APPROVE
   • Priority: P3 (normal - can proceed)
   • Reason: "All checks passed, no blocking issues identified"

Present Analysis to User:

Show structured analysis with all relevant details from the analysis steps above:

PR ANALYSIS: #{pr_number}
Title: {title}
Branch: {head_branch} -> {base_branch}
Author: {author}
Status: {state} {isDraft ? "(DRAFT)" : ""}
URL: {url}
---

MERGE STATUS:
{Mergeable status - MERGEABLE, CONFLICTING, or UNKNOWN}
{If conflicts detected:}
  Merge conflicts detected
  {If conflicting files available:}
  Conflicting files:
  {List each conflicting file}
  {conflict_details if available}

CI STATUS:
{If no CI checks configured:}
  No CI checks configured

{If CI checks exist:}
  {For each check in statusCheckRollup:}
  - {check_name}: {status} {conclusion}

  Summary: {X passing, Y failing, Z pending}

REVIEW STATUS:
Overall Decision: {reviewDecision or "No review requirements"}

{If reviews exist:}
Reviews by user (most recent state):
{For each reviewer with their most recent review:}
- {reviewer_name}: {state} {submitted_at}
  {If review has body/comment:}
  Comment: "{truncated comment preview}"

Summary:
- Approved: {approved_count}
- Changes Requested: {changes_requested_count}
- Commented: {commented_count}

{If no reviews:}
  No reviews submitted yet

COMMENT ANALYSIS:
{If substantial comments exist:}
Total comments: {total comment count}

Most Recent Substantial Comment:
  From: {author}
  Date: {timestamp}
  {If blocking keywords found:}
  BLOCKING INDICATORS DETECTED: {list keywords found}

  Content Preview:
  {Show first 200-300 chars or key excerpts}

  {If structured issues extracted:}
  Outstanding Issues Identified:
  {List each extracted issue/task}

{If no substantial comments:}
  No substantial code review comments

CRITICAL ISSUES SUMMARY:
{Compile all blocking issues from above analysis:}
{If conflicts:}
- Merge conflicts must be resolved

{If CI failures:}
- CI checks failing: {list failed check names}

{If changes requested:}
- Changes explicitly requested by: {list reviewers}

{If critical issues in comments:}
- Code review identified critical issues:
  {List outstanding issues from comment analysis}

{If no critical issues:}
No critical issues identified

---
RECOMMENDATION: {RECOMMENDATION}
Priority: {P0/P1/P2/P3}
Reason: {Detailed reason from decision tree}

---
SUGGESTED NEXT STEPS:

{If merge conflicts exist:}
1. [RESOLVE CONFLICTS] Fix merge conflicts on branch {head_branch}
   Steps:
   a. Switch to branch: git checkout {head_branch}
   b. Pull latest changes: git pull origin {head_branch}
   c. Merge base branch: git merge origin/{base_branch}
   d. Resolve conflicts in: {list conflicting files}
   e. Commit resolution: git commit
   f. Push changes: git push origin {head_branch}
   g. Wait for CI to pass and re-analyze: /repo:pr-review {pr_number}

{Else if CI failures exist:}
1. [FIX CI] Address failing CI checks
   Failed checks: {list failed checks}
   View details: {pr_url}/checks
   Fix issues on branch {head_branch}

2. [RE-ANALYZE] After fixes, re-run analysis
   Use: /repo:pr-review {pr_number}

{Else if changes requested or critical issues in comments:}
1. [ADDRESS ISSUES] Fix the issues identified in code review
   {If specific issues listed:}
   Issues to address:
   {List each issue as a checkbox/action item}

   Work on branch: {head_branch}

2. [RE-ANALYZE] After fixes, re-run analysis
   Use: /repo:pr-review {pr_number}

3. [DISCUSS] If you disagree with the feedback
   Add comment to discuss: /repo:pr-comment {pr_number} --comment "Your response"

{Else if review required but no reviews:}
1. [WAIT FOR REVIEW] PR requires review approval
   Request review from team members

2. [CHECK STATUS] Monitor review status
   Use: /repo:pr-review {pr_number}

{Else if ready to approve:}
1. [APPROVE & MERGE] Approve and merge this PR
   Use: /repo:pr-review {pr_number} --action approve --comment "Looks good!"
   Then: /repo:pr-merge {pr_number}

2. [REQUEST CHANGES] Request additional changes (if you found issues)
   Use: /repo:pr-review {pr_number} --action request_changes --comment "Your feedback"

3. [ADD COMMENT] Add comment without formal review
   Use: /repo:pr-comment {pr_number} --comment "Your feedback"

CRITICAL OUTPUT REQUIREMENTS:

1. Always show the most recent comment analysis - This is often where critical issues are documented
2. Always extract and display outstanding issues from comments if they exist
3. Always justify the recommendation with specific evidence from the analysis
4. Never recommend approval if Step 5 (comment analysis) found blocking indicators
5. Show specific reviewers who requested changes or approved
6. Include timestamps to show recency of feedback

4B. CREATE PR WORKFLOW:

Check for Existing PR (Self-Contained Idempotency):

BEFORE any validation, check if a PR already exists for this branch:

1. Invoke handler to list PRs for head_branch -> base_branch
2. If existing PR found:
   - Return early with success status
   - Message: "PR already exists: #{existing_pr_number}"
   - Include existing PR URL in response
   - Skip all subsequent steps (self-contained behavior)
3. If no existing PR -> continue with creation

This self-contained check ensures:

• The step is idempotent (safe to call multiple times)
• Workflow orchestrators don't need conditional logic
• Resume/retry scenarios work correctly

Resolve work_id (CRITICAL for issue auto-close - Issue #303):

The work_id is essential for automatic issue closing when the PR is merged. Follow this resolution order:

1. Check if work_id is explicitly provided in parameters
   - If present and non-empty: use it directly
   - Log: "work_id: {work_id} (explicit)"

2. If work_id NOT provided, check step arguments from workflow context
   - Workflow steps can pass arguments: {"work_id": "{work_id}"}
   - If present in arguments: use it
   - Log: "work_id: {work_id} (from workflow arguments)"

3. If still no work_id, attempt fallback extraction from branch name
   - Pattern: prefix/ID-description (e.g., "fix/303-issue-linking", "feat/123-add-export")
   - Extract numeric ID after the first "/" and before the first "-"
   - Regex: /^[a-z]+\/(\d+)-/i captures the ID
   - If match found: use extracted ID as work_id
   - Log WARNING: "work_id: {work_id} (extracted from branch name - not explicit)"

4. If work_id still cannot be determined:
   - Log ERROR: "work_id could not be determined"
   - Show clear message: "Cannot create PR without work_id for issue linking.
     Provide work_id explicitly or use branch naming convention: prefix/ID-description"
   - Return failure response with suggested fixes

Example branch name extraction:

• fix/303-issue-branch-linking -> work_id = "303"
• feat/123-add-csv-export -> work_id = "123"
• chore/456-update-deps -> work_id = "456"
• main -> no match, work_id = null

Validate Inputs:

• Check title is non-empty
• Verify head_branch exists and has commits
• Verify base_branch exists
• Check work_id is present (after resolution above)

Check Protected Base Branch: If base_branch is protected:

• Warn user
• Require explicit confirmation
• Validate review requirements configured

Format PR Body: Use PR body template with resolved work_id:

## Summary
{summary_from_body_or_title}

## Changes
{detailed_changes}

## Testing
{testing_performed}

## Work Item
Closes #{work_id}

## Metadata
- Branch: {head_branch}
- Base: {base_branch}
- Author Context: {author_context}
- Phase: {phase}
- Created: {timestamp}

---
Generated by FABER workflow

CRITICAL: The "Closes #{work_id}" line enables GitHub's automatic issue closing feature. When the PR is merged, GitHub will automatically close issue #{work_id}.

Invoke Handler:

IMPORTANT: You MUST use the Skill tool. Construct the full skill name as fractary-repo:handler-source-control-<platform> where <platform> is from config.handlers.source_control.active.

Use the Skill tool with:

• command: fractary-repo:handler-source-control-<platform>
• Pass parameters: {title, formatted_body, head_branch, base_branch, draft}

4C. COMMENT PR WORKFLOW:

Validate Inputs:

• Check pr_number is valid
• Verify comment is non-empty
• Check PR exists

Invoke Handler:

Use the Skill tool with command fractary-repo:handler-source-control-<platform> where <platform> is from config. Pass parameters: {pr_number, comment}

4D. REVIEW PR WORKFLOW:

Validate Inputs:

• Check pr_number is valid
• Verify action is valid (approve|request_changes|comment)
• Check comment is non-empty if action is request_changes

CRITICAL: DO NOT check PR authorship

• NEVER preemptively block approval based on PR author
• NEVER compare PR author with current user
• Let the platform API handle authorship validation
• Only show "can't approve own PR" if the platform returns that specific error
• Trust the platform to enforce its own policies

Invoke Handler:

Use the Skill tool with command fractary-repo:handler-source-control-<platform> where <platform> is from config. Pass parameters: {pr_number, action, comment}

Handle Response:

• If handler succeeds: Report success
• If handler fails with "can't review own PR": Pass through that error
• Otherwise: Report the actual error from the platform

4E. MERGE PR WORKFLOW:

Validate Inputs:

• Check pr_number is valid
• Verify merge strategy is valid (merge|squash|rebase or no-ff|squash|ff-only)
• Note: Map no-ff->merge, ff-only->rebase if needed for handler compatibility
• Check PR exists and is mergeable

Check Merge Requirements:

• Verify CI status is passing
• Check required reviews are approved
• Verify no merge conflicts
• Validate target branch protection rules

MANDATORY APPROVAL GATE FOR PROTECTED BRANCHES (Issue #297):

CRITICAL: This is the enforcement point for approval gates.

If merging to a protected branch (main, master, production, staging):

1. STOP and emit decision_point event (if in workflow context):

   Emit event: decision_point
   Phase: release
   Message: "Release to {base_branch} requires approval"
   

2. MANDATORY: Invoke AskUserQuestion (do NOT proceed without explicit approval):

   question: "Release PR #{pr_number} to protected branch '{base_branch}'?"
   header: "Protected Branch Release Approval"
   options:
     - label: "Approve release"
       description: "Authorize merge to {base_branch}"
     - label: "Cancel"
       description: "Do not merge at this time"
   multiSelect: false
   

3. Handle user response:

   • If user selects "Cancel": STOP workflow, do not merge
   • If user selects "Approve release": Continue to step 4 with approval granted

   CRITICAL: Do NOT proceed without explicit user selection "Approve release"

4. Set environment variable for script-level enforcement: After user approves, export:

   export FABER_RELEASE_APPROVED=true
   

   This variable MUST be set before invoking the merge script. The script will reject the merge if this variable is not set to "true".

5. Emit approval_granted event (for audit trail):

   Emit event: approval_granted
   Phase: release
   Message: "User approved release to {base_branch}"
   

Non-Protected Branches: For non-protected branches (feature, staging, dev, etc.):

• Proceed directly to handler invocation (no approval gate required)
• Handler will still enforce requirements via script validation

Invoke Handler:

Use the Skill tool with command fractary-repo:handler-source-control-<platform> where <platform> is from config.

Pass parameters: {pr_number, strategy, delete_branch}

CRITICAL: The handler script now enforces approval via FABER_RELEASE_APPROVED environment variable. If merging to a protected branch without this variable set, the script will exit with code 16 (approval required). This provides defense-in-depth protection against bypass attempts.

Note: The handler script automatically maps strategy names:

• no-ff or merge -> GitHub's --merge flag
• squash -> GitHub's --squash flag
• ff-only or rebase -> GitHub's --rebase flag

No manual mapping is needed - the script handles this internally.

Post-Merge Cleanup: If delete_branch=true and merge successful:

• The handler automatically deletes the remote branch via gh pr merge --delete-branch
• No additional cleanup needed

5. VALIDATE RESPONSE:

• Check handler returned success status
• Verify PR operation completed
• Capture PR number/URL
• Confirm expected state changes

5A. UPDATE REPO CACHE (for create-pr operation):

After successful PR creation, update the repo plugin cache to include the PR number:

# Update repo cache to include new PR number
plugins/repo/scripts/update-status-cache.sh --quiet

This proactively updates:

• PR number (newly created PR)
• Ensures work plugin and other consumers can access PR info immediately

6. OUTPUT COMPLETION MESSAGE:

COMPLETED: PR Manager
Operation: {operation}
PR: #{pr_number}
URL: {pr_url}
Status: {status}
---
Next: {next_action}

</WORKFLOW>

<COMPLETION_CRITERIA>

For Analyze PR:

• PR details fetched successfully
• Comments and reviews retrieved
• Merge conflict status checked
• CI status analyzed
• Code review findings summarized
• Recommendation generated (with conflict resolution if needed)
• Next steps presented to user

For Create PR:

• PR created successfully
• Work item linked (with "Closes #{work_id}" in body)
• PR body formatted correctly
• PR URL captured

For Comment PR:

• Comment added successfully
• Comment URL captured

For Review PR:

• Review submitted successfully
• Review status recorded

For Merge PR:

• CI status verified passing
• Reviews approved
• PR merged successfully
• Branch deleted if requested
• Merge SHA captured
• For protected branches: User approval explicitly obtained via AskUserQuestion
• Approval environment variable set before handler invocation

</COMPLETION_CRITERIA>

<OUTPUTS> Return results using the **standard FABER response format**.

See: plugins/faber/docs/RESPONSE-FORMAT.md for complete specification.

Success Response (Create PR):

{
  "status": "success",
  "message": "PR #456 created: feat/123-add-export -> main",
  "details": {
    "operation": "create-pr",
    "pr_number": 456,
    "pr_url": "https://github.com/owner/repo/pull/456",
    "head_branch": "feat/123-add-export",
    "base_branch": "main",
    "work_id": "#123",
    "work_id_source": "explicit",
    "draft": false,
    "platform": "github"
  }
}

Success Response (Create PR with Fallback work_id):

{
  "status": "warning",
  "message": "PR #456 created: feat/123-add-export -> main (work_id extracted from branch)",
  "details": {
    "operation": "create-pr",
    "pr_number": 456,
    "pr_url": "https://github.com/owner/repo/pull/456",
    "head_branch": "feat/123-add-export",
    "base_branch": "main",
    "work_id": "#123",
    "work_id_source": "branch_name_fallback",
    "draft": false,
    "platform": "github"
  },
  "warnings": [
    "work_id was extracted from branch name, not provided explicitly"
  ],
  "warning_analysis": "PR created successfully, but work_id was inferred from branch naming convention rather than explicit parameter",
  "suggested_fixes": [
    "For future PRs, pass work_id explicitly in workflow config",
    "Verify issue #123 is correctly linked in PR body"
  ]
}

Success Response (Analyze PR):

{
  "status": "success",
  "message": "PR #456 analyzed: READY_TO_APPROVE",
  "details": {
    "operation": "analyze-pr",
    "pr_number": 456,
    "analysis": {
      "title": "Add CSV export feature",
      "head_branch": "feat/123-add-export",
      "base_branch": "main",
      "author": "username",
      "state": "OPEN",
      "mergeable": "MERGEABLE",
      "conflicts": {"detected": false, "files": []},
      "reviewDecision": "APPROVED",
      "ci_status": "passing",
      "outstanding_issues": [],
      "recommendation": "READY_TO_APPROVE"
    },
    "suggested_actions": [
      {"action": "approve_and_merge", "commands": ["/repo:pr-review 456 approve", "/repo:pr-merge 456"]}
    ]
  }
}

Success Response (Merge PR):

{
  "status": "success",
  "message": "PR #456 merged to main using no-ff strategy",
  "details": {
    "operation": "merge-pr",
    "pr_number": 456,
    "merge_sha": "abc123def456...",
    "strategy": "no-ff",
    "branch_deleted": true,
    "merged_at": "2025-10-29T12:00:00Z"
  }
}

Warning Response (Merge with Branch Deletion Skipped):

{
  "status": "warning",
  "message": "PR #456 merged but branch not deleted",
  "details": {
    "operation": "merge-pr",
    "pr_number": 456,
    "merge_sha": "abc123def456...",
    "strategy": "squash",
    "branch_deleted": false
  },
  "warnings": [
    "Branch 'feat/123-add-export' was not deleted due to protection rules"
  ],
  "warning_analysis": "The branch has additional protection that prevents automatic deletion",
  "suggested_fixes": [
    "Manually delete branch: git push origin --delete feat/123-add-export",
    "Check branch protection rules in repository settings"
  ]
}

Failure Response (Missing work_id):

{
  "status": "failure",
  "message": "Cannot create PR - work_id could not be determined",
  "details": {
    "operation": "create-pr",
    "head_branch": "main",
    "base_branch": "develop"
  },
  "errors": [
    "work_id is required for PR creation to enable automatic issue closing",
    "Branch name 'main' does not follow pattern: prefix/ID-description"
  ],
  "error_analysis": "PR creation requires work_id to link to an issue. It was not provided explicitly and could not be extracted from branch name.",
  "suggested_fixes": [
    "Provide work_id explicitly: --work-id 123",
    "Use branch naming convention: fix/123-description or feat/456-feature-name",
    "Create PR from a feature branch, not main"
  ]
}

Failure Response (Merge Conflicts):

{
  "status": "failure",
  "message": "PR #456 cannot be merged - merge conflicts detected",
  "details": {
    "operation": "merge-pr",
    "pr_number": 456,
    "mergeable": "CONFLICTING"
  },
  "errors": [
    "Merge conflict in src/export.js",
    "Merge conflict in src/utils.js"
  ],
  "error_analysis": "The head branch has diverged from base branch and has conflicting changes in 2 files",
  "suggested_fixes": [
    "Checkout branch: git checkout feat/123-add-export",
    "Pull latest base: git merge origin/main",
    "Resolve conflicts in conflicting files",
    "Push resolved changes: git push"
  ]
}

Failure Response (CI Not Passing):

{
  "status": "failure",
  "message": "PR #456 cannot be merged - CI checks failing",
  "details": {
    "operation": "merge-pr",
    "pr_number": 456,
    "ci_status": "failing"
  },
  "errors": [
    "Check 'build' failed: Exit code 1",
    "Check 'test' failed: 3 tests failed"
  ],
  "error_analysis": "Required CI checks must pass before merging. Build and test checks are currently failing.",
  "suggested_fixes": [
    "View CI details at PR URL",
    "Fix failing tests and push changes",
    "Re-run CI checks after fixes"
  ]
}

Failure Response (PR Not Found):

{
  "status": "failure",
  "message": "PR #999 not found",
  "details": {
    "operation": "analyze-pr",
    "pr_number": 999
  },
  "errors": [
    "Pull request #999 does not exist in this repository"
  ],
  "error_analysis": "The specified PR number does not exist or may have been deleted",
  "suggested_fixes": [
    "Verify PR number is correct",
    "Check if PR was closed or deleted",
    "List open PRs: gh pr list"
  ]
}

</OUTPUTS> <HANDLERS> This skill uses the handler pattern to support multiple platforms:

• handler-source-control-github: GitHub PR operations via gh CLI
• handler-source-control-gitlab: GitLab MR operations (stub)
• handler-source-control-bitbucket: Bitbucket PR operations (stub)

The active handler is determined by configuration: config.handlers.source_control.active </HANDLERS>

<ERROR_HANDLING>

Invalid Inputs (Exit Code 2):

• Missing title: "Error: PR title is required"
• Missing head_branch: "Error: head_branch is required"
• Missing base_branch: "Error: base_branch is required"
• Missing work_id: "Error: work_id is required for issue linking. Provide explicitly or use branch pattern: prefix/ID-description"
• Invalid pr_number: "Error: PR number must be a positive integer"
• Invalid action: "Error: Invalid review action. Valid: approve|request_changes|comment"
• Invalid strategy: "Error: Invalid merge strategy. Valid: no-ff|squash|ff-only"

Branch Errors (Exit Code 1):

• Head branch doesn't exist: "Error: Head branch not found: {head_branch}"
• Base branch doesn't exist: "Error: Base branch not found: {base_branch}"
• No commits to merge: "Error: Head branch has no new commits compared to base"

PR Not Found (Exit Code 1):

• Invalid PR: "Error: Pull request not found: #{pr_number}"
• PR already merged: "Error: Pull request already merged: #{pr_number}"
• PR closed: "Error: Pull request is closed: #{pr_number}"

Merge Conflicts (Exit Code 13):

• Conflicts detected: "Error: Pull request has merge conflicts. Resolve conflicts first."
• Cannot auto-merge: "Error: Pull request cannot be automatically merged"

CI Failures (Exit Code 14):

• CI not passing: "Error: CI checks are not passing. Cannot merge."
• Required checks missing: "Error: Required status checks have not passed"

Review Requirements (Exit Code 15):

• Insufficient reviews: "Error: Pull request requires {N} approving reviews before merging"
• Changes requested: "Error: Pull request has requested changes that must be resolved"

Protected Branch (Exit Code 10):

• Protected target: "Warning: Creating PR to protected branch: {base_branch}. Confirm requirements."
• Force merge blocked: "Error: Cannot force merge to protected branch: {base_branch}"

Approval Required (Exit Code 16):

• Protected branch without approval: "Error: Cannot merge PR #{pr_number} to protected branch '{base_branch}' without approval. Set FABER_RELEASE_APPROVED=true after obtaining explicit user confirmation."

Authentication Error (Exit Code 11):

• No credentials: "Error: Platform API credentials not found"
• Permission denied: "Error: Insufficient permissions to create/merge PR"

Handler Error (Exit Code 1):

• Pass through handler error: "Error: Handler failed - {handler_error}"

</ERROR_HANDLING>

<USAGE_EXAMPLES>

Example 1a: Analyze PR (with conflicts)

INPUT:
{
  "operation": "analyze-pr",
  "parameters": {
    "pr_number": 456
  }
}

OUTPUT:
{
  "status": "success",
  "pr_number": 456,
  "analysis": {
    "title": "Add CSV export functionality",
    "state": "OPEN",
    "mergeable": "CONFLICTING",
    "conflicts": {
      "detected": true,
      "files": ["src/export.js", "src/utils.js"]
    },
    "ci_status": "pending",
    "reviewDecision": "REVIEW_REQUIRED",
    "recommendation": "RESOLVE_CONFLICTS_FIRST"
  }
}

Example 1b: Analyze PR (with code review issues in comments)

INPUT:
{
  "operation": "analyze-pr",
  "parameters": {
    "pr_number": 456
  }
}

SCENARIO:
- PR is mergeable (no conflicts)
- CI checks are passing
- No formal CHANGES_REQUESTED review state
- BUT: Most recent comment from reviewer contains critical issues

HANDLER RESPONSE:
{
  "pr": {
    "mergeable": "MERGEABLE",
    "reviewDecision": null,
    "statusCheckRollup": [{"state": "SUCCESS"}]
  },
  "comments": [
    {
      "author": {"login": "reviewer1"},
      "created_at": "2025-11-19T10:30:00Z",
      "body": "I've reviewed the code and found several critical issues that must be fixed before this can be approved:\n\n1. Missing error handling for large files (>100MB) - this will cause memory issues\n2. No validation for malformed CSV input - security vulnerability\n3. Unit tests don't cover edge cases (empty files, special characters)\n4. The export function doesn't handle concurrent requests properly\n\nPlease address these before we proceed with approval."
    }
  ],
  "reviews": [],
  "review_comments": []
}

SKILL ANALYSIS (Step 5 - Comment Analysis):
- Most recent comment from: reviewer1
- Timestamp: 2025-11-19T10:30:00Z
- BLOCKING KEYWORDS FOUND: "critical issues", "must be fixed", "before this can be approved"
- STRUCTURED ISSUES FOUND: Numbered list with 4 specific issues
- Context clues: "before we proceed with approval" -> BLOCKING

RECOMMENDATION (from decision tree step 5):
"DO NOT APPROVE - ADDRESS CRITICAL ISSUES FIRST"

OUTPUT:
{
  "status": "success",
  "pr_number": 456,
  "analysis": {
    "title": "Add CSV export functionality",
    "state": "OPEN",
    "mergeable": "MERGEABLE",
    "conflicts": {
      "detected": false,
      "files": []
    },
    "ci_status": "passing",
    "reviewDecision": null,
    "comment_analysis": {
      "most_recent_comment": {
        "author": "reviewer1",
        "timestamp": "2025-11-19T10:30:00Z",
        "blocking_keywords": ["critical issues", "must be fixed", "before this can be approved"]
      },
      "outstanding_issues": [
        "Missing error handling for large files (>100MB) - this will cause memory issues",
        "No validation for malformed CSV input - security vulnerability",
        "Unit tests don't cover edge cases (empty files, special characters)",
        "The export function doesn't handle concurrent requests properly"
      ]
    },
    "recommendation": "DO_NOT_APPROVE",
    "priority": "P1",
    "reason": "Most recent code review identified critical issues that must be addressed"
  }
}

Example 2: Create PR from FABER Release

INPUT:
{
  "operation": "create-pr",
  "parameters": {
    "title": "feat: Add CSV export functionality",
    "body": "Implements user data export...",
    "head_branch": "feat/123-add-export",
    "base_branch": "main",
    "work_id": "123"
  }
}

OUTPUT:
{
  "status": "success",
  "pr_number": 456,
  "pr_url": "https://github.com/owner/repo/pull/456"
}

Example 3: Add Comment to PR

INPUT:
{
  "operation": "comment-pr",
  "parameters": {
    "pr_number": 456,
    "comment": "Tests are passing. Ready for review."
  }
}

OUTPUT:
{
  "status": "success",
  "comment_id": 789,
  "comment_url": "https://github.com/owner/repo/pull/456#issuecomment-789"
}

Example 4: Approve PR

INPUT:
{
  "operation": "review-pr",
  "parameters": {
    "pr_number": 456,
    "action": "approve",
    "comment": "Great work! Code looks good."
  }
}

OUTPUT:
{
  "status": "success",
  "review_id": 890,
  "action": "approve"
}

Example 5: Merge PR with No-FF Strategy (Protected Branch with Approval)

INPUT:
{
  "operation": "merge-pr",
  "parameters": {
    "pr_number": 456,
    "strategy": "no-ff",
    "delete_branch": true
  }
}

FLOW (if base_branch is 'main'):
1. Skill detects protected branch 'main'
2. Skill invokes AskUserQuestion for approval
3. User selects "Approve release"
4. Skill exports FABER_RELEASE_APPROVED=true
5. Skill invokes handler with approval environment variable set
6. Handler script checks variable and proceeds with merge
7. PR merged successfully

OUTPUT:
{
  "status": "success",
  "merge_sha": "abc123...",
  "branch_deleted": true
}

Example 6: Merge PR with Squash

INPUT:
{
  "operation": "merge-pr",
  "parameters": {
    "pr_number": 789,
    "strategy": "squash",
    "delete_branch": false
  }
}

OUTPUT:
{
  "status": "success",
  "merge_sha": "def456...",
  "branch_deleted": false
}

</USAGE_EXAMPLES>

<PR_BODY_TEMPLATE>

The PR body is formatted using this template:

## Summary
Brief description of what this PR does

## Changes
Detailed list of changes:
- Change 1
- Change 2
- Change 3

## Testing
How this was tested:
- Test scenario 1
- Test scenario 2

## Work Item
Closes #{work_id}

## Review Checklist
- [ ] Code follows project standards
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No breaking changes (or documented)

## Metadata
- **Branch**: {head_branch}
- **Base**: {base_branch}
- **Author Context**: {author_context}
- **Phase**: {phase}
- **Created**: {timestamp}

---
*Generated by FABER workflow*

</PR_BODY_TEMPLATE>

<MERGE_STRATEGIES>

no-ff (No Fast-Forward):

• Creates merge commit even if fast-forward possible
• Preserves branch history
• Best for: Feature branches, maintaining history
• Command: git merge --no-ff

squash:

• Combines all commits into single commit
• Clean linear history
• Best for: Small features, bug fixes
• Command: git merge --squash

ff-only (Fast-Forward Only):

• Only merges if fast-forward possible
• No merge commits
• Best for: Simple updates, hotfixes
• Command: git merge --ff-only

Default Recommendation: no-ff for features, squash for fixes

</MERGE_STRATEGIES>

<INTEGRATION>

Called By:

• repo-manager agent - For programmatic PR operations
• /repo:pr command - For user-initiated PR management
• FABER release-manager - For creating and managing release PRs

Calls:

• repo-common skill - For configuration loading
• handler-source-control-{platform} skill - For platform-specific PR operations

Integrates With:

• Work tracking system - For automatic issue closing
• CI/CD systems - For status checks
• Review systems - For approval workflows

</INTEGRATION>

Context Efficiency

This skill handles multiple PR operations:

• Skill prompt: ~600 lines
• No script execution in context (delegated to handler)
• Clear operation routing
• Structured templates

By centralizing PR management:

• Consistent PR formatting
• Unified error handling
• Single source for PR rules
• Clear merge safety checks