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.
@panel
Section titled “@panel”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
Settings
| Setting | Type | Required | Default | Meaning |
|---|---|---|---|---|
label | string | no | — | Small uppercase kicker above the title, e.g. “Risk”. Omit for an unlabelled panel. |
title | string | no | — | The panel’s heading. |
badge | string | no | — | Short status chip beside the label, e.g. “accepted” or “high”. |
accent | neutral · alert · positive · info · quiet | no | neutral | Colour 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
@decision
Section titled “@decision”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 readsdecisionaccepted
Adopt event sourcing
Settings
| Setting | Type | Required | Default | Meaning |
|---|---|---|---|---|
title | string | yes | — | Short name for the decision. |
status | proposed · accepted · deprecated · superseded | no | accepted | Decision status. |
date | string | no | — | 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
New users may bounce in the first hour if the syntax feels like work.
Settings
| Setting | Type | Required | Default | Meaning |
|---|---|---|---|---|
level | low · medium · high · critical | no | medium | Severity. |
title | string | no | — | One-line risk name (shown as a heading). |
@assumption
Section titled “@assumption”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
Code-adjacent PMs will invest an afternoon to learn .jot if the output is good enough.
Settings
| Setting | Type | Required | Default | Meaning |
|---|---|---|---|---|
title | string | no | — | One-line assumption name. |
confidence | high · medium · low | no | medium | How sure we are. |
@persona
Section titled “@persona”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
Writes every spec herself, and keeps it open in VS Code all day.
Settings
| Setting | Type | Required | Default | Meaning |
|---|---|---|---|---|
name | string | yes | — | Persona name or archetype label. |
image | string | no | — | Not built yet: does nothing for now. Path or URL to an avatar image. |
@metric
Section titled “@metric”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
| Setting | Type | Required | Default | Meaning |
|---|---|---|---|---|
name | string | yes | — | What the metric measures. |
value | string | no | — | Current value. |
target | string | no | — | Target value. |
trend | up · down · flat | no | flat | Direction indicator. |
status | on-track · at-risk · off-track | no | on-track | Health signal. |
More examples
@metric name="P0 bug count" value="3" target="0" trend=down status=at-riskmetricat-risk
P0 bug count
3↓target 0
@callout
Section titled “@callout”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
| Setting | Type | Required | Default | Meaning |
|---|---|---|---|---|
flavor | info · warn · tip · question | no | info | Callout flavor. Can also be used as the shortcode name directly. |
More examples
@tip
Export to HTML before the stakeholder meeting.