Reviewer and assignee suggestions

Quavon can suggest reviewers for pull requests and assignees for issues, and, where every gate allows it, request them on GitHub. The feature is off for every repository by default. Design record: ADR-0014. Legal input: assignment-assessment.md.

Instructions for use

Intended purpose. Quavon assignment suggests reviewers for pull requests and assignees for issues in a software repository, based on the relationship between people and the code affected (code ownership, recent changes and reviews of the same files), their current number of open assignments and their declared availability, in order to route work to people who know the code and to spread knowledge. It does not evaluate the performance, behaviour or personal characteristics of people.

Prohibited uses. Do not use suggestions, explanations, assignment records or the familiarity data for decisions on hiring, pay, promotion, termination or performance appraisal, or to monitor individuals. Do not export per-person data. Changing the inputs (for example in a fork) changes the intended purpose; whoever does so may become the provider of a different system.

Inputs (closed list). CODEOWNERS entries of the affected paths (read at the pull request's base commit) with team expansion; time-decayed commits, blame lines and reviews on the affected paths; people who worked on similar closed issues; current open review requests and assigned issues (counts); availability (GitHub "Busy", manual out-of-office periods, an ICS feed reduced to out-of-office from/to times, working hours), only for people who opted in; opt-out and privacy flags.

Never used or stored. Review or merge speed, response times, commit counts or lines of code as a standalone value, findings or acceptance rates per person, reverted commits, personal traits, calendar titles, attendees, locations, descriptions or absence reasons, GitHub status messages or emoji, per-person learned parameters.

Human oversight. Every suggestion and every applied assignment can be changed on GitHub at any time. Changes within the reassignment window are recorded as feedback for the repository (no free text, no record of who changed it) and never lower a person's future suggestions.

Modes

Mode	Effect
off (default)	Nothing is read or computed.
shadow	Suggestions are computed and stored. Self-hosted: visible to instance admins only. Hosted (enterprise): visible to nobody. Nothing is written to GitHub.
suggest	Suggestions appear on the repository's Assignments tab and, if Post suggestions as one comment is on, as one comment naming the suggested people (logins as code, so nobody is notified) and the reasons. No scores, ranks or other candidates are shown.
apply	Quavon requests the reviewers or sets the assignees through the publisher, adds only missing people and never removes a request. Every applied assignment is audited (assignment.applied).

The mode set on the repository's policy (Policy → Assignment) is the requested mode. The effective mode is the lowest mode every gate allows; the policy page shows it with the reasons:

Reason	Cap
no_legal_sign_off	shadow
mode_not_permitted	The highest mode in the sign-off (apply never with outcome B)
high_risk_without_conformity	suggest until 2 December 2027, then shadow
works_council_without_agreement	off
works_agreement_forbids_apply	suggest
deployer_attestation_missing	shadow (hosted edition only)
apply_not_opted_in	suggest

The gate is checked when the job runs, when it stores the result and again in the publisher before every GitHub call. If a gate closes between the job and the publication, nothing is posted.

Legal sign-off

Until an instance admin records a legal sign-off, every repository stays in shadow at most. Record it on the instance page Legal sign-off after counsel (and, for German deployments, the works council) has completed docs/legal/assignment-assessment.md §9:

• outcome A, B or C (assessment §7), permitted modes, document reference and date;
• for outcome C, whether the conformity assessment is completed.

Sign-offs are append-only and audited (assignment.legal_sign_off.set|cleared); Clear records an empty sign-off and returns every repository to shadow.

Works-council mode

Tenant admins answer the employment questions under Assignment & privacy: country and whether a works council exists. Works-council mode is on when the country is Germany and the answer is not "no", and also while the questions are unanswered. In works-council mode:

• the feature stays off (no computation, no familiarity data) until a tenant admin records the works agreement (reference, date, whether it permits apply);
• team-level metrics only are forced, so every per-person view returns 404;
• retention is capped at the defaults.

Confirming that no works council exists for a German tenant requires an explicit confirmation and is audited. The hosted edition also needs the tenant's deployer attestation (DPIA done, employees informed, works agreement where required) before anything leaves shadow.

Enabling apply

apply needs a sign-off that permits it, works-council mode off or a works agreement that permits it, and a per-repository opt-in. Only a tenant admin can opt in, on the repository's policy page, by confirming the displayed text; the opt-in is audited (assignment.apply_opt_in.enabled|disabled). Saving the policy never changes the opt-in.

GitHub requests code owners by itself when a pull request is opened; Quavon counts existing requests towards the configured number of reviewers. The review app needs Members: read to expand teams; without it, team owners are skipped. Jobs read with read-only installation tokens; only the publisher uses write permissions.

Privacy controls

• Opt-out (My assignment settings): the person is never suggested or picked, also not in shadow; their familiarity rows are deleted. They stay assignable by hand. Nobody else can see the opt-out.
• Availability is opt-in per person: manual out-of-office periods, an ICS feed URL (https only, stored encrypted, never shown again, fetched through the egress guard without redirects, at most 1 MiB, reduced to from/to times) and working hours with a time zone. GitHub "Busy" is only read for people who opted in. Unknown availability never excludes anyone.
• Team-level metrics only (tenant or repository): per-person endpoints such as the workload view return 404, and no open-work facts are produced. Otherwise the workload view lists only people who opted in under My assignment settings → Workload view, with their open review requests and assigned issues as counts only (no scores or rankings). Turning the opt-in off removes the person from the view immediately.
• Comment language (Assignment & privacy): suggestion comments are posted in English (default) or German, per tenant.
• Retention (Assignment & privacy): assignment records 183 days, availability 30 days after the period ends, reassignment feedback 183 days by default. Familiarity data is recomputed per path and deleted outside the lookback window, and entirely for repositories whose effective mode is off.

Transparency page

Every tenant member can open Assignment transparency. It lists the inputs and exclusions, the requested and effective mode of each repository the member can see, the legal sign-off, whether works-council mode and team-level metrics are on, the retention periods and the contact configured by the tenant. It contains no per-person data.

Limitations

• Whether installation tokens can see organisation-scoped GitHub "Busy" statuses is undocumented and unverified; such statuses are treated as unknown.
• Open-work counts cover only repositories the installation can access, and only organisation installations (org: search).
• ICS recurrence rules are expanded for DAILY, WEEKLY, MONTHLY (also with BYMONTHDAY) and YEARLY with INTERVAL, COUNT and UNTIL, within the import window; other rules count only their first occurrence. Common Windows time-zone names are mapped to IANA zones; unknown names fall back to UTC.