the-nexus/docs/duplicate-pr-prevention.md

Duplicate PR Prevention System

Comprehensive system to prevent duplicate PRs from being created for the same issue.

Problem

Despite having tools to detect and clean up duplicate PRs, agents were still creating duplicate PRs for the same issue. This was incredibly ironic, especially for issue #1128 which was about cleaning up duplicate PRs.

Solution

1. Pre-flight Check Scripts

scripts/check-existing-prs.sh (Bash)

Check if an issue already has open PRs before creating a new one.

./scripts/check-existing-prs.sh 1524

Exit codes:

• 0: No existing PRs found (safe to create new PR)
• 1: Existing PRs found (do not create new PR)
• 2: Error (API failure, missing parameters, etc.)

scripts/check_existing_prs.py (Python)

Python version of the check with more features:

python scripts/check_existing_prs.py 1524
python scripts/check_existing_prs.py --issue 1524

scripts/pr-safe.sh (User-friendly wrapper)

Guides you through safe PR creation:

./scripts/pr-safe.sh 1524
./scripts/pr-safe.sh 1524 fix/my-branch

2. Fixed Existing Script

Fixed syntax error in scripts/cleanup-duplicate-prs.sh (line 21) and AUTH header format.

3. Prevention Strategy

1. Pre-flight Checks: Always check before creating a PR
2. Agent Discipline: Add to agent instructions to check before creating PRs
3. Tooling Integration: Integrate into existing workflows

Usage

Before Creating a PR

# Check if issue already has PRs
./scripts/check-existing-prs.sh <issue_number>

# If exit code is 0, safe to proceed
# If exit code is 1, review existing PRs first

In Agent Instructions

Add to your agent instructions:

Before creating a PR for any issue:
1. Run: ./scripts/check-existing-prs.sh <issue_number>
2. If exit code is 1, STOP and review existing PRs
3. Only proceed if exit code is 0

Cleanup Existing Duplicates

# Show what would be done
./scripts/cleanup-duplicate-prs.sh --dry-run

# Actually close duplicates
./scripts/cleanup-duplicate-prs.sh --close

Integration

CI/CD

Add to your CI pipeline:

- name: Check for duplicate PRs
  run: ./scripts/check-existing-prs.sh ${{ github.event.pull_request.number }}

Git Hooks

Add to .git/hooks/pre-push:

#!/bin/bash
# Extract issue number from branch name
ISSUE=$(git branch --show-current | grep -oE '[0-9]+$')
if [ -n "$ISSUE" ]; then
    ./scripts/check-existing-prs.sh "$ISSUE"
fi

Best Practices

1. Always check before creating PRs — use the pre-flight check
2. Close duplicates promptly — don't let them accumulate
3. Reference issues in PRs — makes duplicate detection possible
4. Use descriptive branch names — helps identify purpose
5. Review existing PRs first — don't assume you're the first

Troubleshooting

"Duplicate PR detected" error

This means a PR already exists for the issue. Options:

1. Review the existing PR and contribute to it
2. Close your PR if it's truly a duplicate
3. Update your PR to address a different aspect

Pre-flight check not working

Check that:

1. Gitea token is configured at ~/.config/gitea/token
2. You have network access to the Gitea instance
3. The repository name is correct in the script

False positives

The check looks for issue numbers in PR body. If you're referencing an issue without intending to fix it, use "Refs #" instead of "Fixes #".

Related Issues

• #1474: [META] Still creating duplicate PRs for issue #1128 despite cleanup
• #1128: Original duplicate PR cleanup issue
• #1500: observation: #1474 already has 2 open PRs — prevented another duplicate