Business & decisions

Field contracts and worked examples for the business & decisions blocks — converted at build time from the repo's authoring-skill reference. Every example body is YAML; in a real doc the fence language is the block type (for example sequence … ). Schemas are strict — unknown fields are rejected. See the field contract for the at-a-glance shape of all 87 blocks, or the block catalog for live previews.

Access control / RBAC

matrix — a role × resource capability grid

cells is positional — one value per cols entry, in order. Cells tint by meaning: Full/Admin/Write/✓ → green, —/None/✗ → muted, anything else → amber. Use matrix (not table) for a capability grid where the columns are resources and each cell is a permission level.

anatomy — the parts of a structured string (e.g. a permission)

Renders the full string (acme:billing:invoices.read) with each segment coloured, then a labelled card per segment. Use it to explain one identifier's shape — a permission string, a resource URN, a topic name.

composition — effective access as intersected gates

Renders gate₁ ∩ gate₂ ∩ … = result. Use it when access is the AND of several independent checks (authn ∩ scope ∩ permission), not a sequence of steps (use flow/sequence for ordered steps).

Presentation cards

drivers — the forces that shaped a design

A grid of "the N drivers/requirements behind this." icon is one of a fixed set (location · shield · grid · lock · key · user · clock · check · database · bolt · flag · doc · link · eye · server · layers); accent colours the top edge + icon.

team — people cards (who owns what)

Compact cards on a 3-column grid — initials avatar, name, uppercase role, and a one-line focus. Initials derive from name; set initials to override (e.g. for a team rather than a person). Use team for ownership/contact overviews; use persona for user archetypes with goals and frustrations.

options — approaches explored, with a verdict

Use when you weighed several approaches. Each card is one option; tone: chosen highlights the winner. For one option's trade-offs alone, use proscons.

scorecard — a weighted decision matrix

Criteria are rows (an ×N chip marks weights other than 1), options are columns, and the footer TOTAL row carries the weighted sum per option — the winner's header and total are highlighted with a WINNER chip (ties highlight all). Scores are plain numbers, 0-5 by convention. Use scorecard when the decision was scored; use options for qualitative pros / cons / verdict cards and table for plain data.

spec — a labelled spec sheet

A compact "fact sheet" for one approach/component. A row with steps: renders as an arrow-joined pill flow (great for a short resolution pipeline).

envelope — back-of-envelope capacity math

The system-design "step 2" block: assumptions are the givens, each steps row is one derivation (label · calc · result), and the optional result is the highlighted bottom line. Every value is a string — write units and ≈/× freely, and quote anything containing , : or #. Use envelope for the estimate that justifies a design; use stats for measured KPIs.

Business & strategy

swot — strengths / weaknesses / opportunities / threats

Four plain string lists — the classic 2×2 draws itself (S green · W red · O blue · T amber). Omit a quadrant you have nothing for; it still draws so the shape reads as a SWOT. Use swot for a strategic position; use proscons for one option's trade-offs and quadrant to plot items on two axes. For a conversion funnel (drop-off between ordered stages), use chart with kind: funnel — see charts-overviews.md.

okr — objectives + key results

One card per objective; each key result renders a progress bar (progress is a plain number 0..1) coloured by status — done / on-track green, at-risk amber, off-track red, no status navy. Use okr for goal tracking; use slo for reliability targets and statustable for task-level work.

persona — user persona cards

A 2-column grid of cards — initials avatar (from name), role, an italic quote with an accent bar, then GOALS / FRUSTRATIONS lists and TOOLS chips (sections with no data are omitted). Use persona for user archetypes; use team for real people and ownership.

wardley — value chain against evolution

Strategy on two axes: how visible a component is to the user (up) and how evolved it is (right — genesis, custom-built, product, commodity). The value of the map is that it forces both judgements to be stated as numbers, so "we should stop building this" becomes a position rather than an opinion.

x and y are 0–1 and clamp; kind tints the dot (user · component · commodity · build · buy) and movement draws a dashed arrow that far along the evolution axis — where the component is heading.

harvey — the rated comparison

Options across the top, criteria down the side, a filled circle for each judgement. A steering committee reads it faster than any table of numbers, because a column of nearly-full circles argues for itself.

Ratings run 0–4, empty ball to full. A row shorter than columns reads as not assessed (—) rather than a zero — those are different claims. weight multiplies a row into the WEIGHTED footer, which is computed from the balls, so the column you mark with recommend and the arithmetic can be seen to agree. Use benchmark when the cells are measured numbers.

scqa — the executive summary, in Minto order

Situation, complication, question, answer: the four moves that make an opening slide argue instead of describe.

Every field is optional, but the order is fixed — keeping it is the block's job. The first three render as a numbered ladder; answer is the recommendation and takes the filled card, with because as the support under it. Pair it with a lede on the block: on a slide that line pins under the action title as the supporting sentence.

scenarios — base, upside and downside

The table a plan is defended with. Cases go in columns, so reading across a driver row shows how much of the outcome hangs on that one assumption.

tone is pos | neg | base, and the base case is badged because every other column is read relative to it. values are positional against drivers; a case that omits one renders · — silent about that driver, which is not the same as claiming no change. outcome gets its own emphasised row.