Role extension
Extends an existing role document. Roles change less often than domains or features, but when they do, the changes have broad impact — every feature that references this role may need review.
Phase 1 — Load Current State
Fetch the role and identify its consumers:
get_document("role/{id}")Inventory the existing:
- Responsibilities: what is this role accountable for?
- Goals: what does this role need to accomplish?
- Feature links: which features reference this role?
- Restrictions: what is this role explicitly NOT allowed to do?
Phase 2 — Classify the Change
| Change type | Key question | Impact |
|---|---|---|
| New responsibility | Does this expand what the role does, or refine an existing responsibility? | May require new feature links |
| New feature link | Does the feature’s roles attribute already include this role? | Feature may need updating too |
| Access restriction | Is this a new restriction, or a refinement of an existing one? | Affects all features the role uses |
| Description update | Does the change alter the role’s identity, or just clarify it? | If identity changes, consider creating a new role instead |
| Goal change | Is the goal still achievable with the current feature set? | May signal feature gaps |
Identity check: If the change significantly alters who this role represents (e.g. “viewer” becoming “editor”), create a new role instead of extending — roles represent people, and changing identity breaks existing references.
Phase 3 — Apply Changes
For each change:
- Responsibilities — add new entries or refine existing ones. Verify the responsibility doesn’t overlap with another role’s explicit responsibilities.
- Feature links — verify the feature exists in
content/features/. If the feature doesn’t list this role in itsrolesattribute, note that the feature will also need updating. - Restrictions — state what the role must NOT be able to do. Restrictions are as important as capabilities.
- Goals — update or add goals. Each goal should be achievable given the role’s linked features.
Phase 4 — Impact Check
After drafting changes, check for downstream impact:
- List all features that reference this role
- For each: does the change affect how the feature should handle this role?
- If the role gained new responsibilities that imply new feature requirements, flag them — they become inputs for
feature.extendruns
Present the impact assessment alongside the diff.
Phase 5 — Draft & Confirm
Present only the changed sections as a diff for confirmation, plus the impact assessment from Phase 4.
Write the updated file only after explicit confirmation.
Output: content/roles/{id}.role.mdoc (overwrite)
Do’s and Don’ts
Do:
- Fetch the existing role document and inventory it before proposing changes
- Check for identity-altering changes and recommend creating a new role instead
- Verify new feature links point to existing features in
content/ - Note downstream impact on features that reference this role
- Present only changed sections as a minimal diff for confirmation
Don’t:
- Don’t change the fundamental identity of the role — create a new role instead
- Don’t rewrite unchanged sections or reformat existing content
- Don’t add feature links without verifying the feature exists
- Don’t skip the impact check — role changes can ripple across many features
- Don’t skip confirmation even for small changes like description updates
Definition of Done
- Existing role loaded and inventoried before changes
- Identity check passed (no fundamental identity change)
- Draft diff presented to user for confirmation
- Impact assessment of affected features presented
- Updated document written with only changed sections modified
- All feature links verified against
content/features/ - All cross-references resolve to existing documents
-
pnpm compilesucceeds