Yes it is confusing. The concept is users are assigned roles that have certain capabilities. Ideally, users are not directly assigned capabilities at all, they are inherited from the role they are assigned. In that view, it makes sense to add or remove capabilities to roles only.
The reality is you can add and remove capabilities to individual users. This was intended for special capabilities not defined in any roles. When you try to add or remove capabilities to a user that are role defined, the role definitions will eventually overrule what you attempted to do for the individual user. That’s why you need to deal with the role first.
Furthering the confusion is what is done to a role does not immediately get inherited by the current user, assuming it was supposed to happen. This is because the role’s capabilities are merged with the user’s capabilities when the user object is created, the role having precedence. If you then add a capability to a role, it is not reflected in the current user object unless you explicitly add it.
Be assured though that next time the user object is created, it will receive the new role capability. Since roles are typically changed during admin sessions or from activation hooks, the user affected by the change is not part of the current request, so it all works out.
In summary, focus on organizing capabilities by role, not by user. If you need to grant a special role to a particular user, it should not be any of the standard role capabilities. If for some reason the current user’s capabilities do not reflect the assigned role capabilities, recreating a fresh user object should resolve the discrepancy.
