Technical Spec

/closedloop-spec the Slack integration

​

Arguments

​

What you get

SLACK INTEGRATION: TECHNICAL SPEC

PRD REFERENCE
  When a channel goes quiet mid-rollout, teams cannot tell whether the
  integration broke or nobody posted. 14 customers, 3 of them blocked deals.

CONTEXT AND SCOPE
  Follows the connector shape already in src/connectors/zendesk/, which
  polls on a cursor and writes through the shared ingest path
  (ingest.ts:212).

DESIGN, KEY TRADE-OFF
  Events API over polling. Slack pushes each message as it lands, so the
  connector holds no cursor and never runs a catch-up read.

ALTERNATIVES CONSIDERED
  Per-channel polling, the shape src/connectors/zendesk/ already uses.
  Rejected: a workspace with 400 channels exhausts the rate limit inside
  one sync window, so the cursor never catches up.

ACCEPTANCE CRITERIA
  Given a connected workspace where the bot has not been invited to any
  channel, when the integration page loads, then it shows the invite
  step rather than an empty list.

OPEN QUESTIONS
  None. Bot-invite timing is answered at oauth/callback.ts:128.

​

Sections

​

Why this format

• Trade-offs, not steps. A decision with no real alternative is skipped, not documented.
• Alternatives Considered answers “why didn’t you just…” before review does. Most templates drop it.
• Problems surface while changes are still cheap, because the argument happens before the code.
• Security, privacy and observability get decided rather than discovered.
• The doc is what whoever inherits the system goes looking for.

​

What grounds it

• Your repo. Finds files of the same shape, your data model and migration conventions, your route handlers, your test style. Acceptance criteria come out in the format your team already uses. You pick which repos it searches.
• Customer evidence. No evidence for the feature and it stops, rather than writing a confident spec on an empty PRD reference.
• Line numbers over open questions. If the code answers it, it is answered with a file and line.

​

Two rules that catch the most in review

• A content type customers expect and are not getting becomes an explicit non-goal, not a buried edge case.
• Any step between “connected” and “data appears” must appear in the system flow. That is where first-time users land on an empty screen.