Decision records — auto-indexed, never hand-curated
:::note Map that builds itself
This is the front-door index of every decision record / ADR the platform owns. No one maintains
this table by hand — scripts/gen-adr-index.py crawls every non-archived repo in the org and lists
the decision records it commits, with a link straight to the source file on GitHub. A new ADR in any
repo appears here on its own (weekly + on-demand, via .github/workflows/update-adr-index.yml).
Why it exists: the house rule (documentation.md) is detail lives with the code, the central site is
the map — every repo ADR should have a pointer here. That pairing used to be a hand-written step, and
hand-written steps rot (a doc gets written in a repo and the map never learns about it). This replaces
the discipline with a mechanism — the same pattern already used for the
🧬 Schema diagrams index and the architecture diagrams.
:::
What counts as a decision record here (the crawler's definition): a top-level docs/*.md file (the
flat-ADR convention this platform uses — e.g. cnpg-standard.md, helm-golden-path.md), plus any
file under an adr/ or decisions/ directory inside a repo's docs/. Excluded: the ERD data-model docs
(indexed separately), templates, incident postmortems, and README/index/intro files. Titles are derived
from the filename — click through for the authoritative content, which always lives with the code.
Operate / verify
# regenerate locally (needs an authenticated gh with org read — GITOPS_TOKEN in CI):
cd minicloud-platform-docs && python3 scripts/gen-adr-index.py
# it rewrites only the table between the ADR-INDEX markers; everything else is left untouched.
A decision record's content is never moved onto this site — it stays versioned and CODEOWNERS-gated next to the manifests/code it governs. This page only ever points at it.