Set a default scope for every question

Your GitHub credential probably reaches more of your organisation than the people you are asking about. Prism's index holds whatever it was given, so "who merged the most pull requests last month" is answered about everyone in it — which on an organisation-wide credential is mostly people the person asking has never heard of.

This page is how you say, once, which part of the organisation this installation is about. It takes a few minutes and you need one thing first: a definition that selects people.

You need a directory and a definition first. The scope is not a value you type — it is one of your own definitions, named. So there has to be a designated organisational context stream (a warehouse view or an uploaded staff list), and at least one activated definition that selects people. Admin → Definitions is where those are written; Upload who owns what creates a set of them from a spreadsheet in one step.

Set it

On Admin → Definitions, the Scope band at the top of the page says, in the words every answer uses, what questions currently run under — on a new installation, org-wide: this installation has no default scope set.

Press Set a scope. The chooser lists Everyone in the index first, and then every activated definition, with its kind, its revision and, for one that can be the scope, how many people it selected when it was measured. Choose one and What changes shows the line every answer will name the scope with. Then press Save the scope; the band reads the setting back and shows the new line.

A definition that cannot be the scope is still listed, greyed out, with the reason Prism would refuse it — so a list of identifiers or a context document you were looking for is there, saying why it is not a choice, rather than missing. If none of your activated definitions can be the scope, Set a scope is greyed out and the band says so.

If the band says the scope could not be read, the reason is beside it: this build or its database cannot read the setting, and nothing on the page will change it.

Prism refuses a name that is not an active definition that selects people, and says why. That refusal is deliberate and it is the only place this feature refuses anything: you are standing there, choosing, so a choice that could never work should fail while you can still pick another.

Two kinds of definition can be the scope:

Kind	What it means
a reporting line	everyone under a leader, at a depth you chose
a classification	everyone your directory's own fields say is something — a job family, a division

A list of identifiers cannot. It selects people, so you can ask a question that names one — but Prism cannot yet turn one into the scope every question runs under, and setting it is refused, saying which kinds it takes. That refusal is a different one from the refusal for a name that is not a population at all, and deliberately so: "does not select people" would be false about a list of identifiers, and would send you looking for the wrong problem. Both fail at the same moment and for the same reason — you are standing there, choosing, so the choice fails while you can still pick another.

A context document — the prose kind, where you write down what an acronym means — cannot be the scope. It describes words, not people.

What changes

A question that names nobody in particular runs under it, and the answer says so. Where an answer used to be about everyone in the index, it is now about the people your scope selects, with a line naming the definition and its revision:

this installation's default scope: 'Payments engineering' (revision 3) — 214 people when it was activated on 8 September 2026

A question that names someone overrides it, silently. Ask about a particular leader, team or definition and that is what you get — the answer says which population it used, in full, and does not also mention the default. Two population sentences in one answer would describe two different sets of people in one breath. Nobody is locked out of anything by this setting: a reader can always widen by asking a wider question.

What it never does

It never silently narrows a number. Every answer that ran under the scope says so. That is the whole design: a denominator that moves without saying so is worse than a wrong one, because nothing shows.

It never takes the installation down. Once set, this setting is read on every question — so it is deliberately hard to make a question fail because of it, and easy to make one say something true:

What happened	What a question does
nothing is set	answers about everyone, and says org-wide: this installation has no default scope set
you withdrew the definition the scope names	answers about everyone, and says the scope names a definition with no active revision
that name is now a context document rather than a population	answers about everyone, and says so, naming the kind
the scope names a list of identifiers, set before this release refused it	answers about everyone, and says the scope is a kind this build cannot apply
the source computes its own figures (a warehouse view)	answers about everyone it holds, and says the scope does not apply on that path
no organisational directory is designated	answers about everyone, and says to designate one on the Data sources page
Prism could not read its own database	refuses, and says to ask again

Every row but the last is a state — of your data, or of where a figure is computed — and an administrator who withdrew a definition has not asked for every question on the installation to stop working. The warehouse row is the one worth knowing about before you set a scope: a source Prism queries live rather than copying computes its figures in your own system, where Prism's identity crosswalk does not exist, so no population can reach those rows. Those answers stay org-wide and say so.

The last is a fault, and it is the one case where refusing is right — a question answered as though no scope were set, on an installation that has one, would be about more people than the reader was told.

And it does not reach everything. Four kinds of answer are built from an index directly, or from a live query, and cannot apply it: the GitHub index, the Jira index, a live GitHub drill-down, and the two internal leaderboard endpoints. Each says so in a line of its own. Limits is the list.

Change it, or clear it

The same chooser: the band's button says Change the scope once one is set. Choose another definition to change it, or Everyone in the index to clear it. Changing the scope changes what unscoped questions are about from that moment — it does not rewrite answers already given, and an archived answer still names the scope it ran under, so a figure someone acted on last month is still explicable.

Clearing it returns the installation to org-wide, which every answer then says. If somebody changed the scope after you opened the chooser, saving is refused and says what it is now, so you cannot replace or remove a scope you never saw. Setting and clearing are both recorded with who did it.

What to check afterwards

Ask a question you know the answer to, with no leader or team named:

How many pull requests were merged last month?

The answer should carry the scope line above, naming the definition you chose and its revision. If it says org-wide: this installation has no default scope set, the setting did not save. If it names a definition you did not choose, somebody else set it — every change records who made it.

For scripting

The page calls two routes you can call yourself, with a super-administrator session, the same as the page.

curl -sS -X POST "https://<host>/api/admin/definitions/scope" \
  -H "Content-Type: application/json" \
  -d '{"name": "Payments engineering"}'

{"name": null} clears it. Add "expect_name_key" — the name_key you read, or null if none was set — to either call, and it is refused (409) if the scope has changed since, as the page's calls are. A name you type is matched against aliases too, as a question would be; {"name_key": ...} names a definition by its own name only, which is what the page sends. GET /api/admin/definitions/scope reads back what the installation defaults to, what that resolves to now, and candidates: every activated definition, with eligible, and for one that cannot be the scope, why_not — the sentence a POST naming it would be refused with.