A retrospective Slack bot for the 2020s.
This is a bolt-js port of Remy's Retrobot, which was in turn inspired by PebbleKat's Retrobot.
For this to work, you'll need to create a Slack bot.
You can use the resources/app-manifest.yml
file to quickly create a new Slack app in your workspace. Don't forget to update the request_url
field with the URL of your deployed app (see below about deploying to Heroku).
Once you have created and installed the new app in your workspace, you should record its bot token (from the OAuth & Permissions
page) and signing secret (from the Basic Information
page).
Follow these steps to manually create the app:
- Select to create a new Slack app from scratch
- Record the app's
Signing Secret
from theBasic Information
page (this is yourSLACK_SIGNING_SECRET
) - In the
OAuth & Permissions
page:- Add the following scopes under the
Bot Token Scope
section:- app_mentions:read
- channels:history
- channels:read
- chat:write
- dnd:read
- im:history
- reactions:read
- users:read
- Under the
OAuth Tokens for Your Workspace
section, clickInstall to Workspace
(follow the instruction there) - Record the
Bot User OAuth Token
that was created after the app insllation (this is yourSLACK_BOT_TOKEN
)
- Add the following scopes under the
- In the
App Home
page, under theShow Tabs
section, check theAllow users to send Slash commands and messages from the messages tab
checkbox - You can now deploy the app to Heroku using the two keys (see below about deploying to Heroku)
- In the
Event Subscriptions
page:- Enable the events toggle; enter the URL of your bot's deployment and add
/slack/events
(e.g.https://my-cool-retrobot.herokuapp.com/slack/events
) - In the same page, subscribe to the following bot events:
- app_mention
- message.channels
- message.im
- Enable the events toggle; enter the URL of your bot's deployment and add
- You'll need to reinstall the app - do it now (in the
Install App
page)
It's best to just install Retrobot on Heroku, where it can live inside a free web dyno and woken up as required. You can do it with a single click on this button below (opens in the same tab, so Cmd/Shift-click it):
You'll need to supply two env vars from your newly-created bot:
- SLACK_BOT_TOKEN
- SLACK_SIGNING_SECRET
You can run this project locally and provide Slack with an external URL (use ngrok).
- Create a new public channel that will be dedicated to retrospectives
- Invite everyone who should take part in these sessions
- Add Retrobot (as an integration) to this channel
You're all set!
Retrobot can manage multiple retro sessions, each from its own channel.
Important: If a user is a member of two channels that are both running a session at the same time, this user's private interaction with Retrobot (giving feedback) will land randomly in either sessions. To avoid this embarrasing (if potentially funny) situation, that user can leave the unwanted channel before the session starts (and come back to it later).
Retro sessions have three parts:
- Gathering feedback from everyone
- Up-voting the messages that everyone would like to discuss
- List the top up-voted messages, opening up a way to start talking about the important issues
Appropriately, Retrobot has three phases:
-
Type
@retrobot start
to start gather feedback from everyone who is (1) a member of this channel; (2) isn't away; and (3) not in DnD (Do not Disturb) mode.- Everyone will get pinged by Retrobot in a DM
- At this point, each person sends feedback privately (through direct message) to Retrobot
-
Type
@retrobot stop
after a short while (give everyone 5-10 minutes to give some prope) - this will print all the feedback from everyone, split into two lists: "Worked Well" and "Needs Work"- Now everyone should up-vote (๐) on the most important items they'd like to discuss
-
Once everyone has voted, type
@retrobot sum [N]
to print the first[N]
messages (defaults to 3) that were up-voted.- The retro session is now finished
- You can start discussing the items with the team, and sum up the discussions and any action items in each item's thread, for later follow-up
@retrobot help
will print a list of all the commands it supports@retrobot wake up
just to ping Retrobot, in case it was sleeping (e.g. in a Heroku free dyno)@retrobot status
will provide you with the status of the retro session in this channel, if any is running@retrobot channels
will list all the channels where an active retro session is currently runnning@retrobot terminate session
will unceremoniously end the current session, leaving nothing behind (dangerous, but useful for reseting a session without going through all the motions)