> For the complete documentation index, see [llms.txt](https://help.resouris.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.resouris.com/set-up-what-you-schedule/author-an-allocation-policy.md).

# Author an allocation policy

**Who:** roster-area admin or higher. **Perm:** `equity.policy.publish` (create), `roster.update` (read). **Time:** \~15 minutes for a preset-based policy; longer for custom weights.

The allocation policy governs how the solver scores candidates. It's the single most impactful configuration surface in ReSouris — a bad policy produces defensibly-solved-but-clearly-unfair rosters.

## Before you start

You need to know:

* Which **equity dimensions** matter for your department (weekend shifts? night on-call hours? training-supervisor load?).
* What **windows** you want to measure fairness over (4-weekly? 13-weekly? monthly?).
* Whether any assignments should be **excluded** from the equity computation (study leave? external-cover shifts?).

If you don't know yet, start with the **Balanced** preset and iterate after seeing one solve.

## 1. Navigate

Sidebar → **Fairness & cover** → **Allocation policies** (`/ui/admin/allocation-policies`), then create a new one.

## 2. Pick a preset

The friendly editor (v1.6 P26.B1) starts with a preset picker rather than an empty form:

* **Balanced** — reasonable defaults across all five score components. Use as the starting point unless you have a strong reason.
* **Skill-first** — heavier weight on `competency_value`. The solver prefers high-competency matches over equity considerations. Use in departments with steep skill hierarchies (interventional radiology, cardiac surgery) where a marginal skill mismatch has real clinical cost.
* **Fairness-first** — heavier weight on `equity_deficit`. Use when the team perception is that senior staff have been dodging on-call.
* **Priority-first** — heavier weight on service-line priority. Use when a subset of SLs (e.g. cancer-pathway two-week wait) must be fully staffed before others.
* **Clone from active** — copy the current active policy as a starting point. Use when iterating.

## 3. Adjust weight sliders

Below the preset, five sliders — one per score component. The live normalised weight bar at the top shows what the solver will actually optimise (weights are normalised to sum to 100 at solve time).

* **Priority** — how strongly to prefer high-priority SLs.
* **Mandatory bonus** — the fixed reward for hard-required assignments (named training, supervisor-locked slots). Usually leave near the top of the slider.
* **Competency value** — how strongly to reward high-competency matches.
* **Equity deficit** — how strongly to reward staff who are below their fair share.
* **Entitlement debt** — how strongly to reward staff whose job-plan entitlement for this activity is under-fulfilled.

Move sliders and watch the normalised bar. If one component dwarfs the others (>60%), the solver will essentially ignore the rest — check that's what you want.

## 4. Windows

Windows define the time scope over which equity is measured for each dimension:

* **4-weekly** — recent history bias. Use for high-frequency dimensions (weekly on-call, weekend shifts).
* **13-weekly** — quarterly. Use for annualised entitlements (job-plan sessions/quarter).
* **12-monthly** — annual. Use for once-per-year fairness (Christmas / New Year on-call).

You can set different windows per dimension. Default is 13-weekly for most.

## 5. Exclusions

Under **Exclusions**, tick assignments or dimensions to exclude from the equity denominator:

* **Study leave** — usually excluded so a staff on study leave doesn't accumulate "unfair advantage" the equity accounting has to work back off.
* **External cover** — cover shifts on another team's rota.
* **Ad-hoc extras** — specific activity codes that don't count toward fair-share.

Exclusions are the discrimination-risk mitigation. Standing-policy `equity_adjustment` rows do per-staff carve-outs (see [Equity and fairness model](/how-it-works/equity-model.md)); exclusions here are policy-wide.

## 6. Advanced JSON (optional)

At the bottom, an **Advanced JSON** panel is collapsed by default. Expand it if you need to set a weight or window that isn't in the friendly editor's registry. Passthrough dict preserves keys the friendly editor doesn't know — this is deliberate for forward-compat with future policy schemas.

**Don't hand-edit the JSON unless you have a specific reason.** The friendly editor covers 95% of realistic policies.

## 7. Preview

Click **Preview**. The system runs a dry solve against the current published roster and shows the diff:

* Which assignments would change under this policy.
* How the equity-counter values would shift.
* Any staff whose entitlement debt would materially change.

Use the preview to sanity-check before publishing. If the preview shows a dramatic reshuffling, either the previous policy was very different or your new weights are too aggressive.

## 8. Save + publish

Click **Save**. Policy enters `draft` state.

To activate, click **Publish**. The workflow-driven approval kicks in if your tenant has a workflow override configured for `allocation_policy` artefact kind:

* Draft goes to `proposed`.
* Signers listed in the workflow definition receive notifications.
* When quorum signs off, transitions to `active`.
* Any previous `active` policy transitions to `superseded`.

If no workflow override exists, `Publish` transitions straight to `active`.

## 9. Verify on next solve

Regenerate the roster for a short horizon (one week). Compare the `assignment_score_breakdown` values against expectation. If a component you weighted heavily isn't showing up in the breakdown, either the dimension isn't measured (check equity dimension configuration) or your window is too short to have accumulated a signal.

## Rollback

Every published policy is preserved via `supersedes_id`. To roll back, open the previous policy and click **Reactivate**. The current active transitions to `superseded`; the previous one flips back to `active`.

## Feedback loops

Every allocation policy has a feedback thread attached (see [Equity and fairness model](/how-it-works/equity-model.md)). Staff post questions or disputes with `feedback.post`; whoever holds `feedback.respond` answers — `roster_area_admin` and `tenant_admin` by default. The thread state (`open → resolved → reopened`) tracks resolution.

## Common issues

* **Sliders max out but nothing changes** — the weight is normalised at solve time. Maxing one slider while others are non-zero doesn't produce a "purely-this-component" solve; you'd need to zero the others.
* **Equity deficit doesn't seem to move** — check the equity dimension window. A 13-weekly window won't reflect a change made yesterday.
* **Solver picks a low-scoring candidate** — the `mandatory_bonus` component always wins if a named training assignment or supervisor lock applies. Score breakdown will show the bonus firing.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.resouris.com/set-up-what-you-schedule/author-an-allocation-policy.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.