| 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 |