Skip to content

chore(docs): unify patterns/ naming to NN-slug[-walkthrough].md#518

Merged
trilamsr merged 1 commit into
mainfrom
chore/patterns-naming-unify
Jun 4, 2026
Merged

chore(docs): unify patterns/ naming to NN-slug[-walkthrough].md#518
trilamsr merged 1 commit into
mainfrom
chore/patterns-naming-unify

Conversation

@trilamsr

@trilamsr trilamsr commented Jun 4, 2026

Copy link
Copy Markdown
Contributor

Summary

Patterns 1-5 in docs/patterns/ carried pattern-N-slug.md while
patterns 7-13 used the lexsort-stable NN-slug.md prefix — two schemes
side-by-side. Pattern #2 carried both an engineering design spec
(02-ib-link-flap.md) AND an operator walkthrough
(pattern-2-ib-link-flap.md); these look like dup-naming but are
intentionally distinct doc types per the docs/patterns/README.md
two-table split (operator walkthroughs vs. design specs / TDD red-test
inputs).

This PR unifies the numeric-prefix scheme across the directory while
preserving the spec/walkthrough type distinction via a filename suffix:

  • NN-slug.md = engineering design spec
  • NN-slug-walkthrough.md = operator-facing runbook

Renames (5)

Old New
pattern-1-nvlink-degradation.md 01-nvlink-degradation-walkthrough.md
pattern-2-ib-link-flap.md 02-ib-link-flap-walkthrough.md
pattern-3-hbm-ecc.md 03-hbm-ecc-walkthrough.md
pattern-4-thermal-throttle.md 04-thermal-throttle-walkthrough.md
pattern-5-pcie-aer.md 05-pcie-aer-walkthrough.md

Pattern #2 dup investigation (not a dup)

02-ib-link-flap.md (engineering design spec) and
pattern-2-ib-link-flap.md (operator walkthrough with PromQL alert

  • escalation runbook) are distinct doc types that cross-reference
    each other. docs/patterns/README.md already lists them in separate
    tables (operator walkthroughs vs design specs). Both retained;
    walkthrough renamed to 02-ib-link-flap-walkthrough.md per the
    unified convention.

recipes-path-check*.sh retained (not the dup-scheme validator)

The original task plan flagged scripts/recipes-path-check.sh +
_test.sh for deletion as "the validator policing both schemes".
On inspection: those scripts implement the issue #427 convention
gate that lints commit subjects / PR titles for references to a
non-existent recipes/pattern-N/ directory layout. They have
nothing to do with docs/patterns/ filenames. Retained.

Inbound-ref updates (9 files)

  • docs/MILESTONES.md, docs/NORTHSTARS.md
  • docs/integrations/prometheus-scrape.md
  • docs/rfcs/0014-metrics-to-logs-pattern-input.md
  • docs/followups/M4b.md (forward-ref to planned
    14-pod-evicted-walkthrough.md)
  • docs/patterns/README.md (table rows + new "Filename convention"
    section documenting the NN- / NN-walkthrough split)
  • docs/patterns/02-ib-link-flap.md (spec's cross-link to its
    walkthrough)
  • module/pkg/patterns/{hbm_ecc,thermal_throttle,pcie_aer}.go
    (doc-comment references)
  • module/pkg/replay/thermal_throttle/canonical/manifest.json
    (replay-fixture description text)

Why this shape (vs collapsing both schemes into one)

The original task framing assumed the two schemes were unintended
divergence — but the README's two-table layout treats them as a
deliberate audience split (engineering TDD-spec readers vs.
operators triaging incidents). Collapsing the walkthroughs into the
spec namespace would have destroyed that signal. The
-walkthrough suffix preserves the semantic distinction while
giving the directory the lexsort-stable numeric prefix the task
wanted.

Test plan

  • make doc-check exit 0 pre-change (217 anchors + 1105
    markdown links + 239 non-md intra-repo links resolve)
  • make doc-check exit 0 post-change (same counts; zero
    broken refs introduced)
  • rg 'pattern-[1-5]-' docs/ install/ .github/ module/ scripts/
    returns only in-page heading anchors (#pattern-2--…,
    #m17-pattern-1-…), no stale filename refs
  • Pre-commit hook: attribute-namespace-check clean (100
    attributes documented), slo-rules-check 13 rules OK,
    chart-appversion-check matches, all module verify pass
  • Pre-push hook: no-autoupdate-check_test clean
docs: unify `docs/patterns/` filename convention to a single
`NN-slug.md` / `NN-slug-walkthrough.md` scheme. Operator walkthroughs
for patterns 1-5 renamed; design-spec files keep the `NN-slug.md`
shape; pattern #2 retains both (spec + walkthrough).

Patterns 1-5 carried `pattern-N-slug.md` while 7-13 used the lexsort-
stable `NN-slug.md` prefix. Pattern #2 had both an engineering design
spec (`02-ib-link-flap.md`) AND an operator walkthrough
(`pattern-2-ib-link-flap.md`) — distinct doc types, not duplicates.

Unify everything under a single numeric-prefix scheme that preserves
the spec/walkthrough split as a filename suffix:

- `NN-slug.md`             = engineering design spec (TDD red-test input)
- `NN-slug-walkthrough.md` = operator runbook (symptom -> escalation)

Renames (5):
  pattern-1-nvlink-degradation.md -> 01-nvlink-degradation-walkthrough.md
  pattern-2-ib-link-flap.md       -> 02-ib-link-flap-walkthrough.md
  pattern-3-hbm-ecc.md            -> 03-hbm-ecc-walkthrough.md
  pattern-4-thermal-throttle.md   -> 04-thermal-throttle-walkthrough.md
  pattern-5-pcie-aer.md           -> 05-pcie-aer-walkthrough.md

Inbound refs updated in 9 files (MILESTONES, NORTHSTARS,
prometheus-scrape, RFC-0014, M4b followup, README, 02-ib-link-flap
spec, 3 module/pkg/patterns Go files, thermal_throttle replay
manifest). README "Filename convention" section now documents the
NN-/NN-walkthrough split explicitly.

Pattern #2 keeps both files — they cross-reference each other (spec
links to walkthrough for operators; walkthrough links to spec for
the engineering contract). docs/patterns/README.md tables already
reflected this dual-doc reality; this change makes the filenames
honest about it.

`scripts/recipes-path-check{.sh,_test.sh}` retained — that gate
lints commit-subject references to a non-existent `recipes/pattern-N/`
*directory* (issue #427) and is unrelated to `docs/patterns/`
filenames.

Pre-change `make doc-check`: exit 0 (217 anchors + 1105 md links).
Post-change `make doc-check`: exit 0 (same counts; zero broken refs).

Signed-off-by: Tri Lam <tree@lumalabs.ai>
@trilamsr trilamsr enabled auto-merge (squash) June 4, 2026 00:36
@trilamsr trilamsr merged commit cc33e94 into main Jun 4, 2026
27 checks passed
@trilamsr trilamsr deleted the chore/patterns-naming-unify branch June 4, 2026 00:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant