Skip to content

chore(docs): rename ADR files with ADR- prefix for discoverability #161

@scottschreckengaust

Description

@scottschreckengaust

Summary

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

  1. Self-describing — a file named ADR-001-... tells you what it is without opening it. 001-... could be anything.
  2. Starlight title becomes ADR 001 stacked pull requests — instantly recognizable in the sidebar as a decision record.
  3. Grep-friendlyfind docs/decisions -name 'ADR-*' works intuitively.
  4. Convention alignment — most ADR tooling (adr-tools, Log4brains, etc.) uses the ADR-NNN prefix in filenames.
  5. No ambiguity at scale — if docs/decisions/ ever contains non-ADR files (README, template), the prefix distinguishes records from supporting files.

Scope

  • Rename all existing ADR files in docs/decisions/
  • Update cross-references (e.g., ADR-002's ./001-stacked-pull-requests.md link)
  • Update docs/decisions/README.md numbering section to show the new pattern
  • Regen Starlight mirrors (mise //docs:sync)
  • Update the golden-baseline test in PR feat(bootstrap): policies as typed TypeScript with version and hash #158 if it references ADR filenames (it doesn't — reads DEPLOYMENT_ROLES.md)
  • No changes needed to sync-starlight.mjsnormalizeFileStem handles any prefix

When

Low priority — cosmetic improvement. Can be bundled with the next ADR PR (#143 or #144) or done standalone.

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions