Plainspoken

• 

  Live search under asker's permissions; Claude separates definition from usage, nothing stored.

Inspiration

Every workplace invents its own language, and almost none of it is ever written down.

A term gets defined once — casually, in a thread, years ago, by someone who has since left. Then it gets used a thousand times as though everyone was there for that conversation. "We're P0 gating until Thursday." "Does this touch the Bramble?" "Nobody do a Sandeep over the weekend."

If you were there, it's obvious. If you weren't, you have two options: interrupt a room of people to ask what sounds like a stupid question, or nod and hope.

Almost everyone nods.

That cost is not evenly distributed. It falls hardest on the people with the least standing to interrupt — the new hire in week two, the engineer whose first language isn't English and who is already spending energy on the literal words, the person for whom a 40-message thread of cross-talk is genuinely hard to parse. They are the ones who most need to ask, and the ones who can least afford to.

We built Plainspoken because that vocabulary already has an explanation. Someone did explain it, once. It's sitting in the workspace, findable, and nobody can find it.

What it does

It decodes your company's private language.

Ask it what a term means and it searches your workspace's own history for the message where somebody actually explained it — not the hundred messages where they merely used it — and answers in plain language, quoting the original and naming the human who said it.

a Kessler
A cascading failure: one service's retries overload its neighbours, which slow down and start retrying too, until the retry traffic is bigger than the real traffic. Kill the retries first, then fix the root cause.

Defined by Dev Patel in #incidents · see the original
⚠️ Used 12× across #eng-process, #incidents, #releases — and never written down anywhere.

That last line is the one people react to. The term is load-bearing, used constantly, and documented nowhere.

It turns a noisy thread into what you actually need.

A 32-message launch thread — engineers arguing about backlogs and rollouts, product worrying about design partners, three separate sub-arguments — becomes four plain sentences, the decision that was reached, and the single thing waiting on you:

One thing for you: Post the p99 latency numbers from Friday's load test before Thursday. You can post raw numbers; Ana will format them.

That request was one line, two-thirds of the way down, phrased casually. The person it was aimed at had been at the company for two weeks. He would have scrolled past it.

Impact

(Track: Slack Agent for Good — accessibility and economic opportunity.)

Undocumented vocabulary is a barrier that nobody put up on purpose and nobody can see, and it is not paid for equally.

It taxes the people with the least standing to interrupt. Asking "what does that mean?" costs a senior engineer nothing and costs a new hire in week two something real. So the new hire nods. So does the engineer whose first language isn't English, who is already spending energy decoding literal words before the private ones start. So does the person for whom forty messages of cross-talk is genuinely hard to parse. They need to ask most, and can afford to least — and the cost compounds: work redone, decisions misread, an action item scrolled past because it was phrased casually in someone else's dialect.

Plainspoken removes the need to ask. It doesn't make people braver, and it doesn't ask a team to write documentation it was never going to write. The explanation already exists — someone gave it, once, years ago. The agent just finds it, and hands it back with the name of the human who said it.

Three specific things it changes:

• Onboarding stops depending on courage. A newcomer can decode the room's language privately, in the moment, without an audience — and without being told to "just ask, we don't bite."
• Long threads stop hiding the one thing that matters. The digest surfaces what a thread is waiting on and who owes it. In our demo the request was one casual line, two-thirds down, aimed at a person who had been there two weeks. He would have scrolled past it.
• It admits what it doesn't know. When a term was never explained, it says so — used six times, never written down anywhere — which turns an invisible barrier into a visible one the team can actually fix.

The gate is real, and it decides who gets to contribute early and who spends their first months quietly guessing. Plainspoken opens it with an explanation the company already gave itself and then forgot.

How we built it

Slack's Real-Time Search API (assistant.search.context) is the engine, and the whole product rests on a single distinction:

A workspace mentions its jargon constantly, but defines it almost never.

Search returns both kinds of message mixed together. Separating them is the entire product. Two signals do it:

• Recency, inverted. The message that defines a term is usually the oldest one, so we sort ascending and read from the beginning of the workspace's memory rather than the end.
• The surrounding conversation. include_context_messages returns the messages on either side of every hit. A definition gets reacted to — "this is the single most useful thing anyone has written in this channel." A usage is just the term doing its job in a sentence.

A cheap heuristic ranks the candidates; Claude Sonnet 5 then picks the message that actually teaches the term and rewrites it plainly. Crucially, it is explicitly permitted to answer "nobody ever explained this" — which is a true and useful thing to hear. It never supplies a definition from world knowledge. A term can mean something entirely different inside a company than outside it, and being confidently wrong about a company's private vocabulary is worse than admitting you don't know.

Everything runs on Bolt for Python in Socket Mode.

Nothing is stored

The Real-Time Search API's terms say it plainly: "You must not store or copy any data retrieved from this API."

Which means the obvious architecture — copy the workspace into a vector store and retrieve from that — is not permitted. We think that constraint is correct, and we leaned into it rather than around it.

Plainspoken has no index, no vector database, no cache. Every answer is retrieved live at the moment of asking, used to answer that one question, and dropped. Nothing is written to disk.

This is not only a compliance story. A RAG index of a company's Slack is a second, unguarded copy of everything that company has ever said — and it does not honour the permissions of the original. Because Plainspoken searches under the asker's own access, a person who cannot see a channel cannot learn its vocabulary from this agent. Privacy is inherited from Slack rather than reimplemented, badly, by us.

Challenges we ran into

• The search API cannot be called from a script. With a bot token it requires an action_token that only arrives inside a live message or app_mention event. Slack is enforcing "a human asked for this, just now, and this search runs with their permissions." It meant we could not test the core feature in isolation — the agent had to exist first.
• Bot-authored messages are excluded from search by default. Our demo workspace is seeded, so every message in it is bot-posted. Had include_bots not surfaced them, the demo would have had nothing to search. This was the single biggest risk in the build.
• Don't quote your search query. Searching the literal phrase "a Kessler" returns 2 messages. Searching Kessler returns 12 — because the real usages say "kesslered" and "going kessler". Strip the article, drop the quotes, let Slack's stemming work.
• The agent was quietly unhelpful in the way that mattered most. Our first digest of the launch thread said "nothing here is waiting on you" — while its own summary, two lines above, said Alex owed the latency numbers. It was technically right (the reader wasn't Alex) and practically useless. Now it surfaces what a thread is blocked on and who owes it, because "what is this stuck on?" is the most useful fact in any long thread.

What we learned

The hard part was never retrieval. It was teaching an agent the difference between a sentence that uses a word and a sentence that teaches it — and then being willing to have it say "I don't know," which is the answer that makes every other answer trustworthy.

What's next

Company-specific vocabulary is a gate. Plainspoken doesn't ask people to climb it or pretend they already have — it just opens it, using an explanation the company already gave itself and then forgot.

Next: a passive glossary that spots terms used constantly and defined nowhere, so a team can see its own undocumented vocabulary before the next new hire has to nod along to it.

Built With

• anthropic
• claude
• claude-sonnet
• cron-job
• python
• render
• slack
• slack-bolt
• slack-real-time-search-api
• socket-mode