the-nexus/docs/auto-reviewer-assignment.md

# Automated Reviewer Assignment

**Issue:** #1444 - policy: Implement automated reviewer assignment (from Issue #1127 triage)  
**Purpose:** Ensure all PRs have at least one reviewer assigned

## Problem

From issue #1127 triage:
> "0 of 14 PRs had a reviewer assigned before this pass."

This means:
- PRs can be created without any reviewer
- No automated enforcement of reviewer assignment
- PRs may sit without review for extended periods

## Solution

### 1. GitHub Actions Workflow (`.gitea/workflows/auto-assign-reviewers.yml`)
Automatically assigns reviewers when PRs are created:

**When it runs:**
- On PR open
- On PR reopen
- On PR ready for review (not draft)

**What it does:**
1. Determines appropriate reviewers based on repository
2. Assigns reviewers via Gitea API
3. Adds comment about reviewer assignment
4. Verifies at least one reviewer is assigned

### 2. Reviewer Check Script (`bin/check_reviewers.py`)
Script to check for PRs without reviewers:

**Usage:**
```bash
# Check all repositories
python bin/check_reviewers.py

# Check specific repositories
python bin/check_reviewers.py --repos the-nexus timmy-home

# Generate report
python bin/check_reviewers.py --report

# Assign reviewer to specific PR
python bin/check_reviewers.py --assign the-nexus 123 --reviewer @perplexity
```

### 3. CODEOWNERS File (`.github/CODEOWNERS`)
Defines default reviewers for different paths:

```
# Default reviewer for all repositories
* @perplexity

# Specialized component owners
hermes-agent/ @Timmy
hermes-agent/agent-core/ @Rockachopa
hermes-agent/protocol/ @Timmy
the-nexus/ @perplexity
the-nexus/ai/ @Timmy
timmy-home/ @perplexity
timmy-config/ @perplexity

# Owner gates for critical systems
hermes-agent/ @Timmy
```

## Reviewer Assignment Rules

### Repository-Specific Rules

| Repository | Default Reviewers | Required Reviewers | Notes |
|------------|-------------------|-------------------|-------|
| hermes-agent | @Timmy, @perplexity | @Timmy | Owner gate for critical system |
| the-nexus | @perplexity | None | QA gate |
| timmy-home | @perplexity | None | QA gate |
| timmy-config | @perplexity | None | QA gate |
| the-beacon | @perplexity | None | QA gate |

### Special Rules

1. **No self-review:** PR author cannot be assigned as reviewer
2. **Fallback:** If no reviewers available, assign @perplexity
3. **Critical systems:** hermes-agent requires @Timmy as reviewer

## How It Works

### Automated Assignment Flow

1. **PR Created** → GitHub Actions workflow triggers
2. **Determine Reviewers** → Based on repository and CODEOWNERS
3. **Assign Reviewers** → Via Gitea API
4. **Add Comment** → Notify about assignment
5. **Verify** → Ensure at least one reviewer assigned

### Manual Assignment

```bash
# Assign specific reviewer
python bin/check_reviewers.py --assign the-nexus 123 --reviewer @perplexity

# Check for PRs without reviewers
python bin/check_reviewers.py --report
```

## Configuration

### Environment Variables

- `GITEA_TOKEN`: Gitea API token for authentication
- `REPO`: Repository name (auto-set in GitHub Actions)
- `PR_NUMBER`: PR number (auto-set in GitHub Actions)

### Repository Configuration

Edit the workflow to customize reviewer assignment:

```yaml
# Define default reviewers based on repository
case "$REPO_NAME" in
  "hermes-agent")
    DEFAULT_REVIEWERS=("Timmy" "perplexity")
    REQUIRED_REVIEWERS=("Timmy")
    ;;
  "the-nexus")
    DEFAULT_REVIEWERS=("perplexity")
    REQUIRED_REVIEWERS=()
    ;;
  # Add more repositories as needed
esac
```

## Testing

### Test the workflow:

1. Create a test PR
2. Check if reviewers are automatically assigned
3. Verify comment is added

### Test the script:

```bash
# Check for PRs without reviewers
python bin/check_reviewers.py --report

# Assign reviewer to test PR
python bin/check_reviewers.py --assign the-nexus 123 --reviewer @perplexity
```

## Monitoring

### Check for PRs without reviewers:

```bash
# Daily check
python bin/check_reviewers.py --report

# JSON output for automation
python bin/check_reviewers.py --json
```

### Review assignment logs:

1. Check GitHub Actions logs for assignment details
2. Review PR comments for assignment notifications
3. Monitor for PRs with 0 reviewers

## Enforcement

### CI Check (Future Enhancement)

Add CI check to reject PRs with 0 reviewers:

```yaml
# In CI workflow
- name: Check for reviewers
  run: |
    REVIEWERS=$(curl -s "https://forge.alexanderwhitestone.com/api/v1/repos/$REPO/pulls/$PR_NUMBER/requested_reviewers" \
      -H "Authorization: token $GITEA_TOKEN" | jq '.users | length')
    
    if [ "$REVIEWERS" -eq 0 ]; then
      echo "❌ ERROR: PR has no reviewers assigned"
      exit 1
    fi
```

### Policy Enforcement

1. **All PRs must have reviewers** - No exceptions
2. **No self-review** - PR author cannot review own PR
3. **Critical systems require specific reviewers** - hermes-agent requires @Timmy

## Related Issues

- **Issue #1127:** Perplexity Evening Pass triage (identified missing reviewers)
- **Issue #1444:** This implementation
- **Issue #1336:** Merge conflicts in CODEOWNERS (fixed)

## Files Added/Modified

1. `.gitea/workflows/auto-assign-reviewers.yml` - GitHub Actions workflow
2. `bin/check_reviewers.py` - Reviewer check script
3. `.github/CODEOWNERS` - Cleaned up CODEOWNERS file
4. `docs/auto-reviewer-assignment.md` - This documentation

## Future Enhancements

1. **CI check for 0 reviewers** - Reject PRs without reviewers
2. **Slack/Telegram notifications** - Notify when PRs lack reviewers
3. **Load balancing** - Distribute reviews evenly among team members
4. **Auto-assign based on file changes** - Assign specialists for specific areas

## Conclusion

This implementation ensures all PRs have at least one reviewer assigned:
- **Automated assignment** on PR creation
- **Manual checking** for existing PRs
- **Clear documentation** of policies and procedures

**Result:** No more PRs sitting without reviewers.

## License

Part of the Timmy Foundation project.