diff --git a/doc/hubot-migration.md b/doc/hubot-migration.md
new file mode 100644
index 0000000..9f51a42
--- /dev/null
+++ b/doc/hubot-migration.md
@@ -0,0 +1,30 @@
+# Hubot migration — waiting on
+
+Deferred/blocked items from moving botka (IRC) and hal8000 (XMPP) off the
+retired `nodejs-4` onto `nodejs-5`.
+
+## Upstream: @xmpp/stream-management crash
+
+`ackQueue()` dereferences `undefined` when the server acknowledges more stanzas
+than are still queued, so hal8000 logs
+`TypeError: Cannot read properties of undefined (reading 'stanza')` on every
+(re)connect. Caught by the client, harmless.
+
+Fix is upstream: https://github.com/xmppjs/xmpp.js/pull/1119 (guard the empty
+queue). `kosmos/hubot-xmpp` logs the error stack trace meanwhile.
+
+## Upstream: xmpp.js CI is red
+
+The prosody e2e step fails to load `/certs/localhost.key` (environmental
+regression); `main` fails on every Node version. Unrelated to our changes, but
+it blocks PR CI there.
+
+## Upstream: xmpp.js jest testMatch regression
+
+`jest.config.cjs` sets `testMatch: ["**/test/*.js"]`, dropping
+`...defaults.testMatch`, so package-root `*.test.js` files are no longer run.
+#1119 works around it by moving one file.
+
+## Deferred features
+
+- botka as an XMPP bot