Hi HN, I built this to solve a problem I kept running into on my team.
The problem: A senior engineer made a deliberate choice—Postgres over MongoDB for billing because we needed ACID compliance. They documented the reasoning in a Slack thread. 8 months later they left. A new developer opened a PR to migrate to MongoDB. No one remembered why Postgres was chosen. We spent 3 months re-evaluating a decision that had already been carefully made.
What this does: Decision Guardian is a GitHub Action that lets you write architectural decision records in markdown, tied to file paths. When a PR modifies those files, it automatically posts a comment with the relevant context—what was decided, why, what alternatives were rejected.
Think of it as CODEOWNERS for the "why" instead of the "who."
Technical details:
1) Written in TypeScript, runs as a GitHub Action
2) AST-based markdown parsing with remark
3) Prefix trie for O(log n) file-to-decision matching instead of brute-force O(N×M)
4) Supports glob patterns, regex content matching (with ReDoS protection via VM sandbox + timeout), and boolean logic for complex rules
5) Handles PRs with 3000+ files using streaming mode
6) Idempotent comments—updates existing ones instead of spamming, with self-healing duplicate cleanup
7) 5-layer progressive truncation to always fit within GitHub's comment size limit
8) No external network calls, no data leaves your GitHub runner
What I'd love feedback on:
1) Is the decision file format (structured markdown) the right choice, or would YAML/TOML be better?
2) Any thoughts on content-based matching (detecting patterns in diffs, not just filenames)?
3) Would integration with existing ADR tools (like adr-tools) be useful?
Code: https://github.com/DecispherHQ/decision-guardian
Happy to answer any questions about the implementation.
What I like most is that you’re inserting context at the moment of change (PR time) instead of relying on people to proactively search docs. That’s where most documentation systems fail — they require memory and initiative.
One question I have: how do you prevent this from becoming noisy over time? In my experience, the biggest risk with automated PR comments is that teams start ignoring them once the signal-to-noise ratio drops.
reply