{% explanation %}

#caching#performance

Why DBML over Prisma schema

Attributes

Parameter	Type	Required	Description
`type`	hint \| details	✓	Rendering variant: 'hint' renders as a branded callout; 'details' renders as a collapsible disclosure element
`audience`	string	—	The target group (e.g., 'frontend', 'backend', 'qa', 'ops'). Required when type='hint'.
`tags`	string	—	Space-separated labels for filtering (e.g., 'security performance')
`summary`	string	—	Label override for hint; text of the <summary> element for details. Defaults to audience when absent.
`scope`	string	—	Space-separated list of visibility scopes (defaults to 'public agent')

Valid Parent Contexts

This tag is valid inside: {% domain %}, {% feature %}, {% flow %}, {% blueprint %}, {% role %}, {% story %}, {% manifest %}, {% milestone %}, {% surface %}, {% tour %}, {% changeset %}

Rules

Rule	Force	Realm	Reference	Description
`explanation-type-required`	must	global	—	Always specify . The attribute has no default and the compiler will reject tags without it. convention
`explanation-hint-audience`	must	global	—	When , provide . The compiler emits a validation warning when it is absent. convention
`explanation-non-normative`	must	global	—	Use for advice and context, not requirements. If something must be done, use or . convention
`explanation-inside-root-tag`	must	global	—	Place tags inside the root document tag. They are collected and rendered near the top of the page regardless of their position in the source. conventionplacement

The explanation tag provides contextual information that isn’t a hard requirement or a policy. Use type="hint" for audience-targeted implementation advice rendered as a callout. Use type="details" for supplementary background or rationale that readers can expand on demand.

The body supports full Markdown: paragraphs, lists, code fences, bold, links. Content is rendered correctly in the public site via renderBlocks. The agent bundle receives a plain-text body field.

Agent bundle shape

{
  "explanations": [
    {
      "type": "hint",
      "audience": "backend",
      "tags": ["caching", "performance"],
      "summary": null,
      "body": "Use a write-through cache for all bookmark mutations..."
    },
    {
      "type": "details",
      "audience": null,
      "tags": [],
      "summary": "Why DBML over Prisma schema",
      "body": "DBML is model-only and has no runtime coupling..."
    }
  ]
}

{% explanation type="hint" audience="backend" tags="caching performance" %}
Use a **write-through cache** for all bookmark mutations:

- Invalidate on `bookmark:deleted`
- TTL: 5 minutes
{% /explanation %}

{% explanation type="details" summary="Why DBML over Prisma schema" %}
DBML is model-only and has no runtime coupling to the ORM. This keeps the spec
layer independent of the implementation stack — a schema change in the spec does
not require a migration until the team decides to act on it.
{% /explanation %}