I created Decispher (decispher.com) to enable human developers and AI agents working alongside each other to share their context.

It has some pretty cool features, like Branch Story (explains why a branch's code looks the way it does) and Session Context Transfer (an MCP tool that can copy context from one chat, agent, or machine to another).

You can also capture context from engineering platforms like Slack, JIRA, and Git(hub/lab) just by tagging @Decispher.

Comments URL: https://news.ycombinator.com/item?id=48762112

Points: 5

# Comments: 1

Comments URL: https://news.ycombinator.com/item?id=47459167

Points: 2

# Comments: 1

No database. No signup. Two lines of GitHub Actions YAML.

v1.2.0 fixes several rule-engine bugs that surfaced from real usage:

Silent false-positives when content rules had no type field (every template shipped broken)

OR-only logic for multi-condition rules with no way to require ALL conditions

Deleted lines were invisible to all matchers — removing guarded code never triggered a warning

json_path rules failed silently for nested value edits because parent keys only appear as context lines in diffs

The fixes came directly from people running this on production repositories and reporting what wasn't working. That feedback loop has been more valuable than anything I designed upfront.

It also works as an npx CLI for pre-push checks outside GitHub Actions (GitLab CI, Jenkins, CircleCI, local hooks).

Repo: https://github.com/DecispherHQ/decision-guardian npm: npx decision-guardian check

Would love your feedback

Comments URL: https://news.ycombinator.com/item?id=47392464

Points: 2

# Comments: 0

# 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 security Use in any CI system — GitLab, Jenkins, CircleCI, pre-commit hooks, and more

Github Open Source -:

https://github.com/DecispherHQ/decision-guardian

Comments URL: https://news.ycombinator.com/item?id=47375668

Points: 3

# Comments: 0

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

Comments URL: https://news.ycombinator.com/item?id=47226046

Points: 6

# Comments: 1

Comments URL: https://news.ycombinator.com/item?id=47202407

Points: 5

# Comments: 0

I built Decision Guardian to solve a problem I call "institutional amnesia." Senior engineers build complex systems (like highly-tuned DB connection pools or sensitive auth middleware) and document the "why" in wikis or ADRs. But inevitably, a new developer modifies that code without reading the docs, and things break. While tools like CODEOWNERS are great for telling you who needs to review a file, I needed something that automatically tells the developer why the review matters before they even ask.

What it is: Decision Guardian is an open-source tool that shifts teams from passive documentation to active enforcement. You write your architectural decisions in a standard Markdown file (e.g., .decispher/decisions.md) and map them to file paths using glob patterns or advanced JSON rules. When a developer modifies those protected files, it automatically analyzes the diff and drops a structured comment into the Pull Request explaining the context, warnings, and checklists.

I just released v1.1, which includes a major internal SOLID refactor. The core engine is now 100% decoupled from GitHub (using ISCMProvider and ILogger interfaces), allowing it to ship as a standalone 430KB CLI (npx decision-guardian check) that works locally, in pre-commit hooks, or on GitLab/Jenkins.

Under the hood (How it works): I wanted this to be fast and secure enough to run on massive enterprise repositories, which required a few fun technical implementations:

O(1) Pattern Matching: Naively matching N decisions against M files in a 3,000+ file PR is painfully slow. The core engine compiles all file patterns into a Prefix Trie (an Aho-Corasick variant), turning candidate lookup into an O(1) operation relative to the number of decisions.

ReDoS-Protected VM Sandbox: For complex rules, you can use Regex to scan diff contents (e.g., detecting hardcoded credentials). Because user-supplied regex can cause catastrophic backtracking, all regex evaluation runs inside an isolated Node VM sandbox with a hard 5-second timeout and pre-flight safe-regex checks.

Progressive Comment Truncation: GitHub limits PR comments to 65,536 characters. To prevent failures on massive PRs, the tool uses a 6-layer progressive truncation algorithm that intelligently summarizes details before falling back to a hard truncation.

Privacy & Telemetry: I know HN cares deeply about telemetry. v1.1 introduces anonymous usage metrics to help me understand performance (e.g., node version, duration, match counts). However, I designed it with strict privacy constraints:

Zero PII: It never collects source code, file contents, repo names, branches, or paths.

Runtime Blocklist: The privacy module physically validates every payload against a blocklist before sending. If any blocked field is detected, it throws an error and rejects the payload.

Open Source Backend: It is fire-and-forget (never slows down the tool), entirely opt-out (DG_TELEMETRY=0), and the Cloudflare Worker backend code is fully open-source in the repo.

Links:

Repo: https://github.com/DecispherHQ/decision-guardian

Docs/Architecture: https://decision-guardian.decispher.com

I also included 5 production-ready templates (security, database, api, etc.) to help teams get started instantly.

I’d love to hear your thoughts on the architecture, the Trie implementation, or how your teams currently handle enforcing ADRs during code reviews!

Comments URL: https://news.ycombinator.com/item?id=47188328

Points: 2

# Comments: 0

If you work on a scaling codebase, you know the struggle of keeping architectural context alive. Senior engineers make important decisions about how the code should be structured, but new hires often don't know that context exists and end up accidentally breaking critical systems.

To fix this, I built Decision Guardian. It is an open-source tool (running as a GitHub Action or local CLI) that shifts teams from passive documentation to active enforcement. What it exactly does: Instead of hoping developers read an external wiki, you document your architectural decisions in a simple Markdown file in your repository (e.g., .decispher/decisions.md). You map these decisions to specific files using glob patterns or advanced JSON rules (like regex or line-ranges).

When a developer opens a Pull Request that modifies those protected files, Decision Guardian automatically drops a structured comment directly into the code review, giving them the exact context and checklist they need before they merge.

Here is a real-world example of how it works:

Let's say your team has a strict rule about not breaking public API contracts.

The Setup: In your decisions.md file, you create a decision called DECISION-API-001: Public API Contract Protection and map it to the file pattern src/api/v1/*/*.ts.

The Trigger: A new developer submits a Pull Request that modifies src/api/v1/users.ts to change how a payload is formatted.

The Action: Decision Guardian instantly detects the match and posts a "Warning" comment on the PR stating: "Changes to v1 API routes affect external clients. Before merging: Update API documentation, notify integration partners, and consider a deprecation path".

Key Features:

You can categorize decisions by severity (Info, Warning, Critical).

If a developer violates a "Critical" decision, you can configure the tool to automatically fail the PR status check, preventing them from merging without approval. It runs entirely locally or in your CI/CD pipeline, guaranteeing your source code never leaves your repository. It essentially acts as an automated guardrail, telling your developers why a piece of code is sensitive the exact moment they try to change it.

You can check out the repo here: https://github.com/DecispherHQ/decision-guardian

Comments URL: https://news.ycombinator.com/item?id=47188281

Points: 5

# Comments: 2

The context exists somewhere — a postmortem doc, a Slack thread, someone's memory. It's just never at the moment a new engineer opens a PR touching that file.

Decision Guardian reads a markdown file of decisions tied to file patterns and posts the relevant context as a PR comment when those files change. Works as a GitHub Action or CLI (npx decision-guardian check, non-zero exit on critical matches).

The part I found interesting to build: simple file matching created too much noise, so I added content-aware rules. A config file only triggers if you change the specific keys that matter.

An alert only fires when both files in a coupled pair change in the same PR. Regex matching on diffs with ReDoS protection and 5s timeout.

{ "match_mode": "all", "conditions": [ { "type": "file", "pattern": "src/analytics/events.ts" }, { "type": "file", "pattern": "src/analytics/schema.ts" } ] }

That rule fires only when both files are in the same PR diff — the case where a field rename needs to be consistent across both.

Tech: TypeScript, Trie for O(1) pattern lookup, safe-regex for ReDoS prevention. CLI is platform-agnostic — GitLab CI, Jenkins, any pre-push hook.

GitHub: https://github.com/DecispherHQ/decision-guardian (MIT)

Known gaps: PR commenting is GitHub-only for now. GitLab native support is the most requested thing and the ISCMProvider interface is already stubbed for it.

Happy to discuss the matching engine or the decision format tradeoffs.

Comments URL: https://news.ycombinator.com/item?id=47089082

Points: 3

# Comments: 0

The Problem: We write ADRs (Architectural Decision Records), put them in a folder, and then ignore them. New engineers break architectural rules because they don't know the history.

The Solution: Decision Guardian runs in CI. You define rules (ADRs) linked to file patterns.

What makes it interesting: It goes beyond simple glob matching. You can define rules based on:

Content (Regex): e.g., Alert if someone commits a secret key pattern or a banned function.

Structure (JSONPath): e.g., Watch $.dependencies in package.json to prevent library drift.

Location (Line Range): Protect the first 50 lines of a legacy file.

It’s open source and there's a helper site to generate the rule configs: https://decision-guardian.decispher.com/

Comments URL: https://news.ycombinator.com/item?id=47013210

Points: 4

# Comments: 0

Re: noise — I agree, that’s the main failure mode for any PR bot.

A few things I did to keep signal high:

Only trigger on explicit file patterns (no fuzzy matching by default)

Idempotent comments — it updates instead of spamming new ones

If multiple decisions match, it groups them into a single comment

Severity levels (info / warning / critical) so teams can tune strictness

Optional “fail critical” mode so it never blocks PRs unless configured

The goal is that it behaves more like a linter than a chatbot — predictable and quiet unless something clearly matches.

If it ever becomes background noise, it’s failed

This is still just markdown in the repo. The Action doesn’t replace ADRs, it just surfaces the relevant ones automatically in PRs so reviewers don’t have to remember to look for them.

In teams where people consistently check ADRs, this probably isn’t useful.

In teams where the ADR exists but nobody remembers it during review, this helps reduce that friction.

And yeah — the Mongo example was dramatized. The real version was just re-explaining a past decision in a design doc. Not catastrophic, just wasted cycles.

Appreciate the sanity check.

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.

Comments URL: https://news.ycombinator.com/item?id=46993402

Points: 4

# Comments: 8

At my last job, we chose Postgres over MongoDB for ACID compliance. 18 months later, a new engineer opened a PR to switch to MongoDB. The team spent 3 months re-evaluating before someone remembered.

Decision Guardian prevents this: - Document decisions in markdown (why you chose X over Y) - GitHub Action comments on PRs when decision-protected code changes - Free, open source, MIT licensed

Takes 2 minutes to set up. Would love feedback.

GitHub: https://github.com/DecispherHQ/decision-guardian

Comments URL: https://news.ycombinator.com/item?id=46955694

Points: 4

# Comments: 0