---
name: dorsal
description: Current field evidence from AI builders, repositories, docs and research, read over HTTP from the Dorsal graph. Use when the user starts a message with the word "dorsal", asks to check a technical decision against current evidence, or asks what builders report about a library, model, tool, MCP server, agent framework, bug or recent change.
---

# Dorsal

Dorsal is a live graph of what builders ship, break and fix: dated events with source links, named
objects (products, models, repos, methods, problems), and documentation passages. You call it with the
bundled script. You do the reasoning; Dorsal only returns records.

## Setup

- The script reads the key from `DORSAL_API_KEY` or from `~/.dorsal/api-key`. If it reports `setup_error`,
  pass on its message. Never ask for the key in the chat and never print or read the key file.
- `DORSAL_API_URL` is optional. The default is `https://api.dorsal.us`.
- The script is `scripts/dorsal.sh` in this skill's directory. Call it by its full path.

## Privacy

Everything you send leaves the machine. Write every query yourself as a short search phrase, under 25
words, in public names: products, models, libraries, versions, methods and error types.

Never send:
- code, or names from the user's code: functions, classes, variables, tables
- file paths, file names or folder names from the user's project
- keys, tokens, passwords, or any value from .env or config files, such as hosts, URLs, ports and database names
- history: commit messages, branch names, author names or emails, shell history, and text copied from this
  conversation, terminal output or tool results
- private repository names, internal names, customer data or proprietary requirements

Quote only the public part of an error: the library, the error type or code, and the public message. Name a
setting by its public role ("Postgres connection URL"), never by its value. Examples:
- "our billing service on Postgres 16 times out under PgBouncer" → `PgBouncer transaction pooling timeouts Postgres 16`
- `TypeError: Cannot read properties of undefined (reading 'id') at /Users/sam/acme/src/invoices/route.ts:42`
  → `Next.js route handler TypeError cannot read properties of undefined`
- `P1001: Can't reach database server at db-prod.acme.internal:5432` → `Prisma P1001 cannot reach database server`

`dorsal.sh` checks every request on this machine before sending it. When it prints `privacy_block`, nothing
was sent: rewrite the query in public terms and retry once. Never send the request another way.

## Routing

- Message starts with "dorsal audit": run `dorsal.sh protocol audit` before reading any local work,
  and follow the audit method it returns exactly. If the call fails, stop and report the error; never
  audit from a remembered method.
- Any other message that starts with "dorsal": run `dorsal.sh protocol dorsal investigate` (use `improve`
  for "dorsal improve …") and follow the contract it returns.
- User asks to verify or check a decision: run `dorsal.sh protocol decision-verification` and follow it.
- Any other question: use the default method below.

Contracts name MCP tools. Map them: getSummaries → `summaries`, getSet → `set`,
getNeighbors → `neighbors`, with identical JSON arguments. getAuditProtocol → `protocol audit <phase>
<sections>`, with sections comma-separated: `protocol audit audit memory` fetches the memory section, and
`protocol audit fix` fetches the fix phase. The script sets the client.

## Default method

1. Search with 2 or 3 complementary queries, each with `"total": 10`:
   current guidance, results and failures in practice, and the strongest case against the likely answer.

   ```bash
   S=<this skill's directory>
   "$S/scripts/dorsal.sh" summaries '{"query": "PgBouncer transaction pooling prepared statements", "total": 10}'
   ```

   Each call returns `results` with `kind` = `event`, `object` or `documentation_chunk`, plus `id`,
   `description`, `url` and `timestamp`. Filters: `event_types` (use `["capability_observed"]` for measured
   model results), `object_types`, `sources` (use `["docs"]` for documented product behavior),
   `since` / `until` (ISO dates). For a long result, pass `page_size` and follow `next_cursor`.
   Ids are labels for fetching records. Read an event's type from its `event_type` field, never from its id.

2. Fetch the records that decide the answer, usually 3 to 10 ids, at most 25 per call:

   ```bash
   "$S/scripts/dorsal.sh" set '{"ids": ["<id>", "<id>"]}'
   ```

3. Only when relationships matter (makers, alternatives, dependencies, a model's other results), traverse
   one named object. Set `include_events` to list its source-linked events:

   ```bash
   "$S/scripts/dorsal.sh" neighbors '{"query": "Claude Code", "include_events": true, "total": 20}'
   ```

   `{"error": "no object matched"}` means the name is unknown: take the exact name or id from a
   `summaries` result.

For a body with quotes, pass it on stdin instead of as an argument:

```bash
"$S/scripts/dorsal.sh" summaries <<'JSON'
{"query": "agent can't resume after context compaction", "total": 10}
JSON
```

## Reporting

- Lead with the answer. Support each claim with records you fetched, cited by source URL and date.
- Objects identify named things. Prove behavior with events or documentation passages.
- Say when evidence is thin, old or one-sided, and show the counterevidence you found.

## Errors

Non-200 responses print `{"error": {"type", "message"}}` on stderr and the script exits non-zero.
When you pipe the output into `jq`, the error still shows; read it before retrying.

- `privacy_block` (exit 3, or HTTP 400 from the server): the request held a path, key, URL, setting, private
  host, or a name, branch, commit subject or .env value from the user's repository. On exit 3 nothing was
  sent; on HTTP 400 the server refused it and stored nothing. Rewrite the query in public terms and retry once.

- `invalid_request_error` (400): the message names the field and the fix. Fix the body and retry once.
- `authentication_error` (401): the key is missing, wrong or expired. Tell the user to get a new one at
  https://godorsal.com/docs/skill; do not retry.
- `rate_limit_error` (429) or `overloaded_error` (503): the script already retried twice. Wait a minute or
  report it.

Full field reference: [references/api.md](references/api.md).
