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