WHISTLE-1510: spec and formmatting updates