Troubleshooting and FAQ
It's quiet, it's generic, it ranked on the wrong metric, plus the questions everyone asks.
It isn't responding
| Symptom | Cause | Fix |
|---|---|---|
| No 👀, no reply, nothing | It isn't in the channel | /invite @Surface Marketing Agent |
| 👀 appears, then a Connect card | Surface isn't connected, or the grant expired | Click Connect Surface. /surface status confirms |
| "In this channel I only take questions from the … team" | A Slack Connect channel that hasn't been opened | Someone at the installing workspace runs /surface shared open, or ask in an internal channel |
| "This workspace has hit today's question limit" | 200 questions in 24 hours | Wait for the rolling window, or ask a Surface admin to raise it |
| 👀 but silence on a thread reply | It judged the message wasn't for it | Working as designed. @-mention it to be sure |
The answer wasn't what I wanted
| Symptom | What's going on | Fix |
|---|---|---|
| The draft reads generic | It found no voice rules, and it will have said so in one line | Tell it your voice rules once ("remember: …"), or point it at a Vault doc, then re-ask |
| It ranked on pageviews, you wanted pipeline | Sometimes the pipeline metric really is flat, and it'll say so | Ask for the metric by name: "rank by meetings booked" |
| It asked which form you meant | No form matches the name you used | Use the exact name from Surface, or pick from the list it offered |
| It gave totals, you wanted a rate or a trend | It answers what was asked, literally | Ask for "the rate, and the week-over-week change" |
| It stopped halfway through something big | Hit the step or cost ceiling | Click Run it in the background, or narrow the range |
| It's off down the wrong path and still going | A turn that has gone somewhere nobody wants | Hit Stop on the status line. Nothing is changed by a stopped turn |
| It got something wrong | It happens | Correct it in the thread. Corrections are saved to memory |
Files
- "Couldn't read [file]": it names what it skipped and why.
.xlsx, PDFs and Slack Lists aren't readable; export to CSV. - More than 8 images: it reads 8 and names the rest. Split into two messages.
- A file from earlier in the thread: still works. Just refer to it.
FAQ
›Can it see all our Slack messages?
It reads the thread you're in, or the current channel's recent history if you ask it to. It is not indexing your Slack.
›Does everyone in the workspace share one memory?
Yes, that's the point. Channel-scoped notes exist for project-specific context.
›Can it change our data without asking?
No. Every change is an approval card. Background jobs are read-only entirely.
›Who can approve a change?
Whoever asked for it, or any Slack workspace admin.
›Why is it asking me to rate an answer?
Roughly one answer in five carries 👍 / 👎 and a saved 5m · 30m · 2h row. It's sampled deliberately, because buttons under every answer read as being asked to rate a conversation.
›How do I keep a good answer?
If it's a document rather than a number, a Save in Vault button appears
under it. One click files it in your Surface Vault as a dated Markdown doc
under slack/, and it reads its own Vault before drafting, so saving
compounds. Anyone in the workspace can click it; it only ever creates, never
overwrites.
›Why does it write so little?
60 words by default, on purpose. Drafts, digests and scheduled posts are exempt: ask it to write something and it writes the whole thing.
›Can we point it at a different Surface environment?
/surface disconnect, then connect again and pick.
›Does it work in private channels?
Yes. Invite it.
›What happens if we uninstall?
It stops immediately. Install history is kept for support; reinstalling restores the workspace.