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

# Decisions and incidents

> How Synapse recognises decision records and incident write-ups, and two conventions that make agents use them well, Consumers and Origin

Your agents recall decisions, RFCs and incident reviews from the knowledge sources an admin has designated (see [Set up your team](https://docs.synheart.ai/synapse/admin-setup.md)). A few conventions in those documents help agents find the right one and make better use of it.

## What counts as a decision

In a connected repository, Synapse treats a Markdown file as a decision when:

* its file name starts with `ADR` or `RFC`, or it sits in a folder whose name starts with `adr` or `rfc` (such as `docs/rfcs/`); or
* its front matter declares it:

```yaml theme={null}
---
decision: true   # also: adr, rfc. Use false to opt a file out
---
```

`recall`, `why` and `related_context` cite decisions with their source type (`decision`, `adr` or `rfc`). When a change touches code that a decision governs, `related_context` returns that decision as **governs**.

## Consumers: say who reads it

Add a **Consumers** section to an ADR that defines a table, a column, an API field or an event. In it, list who reads that name. Readers outside the repository matter most: mobile apps, partners, other services and data exports.

```markdown theme={null}
## Consumers

- `users.legacy_email`: billing-reconciler nightly job (Finance), partner export to Acme (CSV, weekly)
- `GET /v1/me` → `fullName`: iOS app ≥ 4.2 and Android app ≥ 3.9 (shipped clients; can't be changed in place)
- `order.completed` event: analytics pipeline, fulfilment service
```

* **Name things exactly.** Use the exact name as it appears in code, such as `users.legacy_email` or `fullName`.
* **One line per name.** On each line, give the name, who reads it, and anything that makes a change costly, such as shipped app versions or a contract with a partner.

**Why it helps.** ADRs are indexed. When a change or an agent's instruction mentions one of those names, Synapse recalls the ADR with its Consumers list, so the agent sees who would break and checks with you first.

`related_context` also searches your organization's other connected repositories for code that still uses a name the change removes or renames. That search can't see readers outside your connected repositories, such as a partner's integration, an app in an unconnected repository, or a spreadsheet someone exports. The Consumers section covers those.

## Incidents

Synapse recognises postmortems and incident reviews as **incidents**, and cites them with `source_type: "incident"` in `recall`, `why` and `related_context`. A document is treated as an incident when:

* **In a repository:**
  * it sits under a folder named `incidents/`, `postmortems/` or `post-mortems/`;
  * its title has an incident id such as `INC-204`, or the words "Postmortem" or "Post-incident review"; or
  * its front matter says `incident: true`.
* **In Notion or Google Drive:** its title follows the same title rule. Access still follows the source: an incident is only shown to people who can read it there.

Some documents are never counted as incidents:

* templates, README pages and index pages;
* ADRs and RFCs, which always stay decisions;
* files with `incident: false` in their front matter.

### Origin: link a decision to its incident

When a decision was made because of an incident, name the incident in the decision record:

```markdown theme={null}
# ADR-031: Rate-limit the public ingest API

Origin: INC-204
```

Synapse links the decision to the incident write-up whose id matches. Each citation of the decision then carries an `origins` list, for example `origins: [{ source_type: "incident", id: "INC-204", title, url }]`. An agent that is told "this decision governs your change" also sees the outage behind it. The link appears shortly after the documents next sync, and you only see an incident in `origins` if you can read it.

> [!NOTE]
>
> Incident recognition, Origin links and the search of other repositories for consumers arrive in upcoming Synapse releases. Until then, postmortems are cited as ordinary documents and a Consumers section works through recall alone.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.