ADR-0005 - Numbered step IDs (manual, dotted) #

• Status: Accepted
• Date: 2026-05-07
• Deciders: Natan

Context #

Each step in a run needs an identifier for two reasons:

1. Visual nesting in logs - a reader scanning output should see

that "1.1" and "1.2" are siblings inside "1".

1. Stable handles for postmortems - "step 2.3 spiked at 4s" should

resolve unambiguously to one location across time.

Three options:

• Flat names (api-ready, s3-ready, mongo-count) - loses

grouping. Hard to tell which checks belong to which segment.

• Dotted names (preflight.api-ready) - preserves grouping but

IDs grow longer than the content; reviewers stop reading them.

• Dotted numbers (1.1, 2.3.4) - shortest possible grouping

with a free total ordering.

For ID generation, two further options:

• Auto-generate - couples ID to call site; refactors break past

references.

• Manual - author picks the next number; refactors don't change IDs.

Decision #

Manual, dotted decimal IDs. Top level = segment, second level = check inside a segment, third level (rare) = sub-step of a check. Indent depth in the rendered log = id.split(".").length - 1.

Consequences #

• Pro: Stable references survive refactors.
• Pro: Indent emerges from the ID; no separate nesting bookkeeping.
• Pro: Total ordering is implicit - "what came after 1.4" is

well-defined.

• Con: Author must pick the next number on each addition. Cheap.
• Con: Re-using a deleted number changes the meaning of past

references. Convention: leave gaps, don't reuse.

• Falsifiability: Revisit if (a) we accumulate enough run history

that postmortem references become a primary discovery surface (then consider promoting IDs to first-class metadata in a DB), or (b) the manual-numbering cost stops being trivial (e.g. > ~50 steps in a flow).

See also #

• docs/concepts/step-ids.md ↗ - the

explanation with full conventions.