Skip to main content
Your agents recall decisions, RFCs and incident reviews from the knowledge sources an admin has designated (see Set up your team). 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:
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.
  • 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.
When a decision was made because of an incident, name the incident in the decision record:
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.
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.