Hacker News

iamalizaidi

Shift from passive documentation to active enforcement

Hey everyone,

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

btrettel6 hours ago

Nice work. I made a similar (but much less capable) Python script [1] for my own use before and I can say that a tool like this is useful to keep the docs in sync with the code.

My script only detects whether a checksum for a segment of code doesn't match, using directives placed in the code (not a separate file as you've done). For example:

    #tripwire$ begin 094359D3 Update docs section blah if necessary.
    [...]
    #tripwire$ end

Also, my script knows nothing about pull requests and is basically a linter. So it's definitely not as capable.

[1] https://github.com/btrettel/flt/blob/main/py/tripwire.py

***

Edit: I just checked my notes. I might have got the idea for my script from this earlier Hacker News comment: https://news.ycombinator.com/item?id=25423514

source