> ## Documentation Index
> Fetch the complete documentation index at: https://closedloop.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Technical Spec

> Generates a Google design doc: context and scope, goals and non-goals, the design and its trade-offs, alternatives considered, acceptance criteria.

Two people read a spec. The reviewer, who wants to know why you did not just do the obvious thing, and the engineer who picks it up on Monday and finds the one interesting question still open.

Write it from what customers said and what the repo already does:

```
/closedloop-spec the Slack integration
```

```
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.
```

## Arguments

| Argument                               | Required | Default                    |
| -------------------------------------- | -------- | -------------------------- |
| The feature or topic                   | yes      | asks if you leave it out   |
| A hint about where in the repo to look | no       | asks which repos to search |

## Sections

Google's design doc format: context and scope, goals and non-goals, the design, alternatives considered. Ours adds acceptance criteria, edge cases, rollout and open questions.

## 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.