You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Rename ADR source files from NNN-slug.md to ADR-NNN-slug.md in docs/decisions/.
Problem
The current filenames (001-stacked-pull-requests.md, 002-least-privilege-bootstrap-policies.md) produce Starlight page titles like "002 least privilege bootstrap policies" — the number alone doesn't communicate that these are Architecture Decision Records. The normalizeFileStem function in docs/scripts/sync-starlight.mjs derives the title from the filename, stripping dashes and capitalizing.
Proposed change
Before
After
001-stacked-pull-requests.md
ADR-001-stacked-pull-requests.md
002-least-privilege-bootstrap-policies.md
ADR-002-least-privilege-bootstrap-policies.md
(future ADRs follow the pattern)
ADR-NNN-slug.md
Why
Self-describing — a file named ADR-001-... tells you what it is without opening it. 001-... could be anything.
Starlight title becomes ADR 001 stacked pull requests — instantly recognizable in the sidebar as a decision record.
Grep-friendly — find docs/decisions -name 'ADR-*' works intuitively.
Convention alignment — most ADR tooling (adr-tools, Log4brains, etc.) uses the ADR-NNN prefix in filenames.
No ambiguity at scale — if docs/decisions/ ever contains non-ADR files (README, template), the prefix distinguishes records from supporting files.
Summary
Rename ADR source files from
NNN-slug.mdtoADR-NNN-slug.mdindocs/decisions/.Problem
The current filenames (
001-stacked-pull-requests.md,002-least-privilege-bootstrap-policies.md) produce Starlight page titles like "002 least privilege bootstrap policies" — the number alone doesn't communicate that these are Architecture Decision Records. ThenormalizeFileStemfunction indocs/scripts/sync-starlight.mjsderives the title from the filename, stripping dashes and capitalizing.Proposed change
001-stacked-pull-requests.mdADR-001-stacked-pull-requests.md002-least-privilege-bootstrap-policies.mdADR-002-least-privilege-bootstrap-policies.mdADR-NNN-slug.mdWhy
ADR-001-...tells you what it is without opening it.001-...could be anything.ADR 001 stacked pull requests— instantly recognizable in the sidebar as a decision record.find docs/decisions -name 'ADR-*'works intuitively.ADR-NNNprefix in filenames.docs/decisions/ever contains non-ADR files (README, template), the prefix distinguishes records from supporting files.Scope
docs/decisions/./001-stacked-pull-requests.mdlink)docs/decisions/README.mdnumbering section to show the new patternmise //docs:sync)DEPLOYMENT_ROLES.md)sync-starlight.mjs—normalizeFileStemhandles any prefixWhen
Low priority — cosmetic improvement. Can be bundled with the next ADR PR (#143 or #144) or done standalone.