-
Notifications
You must be signed in to change notification settings - Fork 23
Description
Problem
Watchflow already lets teams define rules (sensitive paths, required reviewers, severity) for pre-merge governance. However, the current system does not tie rule severity into reviewer recommendations or provide risk signals for PRs that need extensive review.
Static CODEOWNERS files become stale as teams grow and do not account for:
- Who recently touched similar code
- Who has expertise in the specific files/technologies changed
- Current review load and availability
- Rule severity (critical paths should require senior reviewers)
High-volume orgs especially suffer from bottlenecks when a few people own everything, leading to imbalanced review loads and slow PR velocity.
Goal
Build a reviewer recommendation engine that integrates with existing Watchflow rule system to suggest the best reviewer for a PR based on:
-
Rule-based risk assessment
- Use existing Watchflow rules to assess PR risk
- Rules with
severity: criticalindicate high-risk PRs requiring senior reviewers - Custom rules for sensitive paths determine required expertise level
- Multiple rule matches compound risk score
-
CODEOWNERS + Watchflow rules integration
- Respect CODEOWNERS as a base filter when present
- Apply Watchflow rule severity to adjust recommendation strength
- If no CODEOWNERS exists, use rule matches to infer ownership
-
Review load balancing
- Track who has reviewed high-severity PRs recently
- Balance load based on rule severity (critical = experienced reviewers only)
- Suggest backup reviewers when primary is overloaded
-
Contributor expertise profiling
- Analyze commit history to build expertise by file path/language
- Weight recent contributions higher than stale ownership
- Consider past review quality and acceptance rate
GitHub Integration
Slash Commands
Support in-PR commands (similar to Danger or other GitHub bots):
/reviewers - Recommend best reviewers based on rules + expertise
/risk - Show risk assessment (size, severity, coverage, deps)
/reviewers --force - Force re-run recommendation
Response Format
## Watchflow: Reviewer Recommendation
**Risk:** High (critical rules matched, 50 files changed)
**Recommended:**
1. @alice - billing expert, 80% ownership of changed files
2. @bob - config owner, available today
**Reasoning:**
- Rule src/billing/* (severity: critical) - requires senior reviewer
- Rule config/* (severity: high) - recommend second reviewer
- @alice has 3 recent reviews on billing code
Labels and Metadata
- Use labels:
watchflow:reviewer-recommendation,watchflow:risk-critical,watchflow:risk-medium,watchflow:risk-low - Reuse existing PR comment formatting patterns
- Store expertise profiles in
.watchflow/or GitHub Project (no external storage)
Risk Signals
- Size risk - Many files, thousands of lines, many commits
- Critical path - Changes to auth, payments, config, secrets, database schemas
- Test coverage - PR removes tests or adds code without tests
- Dependency changes - New deps, version bumps, unverified packages
- Contributor history - First-time contributor, low PR acceptance rate
- Reverts - PR reverts previous changes
- Security-sensitive - Modifies CI/CD, infra code, secrets handling
- Breaking changes - Modifies public APIs, migrations
- Rule matches - Severity of matched Watchflow rules
Constraints
- No new storage - Store expertise profiles in GitHub (labels, projects, or
.watchflow/directory) - No new UI - Leverage existing GitHub primitives (PR comments, labels, assignees)
- No third-party integrations - GitHub API only
- Reuse existing infrastructure - Extend existing rule matching and webhook handlers
Implementation Phases
Phase 1: Risk Assessment
- Integrate with existing rule engine
- Calculate risk score based on rule severity and file changes
- Add
/riskslash command - Post risk breakdown as PR comment
Phase 2: Reviewer Recommendation
- Build contributor expertise profiles from commit history
- Factor in CODEOWNERS (if exists)
- Add
/reviewersslash command - Post ranked recommendations with reasoning
Phase 3: Load Balancing
- Track recent review activity per contributor
- Factor in availability and current queue
- Suggest appropriate reviewer count based on risk
Example Flows
Example 1: Critical path changes
- PR opens touching
src/billing/andconfig/prod.yaml - Watchflow rules:
path: config/*(severity: high),path: src/billing/(severity: critical) - Risk engine: critical + high severity, 2 rule matches = high risk
- Recommendation: @alice (billing expert) + @bob (config owner), 2 reviewers required
Example 2: First-time contributor
- PR opened by @newDev adding
src/utils/helper.pywith no tests - Risk: low rule matches but no test coverage + first PR
- Recommendation: request senior reviewer + mention no tests
Example 3: High-volume org
- 10 PRs open simultaneously, all touching
core/ - CODEOWNERS says @TeamA owns
core/ - Load balancer sees @TeamA has 3 pending reviews
- Recommendation: suggest @backup-reviewer as additional option
Dependencies
- Reuse existing repository analysis pipeline
- Extend existing webhook handlers for slash commands
- May extend
RepositoryAnalysisAgentor create newReviewerRecommendationAgent - Reuse existing rule matching and severity logic
Success Metrics
- Percentage of PRs with reviewer recommendations accepted
- Reduction in average review time
- Improvement in review load distribution
- User satisfaction with recommendations
Related
- Existing rule engine and severity system
- CODEOWNERS file support