Authoring Roles
The mental model
A role is an actor — a distinct persona that interacts with the system. It is not a user account, not a permission level, and not a row in a roles table. It represents a coherent set of responsibilities and goals that drive how someone uses the system.
Think of a role as the answer to: “Who is this person, what do they need to accomplish, and what motivates them?”
Roles are about responsibilities, not permissions
The most important distinction: a role describes why someone uses the system and what they care about, not what buttons they can click. Permissions are an implementation detail derived from roles, not the other way around.
An “Admin” role is not defined by “can access the admin panel.” It is defined by the responsibility: “Ensures the system operates correctly, manages user accounts, and resolves escalated issues.”
When to create a role
Create a new role when you identify a person (or system) that:
- Has a distinct set of goals different from existing roles
- Participates in flows with unique responsibilities
- Would read or use the system in a fundamentally different way
Do not create a role for every permission tier. If “Editor” and “Reviewer” have the same goals and motivations but different access levels, they may be one role with different permissions — not two roles.
Keeping roles minimal
A tight role set is easier to reason about than a sprawling one. Before adding a role, ask:
- “Does this person’s motivation differ from an existing role?”
- “Would collapsing this into an existing role lose important information?”
- “Do flows need to distinguish this actor from others?”
If two roles always appear in the same flows doing the same things, merge them.
Relationship to features and flows
Roles connect to the rest of the spec in two ways:
- Features declare
roles="user admin"— stating which actors use this capability - Flows use
actor="role/user"on steps — stating who performs each action
This creates a traceable chain: role definition describes the person, features describe what they can do, flows describe how they do it.
Writing good role descriptions
The prose body of a role tag should capture:
- Identity — who this person is in one sentence
- Primary goals — what they are trying to accomplish (2-3 bullets worth)
- Context — when and how they interact with the system
Keep it brief. A role is not a user research document — it is a shared reference that ensures everyone on the team pictures the same person when they say “user.”
Common mistakes
| Mistake | Why it hurts |
|---|---|
| Role per permission level | ”Viewer”, “Editor”, “Admin” as separate roles when they share the same goals creates noise. Use one role per distinct motivation. |
| Over-granular roles | Ten roles for a system with three distinct user types makes every feature and flow harder to write. |
| Roles without goals | A role that only has a label and no description provides no useful context to authors or developers. |
| Confusing roles with system accounts | ”The cron job” is not a role. Roles are about human (or human-like) actors with goals. For automated actors, consider whether a policy in a domain is more appropriate. |
| Orphaned roles | A role that no feature references and no flow uses is dead weight. Every role should appear in at least one feature or flow. |
Evolution
Roles change rarely compared to other document types. When you discover a new actor class (e.g., a third-party integrator joins your platform), add a role and update the roles attributes on affected features. If two roles converge over time, merge them and update references.