Spotify's take on ADRs is great, but how do you enforce them at scale? Hey HN, I built Decision Guardian — an open-source GitHub Action and CLI that automatically surfaces architectural decisions as PR comments when code touches protected files. The problem it solves: Spotify published a great post in 2020 about when to write Architecture Decision Records. I followed the advice. My team wrote ADRs. They sat in docs/adr/. Nobody read them before opening a PR. https://engineering.atspotify.com/2020/04/when-should-i-write-an-architecture-decision-record The gap isn't documentation — it's surfacing. The right moment to surface a decision isn't onboarding or sprint planning. It's when someone is actively editing the code the decision protects. How it works: 1) Write decisions in a Markdown file (compatible with existing ADRs) 2) Add the GitHub Action to your workflow 3) When a PR modifies protected files, Decision Guardian posts the relevant decisions as a comment automatically Decision format (plain Markdown): <!-- DECISION-DB-001 --> ## Decision: Use Postgres for Billing *Status*: Active *Severity*: Critical *Files*: - `src/db/*/*.ts` ### Context We evaluated Postgres vs MongoDB. Billing requires ACID compliance. MongoDB was rejected — no transaction guarantees. Features worth calling out: 1) Severity levels (Critical / Warning / Info) — can block PRs on critical violations 2) Advanced matching: glob patterns, regex, content-based rules, boolean logic 3) CLI works with any CI (GitLab, Jenkins, CircleCI, pre-commit hooks) 4) Handles PRs with 3000+ files without OOM 5) Idempotent comments — no spam, updates in place 6) Zero external network calls — nothing leaves your GitHub runner 7) 109 tests, ReDoS protection, path traversal protection vs. CODEOWNERS: CODEOWNERS assigns reviewers. This explains why the review matters. Best used together. vs. Danger.js: Danger requires code. This requires Markdown. Non-JS engineers can own their decisions. It's MIT licensed, single-step GitHub Action or npx decision-guardian CLI. Happy to answer questions. Repo: https://github.com/DecispherHQ/decision-guardian |