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.