Skip to content

Panel

A bounded region that holds anything — fields, prose, or other blocks. @panel does almost everything the named cards do, and takes the same parameters: @risk, @decision, @assumption, @persona, @metric and @callout are presets that set its label, badge and accent for you. Reach for @panel when none of them fit, or when a document should not read as jargon.

Written as @panel, @decision, @risk, @assumption, @persona, @metric, @callout — one look under several names, so they always match.

A bounded region that clears the ruling and holds anything: fields, prose, or other blocks. This is the general container — @decision, @risk, @assumption and @persona are presets over it, so the PM vocabulary is available but never required. Use @panel directly when none of the presets fit, or when a document should not read as jargon.

Other blocks can go inside it. What goes inside what

@panel(label="Risk" badge=high accent=alert title="Churn among small teams")
  mitigation: Grandfather existing plans for 12 months.

Riskhigh

Churn among small teams

mitigationGrandfather existing plans for 12 months.
Settings
SettingTypeRequiredDefaultMeaning
labelstringno—Small uppercase kicker above the title, e.g. “Risk”. Omit for an unlabelled panel.
titlestringno—The panel’s heading.
badgestringno—Short status chip beside the label, e.g. “accepted” or “high”.
accentneutral · alert · positive · info · quietnoneutralColour treatment. alert marks something needing attention; quiet drops the fill entirely.
More examples
@panel(title="Anything can go inside")
  A panel holds prose, fields, or other blocks.

  @metric(name="WAU" value="1,240")

Anything can go inside

A panel holds prose, fields, or other blocks.

metric

WAU

1,240

An architectural decision block: context, choice, consequences. Body uses key: value lines.

Other blocks can go inside it. What goes inside what

@decision title="Adopt event sourcing" status=accepted date=2026-09-17
  context: Writes are bursty, reads need projections
  choice: Event store with CQRS
  consequences: Simpler writes, eventual consistency on reads

decisionaccepted

Adopt event sourcing

contextWrites are bursty, reads need projections
choiceEvent store with CQRS
consequencesSimpler writes, eventual consistency on reads
Settings
SettingTypeRequiredDefaultMeaning
titlestringyes—Short name for the decision.
statusproposed · accepted · deprecated · supersedednoacceptedDecision status.
datestringno—Date the decision was made, e.g. 2026-09-17.

Risk entry with severity level and optional mitigation. Body is the risk description; mitigation is a keyed field.

Other blocks can go inside it. What goes inside what

@risk level=high title="Syntax awkwardness drives churn"
  New users may bounce in the first hour if the syntax feels like work.
  mitigation: Strong welcome file, interactive tour, sensible defaults.

riskhigh

Syntax awkwardness drives churn

mitigationStrong welcome file, interactive tour, sensible defaults.

New users may bounce in the first hour if the syntax feels like work.

Settings
SettingTypeRequiredDefaultMeaning
levellow · medium · high · criticalnomediumSeverity.
titlestringno—One-line risk name (shown as a heading).

Assumption entry. A thing believed to be true that the plan depends on. Body is the assumption; validation is how to test it.

Other blocks can go inside it. What goes inside what

@assumption title="PMs will learn a syntax" confidence=medium
  Code-adjacent PMs will invest an afternoon to learn .jot if the output is good enough.
  validation: 3 real PMs try the welcome file unaided; 2/3 produce a usable doc.

assumptionmedium

PMs will learn a syntax

validation3 real PMs try the welcome file unaided; 2/3 produce a usable doc.

Code-adjacent PMs will invest an afternoon to learn .jot if the output is good enough.

Settings
SettingTypeRequiredDefaultMeaning
titlestringno—One-line assumption name.
confidencehigh · medium · lownomediumHow sure we are.

Persona card. Body uses key: value lines for structured fields. Keys are freeform — use whatever fields suit the persona (name, role, goal, frustration, quote, tools, context). Any other line is a description, shown under the fields. Renders as a styled card with the name prominent.

Other blocks can go inside it. What goes inside what

@persona name="Marta, the systems PM"
  role: Platform PM at a mid-size fintech
  goal: Sketch data relationships inside the spec, not in a separate tool
  frustration: Notion has no star schema view, Miro loses sync with the doc
  tools: VS Code, Datadog, dbt, Notion (reluctantly)
  quote: "I just want the diagram next to the paragraph that explains it."
  Writes every spec herself, and keeps it open in VS Code all day.

persona

Marta, the systems PM

rolePlatform PM at a mid-size fintech
goalSketch data relationships inside the spec, not in a separate tool
frustrationNotion has no star schema view, Miro loses sync with the doc
toolsVS Code, Datadog, dbt, Notion (reluctantly)
quote“I just want the diagram next to the paragraph that explains it.”

Writes every spec herself, and keeps it open in VS Code all day.

Settings
SettingTypeRequiredDefaultMeaning
namestringyes—Persona name or archetype label.
imagestringno—Not built yet: does nothing for now. Path or URL to an avatar image.

KPI / metric block. Renders as a compact card with the metric name, current value, target, and optional trend.

Other blocks can go inside it. What goes inside what

@metric name="Weekly active users" value="1,240" target="2,000" trend=up status=on-track
  Growing 8% week-over-week since the playground launched.

metricon-track

Weekly active users

1,240↑target 2,000

Growing 8% week-over-week since the playground launched.

Settings
SettingTypeRequiredDefaultMeaning
namestringyes—What the metric measures.
valuestringno—Current value.
targetstringno—Target value.
trendup · down · flatnoflatDirection indicator.
statuson-track · at-risk · off-tracknoon-trackHealth signal.
More examples
@metric name="P0 bug count" value="3" target="0" trend=down status=at-risk

metricat-risk

P0 bug count

3↓target 0

Also written as @info, @warn, @tip, @question.

Boxed callout. The flavor is the first word after @callout, or use the alias directly: @tip, @warn, @info, @question. No type= param — the flavor IS the shortcode.

Other blocks can go inside it. What goes inside what

@callout warn
  This metric is lagging by two sprints.
Settings
SettingTypeRequiredDefaultMeaning
flavorinfo · warn · tip · questionnoinfoCallout flavor. Can also be used as the shortcode name directly.
More examples
@tip
  Export to HTML before the stakeholder meeting.