Taking inspiration from Doom, I'm using a "local leader" setup to bind mode-relevant commands, like:

(general-create-definer local-leader-def :states '(normal visual motion) :prefix "SPC m") 

This way, I can do stuff like (local-leader-def :keymaps 'ledger-mode-map "r" 'ledger-report), making it super easy to access the report when I'm in ledger mode with a quick SPC m r. However, this approach starts to break down in more complicated scenarios, such as:

(local-leader-def :keymaps 'org-mode-map "a" '(:ignore t :wk "attachments") "a a" 'org-attach "a d" '(:ignore t :wk "deletion") "a d d" 'org-attach-delete-one "a d G" 'org-attach-delete-all "r" '(:ignore t :wk "refile") "r r" 'org-refile) 

First, this is kind of ugly - Org has a ton of features, and I try to use a lot of them, so some of my key sequences can get pretty long. I end up retyping the same prefix many, many times, sometimes with multiple layers of the (:ignore t :wk "foo") trick (as seen above).

Second, (and more annoyingly, IMO) doing it this way "shadows" the which-key description for modes which share a prefix. That is, if I'm in ledger mode and type "SPC m", it yields the suggestion "r -> refile" instead of "r -> ledger-report" as it should.

I've been futzing around with general's ":prefix-command" and related facilities to try and figure out a way of avoiding this second issue, but so far I haven't been able to get anything to work. Since my current strategy is ad hoc and not based on any best practices I'm aware of, I thought I'd ask here if there's a canonical/idiomatic way of using general's capabilities to define groups of similarly-prefixed commands without breaking which-key.

(Also, why is there a distinction between :prefix-command and :prefix-map? When do you need to store a keymap as the value of a function instead of as variable or vice versa?)