Prevent institutional amnesia by surfacing past architectural decisions directly on Pull Requests (or locally via CLI).
Created by Ali Abbas • Part of the Decispher project
Engineering teams lose critical context when senior engineers leave, architectural decisions go undocumented, or new developers modify sensitive code without understanding the why behind it.
Decision Guardian solves this. You write decisions once in simple Markdown files — when a PR touches protected code, Decision Guardian automatically surfaces the relevant context as a PR comment or CLI output.
- 🛡️ Automatic Context Surfacing — Posts PR comments when protected files change, grouped by severity (Critical, Warning, Info)
- 🎯 Flexible Matching — Glob patterns, regex, content matching, boolean logic (AND/OR), JSON path, line ranges
- ⚡ Enterprise-Grade Performance — Trie-based O(log n) lookup, handles 3,000+ file PRs, streaming mode
- 🔒 Security-First — ReDoS prevention, path traversal protection, Zod validation, VM sandboxed regex
- 🔄 Smart Behavior — Idempotent comments, self-healing duplicate cleanup, progressive truncation
- 💻 CLI + GitHub Action — Works locally, in any CI system (GitLab, Jenkins, CircleCI), or as a native GitHub Action
- 🔏 Privacy-First Telemetry — Opt-out with
DG_TELEMETRY=0. No source code ever leaves your repo. See PRIVACY.md
1. Create a decision file — .decispher/decisions.md:
<!-- DECISION-DB-001 -->
## Decision: Database Choice for Billing
**Status**: Active
**Date**: 2024-03-15
**Severity**: Critical
**Files**:
- `src/db/pool.ts`
- `config/database.{yml,yaml}`
### Context
We chose Postgres over MongoDB because billing requires ACID compliance.
MongoDB doesn't guarantee consistency for financial transactions.
---2. Add workflow — .github/workflows/decision-guardian.yml:
name: Decision Guardian
on:
pull_request:
permissions:
pull-requests: write
contents: read
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: DecispherHQ/decision-guardian@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
decision_file: '.decispher/decisions.md'
fail_on_critical: true3. Done! — Open a PR modifying src/db/pool.ts → Decision Guardian comments with context from DECISION-DB-001.
📖 For production-ready configuration (concurrency, outputs, etc.), see the full documentation.
# Install globally
npm install -g decision-guardian
# Or use directly without installation
npx decision-guardian --help
# Check staged changes
decision-guardian check .decispher/decisions.md
# Check against a branch
decision-guardian check .decispher/decisions.md --branch main
# Auto-discover all decision files
decision-guardian checkall --fail-on-critical
# Initialize a new project with template
decision-guardian init --template securityUse in any CI system — GitLab, Jenkins, CircleCI, pre-commit hooks, and more. See CLI docs.
We welcome contributions! Decision Guardian is open source (MIT) and maintained by Decispher.
- Report Bugs — Open an issue
- Suggest Features — Start a discussion
- Submit PRs — See Contributing.md
- Improve Docs — Fix typos, add examples
- Share — ⭐ Star the repo, write blog posts
git clone https://github.com/DecispherHQ/decision-guardian.git
cd decision-guardian
npm install
npm test
npm run buildQ: Can it prevent merges?
A: Yes, when fail_on_critical: true. Admins can still override.
Q: Works with monorepos?
A: Yes. Use path-specific patterns.
Q: Works with private repos?
A: Yes. Uses GITHUB_TOKEN — no code leaves your repo.
Q: Difference vs CODEOWNERS?
A: CODEOWNERS assigns who reviews. Decision Guardian explains why it matters. Use both.
Q: How do I skip for specific PRs?
A: Add a label condition:
if: "!contains(github.event.pull_request.labels.*.name, 'skip-decisions')"Q: Other CI/CD platforms?
A: The CLI works everywhere (GitLab, Jenkins, etc.). Native PR commenting is GitHub Actions only.
- 🌐 Website: decision-guardian.decispher.com
- 💬 Community: GitHub Discussions
- 🐛 Issues: Bug Reports
- 🏢 Enterprise: Decispher Support
- 📧 Email: decispher@gmail.com
MIT License — See LICENSE for details.
Decision Guardian is free and open source.
Decision Guardian is created and maintained by Ali Abbas as part of Decispher — helping engineering teams preserve and leverage institutional knowledge.
Connect:
- GitHub: @gr8-alizaidi
- Twitter: @gr8_alizaidi
Built with minimatch, parse-diff, zod, safe-regex, and @actions/toolkit.
Inspired by Architecture Decision Records (ADR) and CODEOWNERS.
If Decision Guardian helps your team, please:
- ⭐ Star this repository
- 🐦 Tweet about it
- 📝 Write a blog post
- 💼 Recommend it to colleagues
| Resource | Link |
|---|---|
| 🌐 Website | decision-guardian.decispher.com |
| 📖 Documentation | decision-guardian.decispher.com/docs |
| 📝 Blog | decision-guardian.decispher.com/blog |
| 🛠️ Markdown Builder (GUI) | decision-markdown-builder.decispher.com |
| 🎬 YouTube Walkthrough | Watch on YouTube |
| 📐 Architecture | ARCHITECTURE.md |
| 📋 Decision File Format | DECISIONS_FORMAT.md |
| 💻 CLI Reference | CLI.md |
| ⚙️ GitHub Action Details | APP_WORKING.md |
| 🔏 Telemetry & Privacy | TELEMETRY.md · PRIVACY.md |
| 📝 Templates | TEMPLATES.md |
| 🗺️ Roadmap | FEATURES_ROADMAP.md |
| 🔐 Security | SECURITY.md |
| 📓 Changelog | CHANGELOG.md |
Made with ❤️ by Decispher
Preventing institutional amnesia, one PR at a time.
