Writing the troubleshooting flow

The step types and which to pick

Every entry in topic.steps[] has a type field. There are five, and they map directly to what the technician is supposed to do next with the aircraft in front of them — at the partner site if the aircraft is still docked, or in a maintenance cell at the hub if it has been pulled out of service.

• action — do this work. A concrete physical or software task with no branching: replace the harness, reseat the connector, run the template.
• question — pick a branch. A diagnostic decision point that routes the technician to a different next step based on what they observe in the alarm report or on the aircraft.
• escalation — stop and page someone. The technician has worked through the steps and needs the on-call engineer who owns this failure mode; route through [[EscalationPath:<id>]].
• reference — read this, then continue. Informational context the technician needs before the next action — a dashboard legend, a return-to-service disposition, a definition. It does not, by itself, ask the technician to do anything to the aircraft.
• telemetry — embed a Baraza log plot inline. The technician enters the requested identifier and the plot renders in place instead of sending them away to find it.

The same example topic (0x00100194 ZIP_EXECUTIVE_V4_DROID_PARTIALLY_CONSTRAINED) carries the first three of these. We pull reference from a sibling topic on the next slides, and telemetry is covered end-to-end in Section 8.

Rendered step-type example

What step type do you want to learn about?

Action Question Escalation Reference Telemetry

next and options — how the flow wires together

Two fields connect steps into a graph. The pull-request check fails if the graph is broken (orphan step, dangling next, multiple entry points).

• next: "<step-id>" — single edge. Used by action, reference, and occasionally escalation when there’s a follow-on step after paging. The id must match another step’s id exactly.
• options: [{ label, next }, ...] — multiple edges. Used by question only. Each label is the button the technician sees; each next is the step they land on.
• No next and no options — leaf step. Common for escalation and for a terminal action like “return the aircraft to service.”
• steps[0] is the entry point. Every other step must be reachable from it; the connectivity check enforces this on every pull request.

The ids are slugs of the step text, not human-meaningful names. That is deliberate — they’re generated and only the validator reads them.

Flow UI readability

Flow readability is a final topic quality check, not a step type. After arranging next and options[].next, use Guide content checklist: Flow UI readability to confirm the rendered UI keeps normal reader paths moving down the page.

Tables — keep long lookups searchable

Use tables for lookup or reference data, not for ordinary troubleshooting flow. If the reader needs to choose a branch from the table, consider whether those choices should become question options instead.

Small tables are fine inline. Once a table has more than about 20 rows, do not leave it as one long page-length table. Ask Codex to add a search box above the table and wrap the table in a scroll area so the reader can search across any column without losing their place on the page.

The finished table should keep all rows in the source, cap the visible table height, support horizontal scrolling when the columns are wide, and keep the header visible while the body scrolls.

Notes and cautions

Use Starlight note, caution, and warning blocks for short callouts that should stand apart from the main troubleshooting path.

:::note
Helpful context or reference links.
:::

:::caution
Important limitation, warning, or condition before proceeding.
:::

:::danger[Warning]
Safety-critical or equipment-risk condition before proceeding.
:::

Note, caution, and warning examples

Note

Helpful context or reference links.

Caution

Important limitation, warning, or condition before proceeding.

Warning

Safety-critical or equipment-risk condition before proceeding.

Notes use a blue left border, light blue background, information icon, and bold Note title. Cautions use an orange left border, pale yellow background, warning icon, and bold Caution title. Warnings use the red danger block with a Warning title. Keep these blocks concise, and do not use them for normal troubleshooting steps.

The rendered flow diagram

The FlowVisualizer component reads topic.steps[] and renders a diagram. This is the picture a technician mentally walks through: rectangles for actions, diamonds for questions, paged shapes for escalations.

For the hardware engineer authoring a topic, the flow diagram is your sanity check: if the diagram has an orphan node, an unreachable branch, or three converging paths that don’t make engineering sense, fix the steps before you push. The same data backs both the rendered page above and this diagram — they’re two views of one source of truth.

Rendered flow diagram example