diff --git a/src/main/java/net/hostsharing/hsadminng/rbac/generator/RbacRbacSystemRebuildGenerator.java b/src/main/java/net/hostsharing/hsadminng/rbac/generator/RbacRbacSystemRebuildGenerator.java
index 640a8b85..7350280d 100644
--- a/src/main/java/net/hostsharing/hsadminng/rbac/generator/RbacRbacSystemRebuildGenerator.java
+++ b/src/main/java/net/hostsharing/hsadminng/rbac/generator/RbacRbacSystemRebuildGenerator.java
@@ -25,11 +25,26 @@ class RbacRbacSystemRebuildGenerator {
                 --changeset RbacRbacSystemRebuildGenerator:${liquibaseTagPrefix}-rbac-rebuild endDelimiter:--//
                 -- ----------------------------------------------------------------------------
 
+                -- HOWTO: Rebuild RBAC-system for table ${rawTableName} after changing its RBAC specification.
                 --
                 -- begin transaction;
                 --  call base.defineContext('re-creating RBAC for table ${rawTableName}', null, <<insert executing global admin user here>>);
                 --  call ${rawTableName}_rebuild_rbac_system();
                 -- commit;
+                --
+                -- How it works:
+                -- 1. All grants previously created from the RBAC specification of this table will be deleted.
+                --    These grants are identified by `${rawTableName}.grantedByTriggerOf IS NOT NULL`.
+                --    User-induced grants (`${rawTableName}.grantedByTriggerOf IS NULL`) are NOT deleted.
+                -- 2. New role types will be created, but existing role types which are not specified anymore,
+                --    will NOT be deleted!
+                -- 3. All newly specified grants will be created.
+                --
+                -- IMPORTANT:
+                -- Make sure not to skip any previously defined role-types or you might break indirect grants!
+                -- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+                -- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+                -- of this table would be in a dead end.
     
                 create or replace procedure ${rawTableName}_rebuild_rbac_system()
                     language plpgsql as $$