DEV Community: Ali Abbas

Your AI agent doesn't know WHY your codebase looks like this. That's the whole problem

Ali Abbas — Sat, 11 Jul 2026 14:37:36 +0000

AI coding agents read your code perfectly and understand your team not at all. So they produce diffs that look clean, pass a quick review, and quietly undo something that was there on purpose: a guard rail, an invariant, a workaround that exists because the team hit a problem once and swore never to repeat it. Nothing in the code explained why that line mattered, so the agent optimized it away.

The code is usually fine. The context is what's missing. And this isn't really an AI problem, it's a memory problem that AI just made impossible to ignore.

Two knowledge layers, and agents only see one

Every engineering org runs on two layers of knowledge.

The explicit layer is code, READMEs, tickets, merge history. It's written down, and agents read it fine.

The tacit layer is everything else. Why a design was chosen over the obvious alternative. What the team tried before and abandoned. Which invariants must never break. Which shortcut is quietly forbidden and why. Who to ask before touching the fragile part of the system. None of that is written down anywhere clean. It lives in Slack threads, in PR review comments, and in the heads of a few long-tenured engineers.

A senior engineer's real value isn't typing speed. It's that they carry that second layer around in their head. They start a task already knowing that a certain approach deadlocked in production last year, that a pattern is banned for a security reason, and that you don't touch payments code without a heads-up. AI agents start every task with none of it.

We built Decispher to capture that second layer and serve it back, to humans and agents both, as a queryable system of record.

The mental model

Here's the line that made it click for me:

Git stores what changed. Decispher stores why it changed, what must not change, what was tried before, and what the next engineer should know before touching it.

Everything below is in service of that.

Capture: harvest context from where work already happens

The fastest way to kill a knowledge system is to make engineers maintain it by hand. Nobody does. So capture is passive. Slack bots listen in channels, GitHub webhooks watch PRs and reviews, the Jira app reads tickets and comment threads, and Branch Story records what happens inside coding sessions.

Engineers keep writing normal messages and normal PR descriptions. Decispher extracts the durable signal from them and sorts it into seven structured types. The structure matters because each type should change what an agent does:

Type	What it is	What it should do to an agent
Decision	A choice the team made	Inform
Convention	A recurring rule	Shape generated code
Constraint	A hard boundary	Block the action
Rationale	The reasoning behind a choice	Explain intent
History	What was tried and failed	Prevent the dead end
Ownership	Who owns an area	Route the question
Plan	Approved-but-not-built intent	Set expectations

A pile of undifferentiated message text can't do this. Blocking an action and shaping generated code are different operations, so the memory that drives them has to be typed.

Fuse: one decision, not three copies

The same architectural rule shows up in five places with slightly different wording: a Slack thread, a PR comment, a line in a Jira ticket. Store all five and you haven't built memory, you've built noise with extra steps.

The Context Fusion Engine merges those fragments into one canonical unit using semantic similarity, explicit references, timing, and overlapping people and entities. Then it links units into a graph with real relationships: confirms, extends, contradicts, supersedes, same-topic, derived-from. When two units can't both be true, it flags the contradiction instead of silently keeping both.

That graph turned out to be the closest thing to how a senior engineer actually reasons. They don't recall isolated facts, they recall chains. An authentication choice constrains a deployment pattern, which affects caching, which touches compliance. The graph encodes exactly those chains.

Serve: give the agent the right context, not all of it

The lazy way to give an agent context is to shove a giant generic block into every call. It burns tokens, and worse, it buries the one fact that mattered under a thousand that didn't.

Decispher splits it in two. A small, always-loaded Context Map is committed to .decispher/ in the repo as the spine. The deeper detail stays in Decispher and is fetched live over MCP, only when a task needs it.

So an agent can ask focused questions mid-task instead of hoping it read the right static file. The tool that changes the most behavior is check_intent. The agent describes what it's about to do and gets a verdict before writing code. Illustratively:

> check_intent("remove the token-rotation step to simplify the session flow")

BLOCKED
Violates a CONSTRAINT: token rotation must not be removed from the
session flow.
Rationale: it was added deliberately after a past security issue.
Owner: the payments team.
Sources: the Slack thread and PR where the rule was set.

Instead of confidently deleting something load-bearing and finding out in review, or in production, the agent finds out first.

Because context should reach agents in the format they already read, Decispher also generates CLAUDE.md, .cursorrules, and AGENTS.md, and keeps them in sync through pull requests when the underlying context changes.

Enforce: an automated reviewer that remembers

Capture and serving help before and during work. Lens helps at review time. It reads a PR against the knowledge graph and flags decision violations, convention drift, and constraint breaches by analyzing intent, not by matching patterns. When it comments, it explains which governing decision the change violates and why that decision exists.

That's the senior-engineer move that's hardest to scale: recognizing that a perfectly reasonable-looking change breaks a rule the team agreed on months ago.

If you want the formal version of this, our open-source entry point is Decision Guardian, which enforces Architectural Decision Records on PRs. It's the front door. The platform grows from there into automatic capture, live serving, and semantic review.

Humans use the same memory

This isn't an agent-only tool, and that's deliberate. Engineers get search, Ask Decispher, dashboard chat, Slack commands, and PR-comment answers, all backed by the same graph. The operating rule is no source, no claim. Every answer cites the units it came from.

The point of one shared memory is alignment. When a new hire asks why the team does auth a certain way, and an agent asks the same question, they should get the same cited, traceable answer. Two separate memory systems drift apart. One system of record keeps everyone pointed at the same truth.

Branch Story: the flight recorder for coding sessions

This is the feature I'm most attached to. Branch Story keeps branch-level memory. It opens a session with a pre-flight briefing, records discoveries in the background, offers a Story Mode replay of how the branch evolved, warns you through déjà-vu detection when you're re-attempting an approach that was already abandoned, and lets you promote a hard-won lesson into the main knowledge base with one click.

It preserves the thing that normally evaporates between sessions: not just the final decision, but the sequence of attempts, reversals, and open questions. That's the actual texture of senior-engineer context.

On privacy, briefly

A memory layer is only adoptable if it isn't a liability. Raw Slack text isn't stored. Messages hit a queue worker, structured units get extracted, and the raw text is discarded. Branch Story keeps raw session data only briefly and purges it after merge. What survives is the decisions, constraints, and lessons, not the transcript.

What I actually believe after building this

The wrong way to see Decispher is as a fancier wiki, a place you go to read. The right way is as organizational memory that shapes code generation, review, and onboarding at the moment of work, reaching into the workflow to say "wait, not like that, and here's why."

AI didn't create the tacit-knowledge problem. It just removed our ability to keep ignoring it, because now we have tireless contributors writing confident code with zero institutional memory. The fix was never a smarter model. It's giving the model, and the humans next to it, the scars, guardrails, and reasoning that used to live in one person's head and leave the day they did.

If your agents keep making context-blind mistakes, that's the gap. It's worth closing.

Decispher is a system of record for engineering decisions. If this resonated, the open-source Decision Guardian is the easiest place to start. You can find smarter version at Decispher's Website

How to tune agents trained on public data to work better with your private code

Ali Abbas — Tue, 07 Jul 2026 05:45:39 +0000

I was working in a team of 10 people on a project. We kept running into inconsistency across the codebase because everyone prompted differently and got different results. We tried maintaining a skills.md file to fix it, but it wasn’t great.

So I built Decispher (decispher.com). It's main goal is to automatically capture engineering context from across different platforms and feed it to AI agents. It also records the decisions and assumptions agents make while coding, then surfaces them back to humans. Thereby acting as shared context layer.

I’ve been running it on our own repo. It’s been genuinely helpfulcu tting token usage by 35% on a well-documented repository (ADRs and all) and by 65% on a rougher one. The models now perform much more consistently and in line with our actual decisions.

Decispher currently connects to Slack, Jira, GitHub, GitLab, AI agents, and VS Code (or any fork). It also lets you copy context from one agent chat and paste it into another chat, agent, or machine. (there are more cool and useful features)

We have made the product live. 94 seats are remaining. 50 free credits to start.

Thanks

The Knowledge That Leaves When Your Best Engineer Does

Ali Abbas — Wed, 01 Jul 2026 18:20:44 +0000

There is a particular kind of silence that falls over a team about three weeks after a senior engineer leaves. It is the silence of nobody knowing why.

Why is this flag never allowed to default to true in production? Why does this background job retry exactly twice and then stop? Why did we drop the vendor SDK and call their REST API by hand? These decisions made perfect sense at the time. Now they look insane, and nobody remembers the reason.
The person who held all of that knowledge walked out with it. What they left behind is a codebase full of decisions with the reasoning removed.
We call this a single point of failure when it is a database and treat it as an emergency. Somehow we treat it as normal when the single point of failure is a person's memory.

Documentation has not solved this

For years the answer has been "write better documentation." It keeps failing for the same reason. Documentation is a tax you pay now for a benefit someone else collects later. Humans are bad at that trade.
The wiki goes stale. The ADR folder fills up for one enthusiastic month and then goes quiet. You have seen this.

Now we have AI agents with the same problem

AI coding agents are fast and capable, but they are permanently contextless. They never accumulate the institutional memory a human picks up over years of standups and incidents.
A strong agent will cheerfully reintroduce the vendor SDK you spent a sprint removing. To the agent there is no scar. There is no scar anywhere it can read.
The cost of lost context is no longer just slower onboarding. It now also includes a fleet of fast agents that will keep walking your team into the same walls, confidently and at speed.

Capture decisions where they are made

The fix is not to write more docs. The fix is to capture the decision at the moment it is made, in the place it is already being made — including the options we considered and deliberately rejected.
Then serve that reasoning back to whoever needs it: the new hire and the AI agent alike. The reasoning should outlive the person who made it.

That is what I am building at decispher.com (it is live and 100 seats left). It will not bottle a great engineer's entire judgment. It captures the specific, costly, reusable decisions before they walk out the door.

Who on your team is the single point of failure right now? And what happens to all of that knowledge the day they give notice?

Nobody wants to review the robot's 600-line pull request

Ali Abbas — Wed, 01 Jul 2026 06:18:31 +0000

An agent opened a pull request on our service last week. Six hundred lines. It rewrote how we handle webhook retries and deduplication, an area that is fiddly and easy to get subtly wrong. The diff was clean. The tests were green. The commit messages were better than mine usually are.

And I felt the specific dread that I think a lot of engineers are starting to feel in 2026. I was the reviewer. I had not written any of this. I had no idea why it was shaped the way it was. To review it properly, the way I would want my own code reviewed, I was looking at the better part of an hour of carefully reconstructing intent from the code itself. I did not have that hour. So I did what almost everyone does in that situation, which is skim it, decide it looked reasonable, and approve.

That moment is the actual problem with AI-written code, and it is not the one people argue about.

The bottleneck moved, and most teams have not adjusted

The tired debate is whether agents write good code. In 2026 that argument is mostly over. They do. They plan, they read the codebase, they run the tests, they back out of dead ends, they open pull requests that clear most review bars. If you are still litigating whether the code is any good, you have not used a current agent in a while.

But here is what follows from that, and it is the part teams have not absorbed: if writing the code is no longer the slow step, then reviewing it is. And review does not scale the way generation does. An agent can produce five well-tested pull requests before lunch. Your senior engineers cannot deeply review five pull requests before lunch, not on top of their own work. The volume went up and the review capacity did not, and something has to give.

What gives is the depth of review. It degrades, quietly, into a skim. People approve fluent diffs they have not truly read, because reading them properly costs more time than anyone has. The green check still appears. It just means less than it used to. That is a governance failure wearing the costume of a passing review, and it is happening on a lot of teams right now without anyone deciding it should.

Why agent PRs are harder to review than human ones

It is worth being precise about why this is worse than the human version of the same problem.

When a teammate sends you a pull request, you usually share context with them. You were in the standup. You saw the thread. You know roughly why they are doing this and what constraints they are under. You review the diff against intent you already hold in your head.

With an agent PR, that shared context is gone. You are handed a substantial, confident, well-structured diff and no narrative of why it is shaped the way it is. You cannot ask the agent in the hallway. So reviewing it well means reconstructing intent purely from the code, which is slow, error-prone, and exactly the work that gets skipped under time pressure. The fluency makes it worse, not better, because fluent code invites you to assume the thinking behind it was equally sound.

The mistakes that survive this are not syntax. They are contextual. The agent leaned on an assumption that is true in general and false for your system. In our case, the dedup rewrite quietly assumed webhooks could be deduplicated on payload, when our whole reason for keying on a separate idempotency field was that one upstream sends byte-identical payloads for genuinely distinct events. Perfectly reasonable code. Wrong for us, for a reason that lives in our history and nowhere in the diff.

You cannot fix this by reviewing harder

The instinctive responses do not hold up.

"Review everything as carefully as before" does not survive contact with rising volume. The math does not work. "Trust the agent" is not a governance posture, it is the absence of one. "Add more CI rules" helps with the syntactic class of problem that is already mostly solved, and does little for architectural mistakes, because a contextual violation is not a lint rule, it is a conflict with a decision your team made that no checker knows about.

The thing that actually changes the equation is not reviewing harder. It is changing what review consumes.

Read the reasoning first, the diff second

Here is the shift. Instead of handing a reviewer a raw diff and asking them to reverse-engineer the intent, hand them the story of how the work came to be, first. The decisions it relied on. The constraints it was operating under. The context it was given before it started. The questions it hit and who answered them. The approaches it tried and reverted. The points where a human stepped in and steered it.

Then the reviewer reads that narrative, and reads the diff second, with intent already established. A contextual mistake that is invisible when you are staring at code becomes obvious the moment you can see the reasoning behind it. If I had seen, up front, that the agent's plan rested on deduplicating by payload, I would have caught it in five seconds, because I know why that is wrong here. Buried in six hundred lines, I missed it entirely.

This is what I am building as Branch Story. For any branch or pull request, it reconstructs that narrative, grounded in your team's actual captured decisions rather than guessed from the diff. It reads as a story of how the work happened, not a log dump, because a log dump is just more material to skim and the entire point is to stop skimming.

It works for human-written branches too, which matters more than it sounds. A teammate reviewing a teammate gets the same narrative, so review becomes consistent across human and agent work instead of being two different activities. And honestly, that consistency is part of what makes a team willing to let an agent open pull requests at all. The blocker on agent autonomy was never whether the agent could write the code. It is whether a human can responsibly sign off on it. Trust is the unlock, and trust comes from being able to see the why quickly.

What it does not do

I want to be straight about the limits, because overselling this would be its own kind of damage. Branch Story does not replace your judgment and it does not certify that code is correct. It makes the why legible so your judgment is fast and accurate instead of slow and guessed. And it is only as good as the context behind it, if your team's decisions are not captured anywhere, there is no story to reconstruct, which is exactly why the capture side is the hard part and where most of my work goes.

But the direction feels right to me. As more of the code gets written by something that cannot explain itself in the hallway, the scarce resource is not code and it is not review hours. It is legible intent. That is the thing worth building.

When you review an agent's pull request, are you reading it, or are you approving it? Be honest. That gap is the whole problem.

decispher.com
VS code extension

Stop hand-maintaining your .cursorrules. It's already lying to your agent.

Ali Abbas — Wed, 01 Jul 2026 06:12:18 +0000

You did the responsible thing. You added a rules file for your AI tool,
.cursorrules or CLAUDE.md or an AGENTS.md, and you wrote down the important constraints by hand. For about a week it was great.

Then entropy showed up. Your team made four new decisions and none of the Slack ones made it into the file. Someone changed the caching strategy and the rules file still describes the old one. A constraint got relaxed and nobody updated the line that enforces it. Now your agent is confidently applying last quarter's architecture, which is strictly worse than no rules at all, because it carries authority while being wrong.

This is the exact failure that kills architecture decision records, and it kills them for a structural reason, not a discipline reason. A hand-maintained context artifact depends on a human stopping, mid-flow, to write down something whose payoff is deferred and uncertain. Humans do not do that reliably. They never have. Betting your agent's correctness on it is betting on the one behavior we have decades of evidence people will not sustain.

And the cost is higher now than in the ADR days, because you are not just informing future humans. You are steering a fast agent that will take a stale rule and propagate it across a dozen files before lunch.

So what is the alternative? Invert the default. Stop asking people to transcribe decisions into a file. Capture them where the decision already happens (the PR thread where you argued it out, the Slack channel where it was settled, the ticket where the constraint was set), pull out the choice and the reasoning and the rejected alternatives, and generate the agent-readable rules from that, continuously. The file stops being a thing a tired human curates and becomes a projection of decisions your team is already making anyway.

A few things I have learned building this:

The rejected option is the highest-value field and the one every existing tool throws away. "We tried X, it failed this way, do not bring it back" is what actually prevents the agent from regressing you.
Decisions are cross-surface. The why is split across Slack and GitHub and Jira, so anything single-surface is blind to most of it.
Write time beats review time. A constraint the agent reads before generating is worth ten warnings after.

If your rules file has five obvious entries and none of the hard-won ones, this is why. It is not your discipline. It is the format fighting human nature.

What is the oldest line in your rules file, and is it still even true?

Visit Decispher for the solution

Your AI agent keeps rebuilding decisions your team already made. Here's the fix I landed on.

Ali Abbas — Mon, 29 Jun 2026 07:43:37 +0000

Coding agents have no memory of why your codebase is the way it is. They
re-derive settled decisions every session, confidently redo things your team
already ruled out, and burn tokens doing it. I tried the three obvious fixes (a
CLAUDE.md file, RAG over our docs, pasting context manually) and each broke in
a specific way. What finally worked: stop treating decisions as a doc to
maintain and start serving them to the agent over MCP, scoped to the file it's
touching. Disclosure at the bottom: I built one of the tools I mention.

The actual problem

We're a small backend team living in Cursor and Claude Code. The failure mode
shows up every few days: an agent ships something clean-looking that violates a
rule nobody wrote down. The library we banned after it bit us in prod. The
migration you cannot touch. The pattern we already tried, that failed for a real
reason, that the agent happily reintroduces.

The knowledge exists. It's just scattered across Slack threads, old PR
discussions, and Jira comments. None of those are places an agent looks, and
honestly none are places the next human looks either.

The three fixes everyone tries first

1. A CLAUDE.md / .cursorrules file

Fine for a handful of stable conventions. Breaks on staleness (wrong the moment
a decision changes, nobody updates it) and budget (you can't fit real decision
history without eating your whole context window every turn).

2. RAG over Notion / your docs

Semantic is not relevant. Vector search pulls things that sound similar to the
file, not the decision that governs it, and noise in the window degrades
output. Also, half your real decisions were never written down; they happened in
a thread.

3. Pasting context by hand

Works until I get lazy, which is turn two. Scales to exactly one person.

The shift that worked: serve decisions, don't store them

A decision is not a document you maintain. It's something the agent fetches on
demand. Instead of a static rules file in every call, the agent makes a tool
call over MCP and pulls only the decisions relevant to the file it's editing.
Touch the auth code, get the auth decisions. Scoped, current, not a stale blob.

{
  "mcpServers": {
    "decispher": {
      "command": "npx",
      "args": ["-y", "@decispher/mcp-server"],
      "env": {
        "DECISPHER_API_KEY": "dcp_xxx",
        "DECISPHER_COMPANY_ID": "your_company_id"
      }
    }
  }
}

The other half is capture: a rules file you write by hand stays empty, so the
decisions get extracted automatically from Slack, GitHub, and Jira instead.

The part I didn't expect to care about: receipts

Every retrieval is measured. Each tool call logs the tokens it saved versus
making the agent rediscover that context the slow way.

get_context_for_file   auth        480 tk served   ↓ 3,840 saved
check_conventions      database    212 tk served   ↓ 1,696 saved
tokens_saved_net · 6,976 · ≈ $0.061 this session

Most "AI that knows your context" claims are unmeasurable vibes. A per-call
token number means I can actually tell if it's pulling its weight.

What I'm still unsure about

Is per-file the right retrieval granularity, or per-symbol / per-topic?
How do you keep captured decisions from going stale like a wiki does?
Where's the line between serving everything relevant and blowing the budget?

Disclosure

I built the tool the examples come from (Decispher, in beta, free cohort open).
I left it to the end because the pattern stands on its own. decispher.com if you
want to try it. If you solve this differently, tell me in the comments.

Stop Repeating Yourself: How to Automate Architectural Context in GitHub PRs

Ali Abbas — Sat, 14 Feb 2026 10:07:42 +0000

We've all been there. You're reviewing a pull request from a junior developer, and for what feels like the tenth time this month, you're typing out the same comment:

"Hey, we don't use console.log in production code—please use our structured logger."

The dev apologizes, updates the code, and you approve the PR. Two weeks later, a different developer makes the exact same mistake. Rinse and repeat.

Sound familiar?

The Real Problem: The Documentation-Implementation Gap

Here's the thing: your team's architectural decisions live in documents that nobody reads, while the actual work happens in code.

You probably have an Architecture Decision Record (ADR) somewhere that clearly states: "We use Winston for structured logging, not console.log." It's documented. It's in Confluence. It might even be in your repository's /docs folder.

But let's be honest—when was the last time a developer actively searched through ADRs before writing code?

The problem isn't your team. The problem is expecting humans to remember and enforce dozens of architectural constraints manually. That's not scalable, and it leads to:

Review fatigue: Senior devs waste time repeating the same feedback
Inconsistent codebases: Some violations slip through when reviewers are tired
Slower onboarding: New team members learn by making mistakes instead of prevention
Context switching: Developers have to context-switch between code and documentation

What if there was a better way?

The Solution: Context-as-Code

Instead of keeping architectural decisions in separate documentation, what if we could encode them directly into our development workflow?

This is the concept of "Context-as-Code"—taking your team's architectural decisions and automating their enforcement at the exact moment they matter: during pull requests.

Think of it like this: instead of a senior developer manually checking every PR for violations, you create automated rules that check for you. The PR author gets immediate feedback, learns the constraint, and your reviewers can focus on actual architecture and logic instead of style guide enforcement.

Enter Decision Guardian

Decision Guardian is a GitHub Action that bridges this gap. It automatically surfaces architectural decisions and critical context when Pull Requests modify protected files. Instead of relying on tribal knowledge, Decision Guardian proactively alerts teams when changes touch sensitive code.

Here's what makes it powerful:

Automated context surfacing: Automatically posts PR comments when protected files change
Markdown-based decisions: Write decisions in simple markdown format
Flexible file matching: Supports glob patterns and advanced rule evaluation
Non-blocking: Configurable to either block merges or just warn
Zero external calls: Runs entirely within your GitHub Actions runner—no data leaves GitHub

Let's dive into what this looks like in practice.

The Cool Stuff: Deep Dive into Features

Simple File-Based Decisions

The core concept is beautifully simple: you write architectural decisions in markdown and link them to file patterns. When someone opens a PR that touches those files, they automatically see the context.

Here's a basic example for protecting your database configuration:

<!-- DECISION-DB-001 -->
## Decision: Connection Pool Size

**Status**: Active  
**Date**: 2024-01-15  
**Severity**: Critical

**Files**:
- `src/db/pool.ts`
- `config/database.yml`

### Context

Pool size fixed at 20 connections to prevent exhaustion.

Tested with production load (5K req/s). Higher values caused
connection leaks under sustained traffic.

**Do not modify without load testing.**

---

That's it! When someone modifies src/db/pool.ts or config/database.yml, this decision automatically appears as a comment on their PR.

Advanced Rules with Regex

For more sophisticated scenarios, you can embed JSON-based rules directly in your markdown to detect patterns in code:

<!-- DECISION-SEC-001 -->
## Decision: No Hardcoded Credentials

**Status**: Active  
**Date**: 2024-02-01  
**Severity**: Critical

**Rules**:
\`\`\`json
{
  "type": "file",
  "pattern": "src/**/*.{ts,js}",
  "exclude": "**/*.test.{ts,js}",
  "content_rules": [
    {
      "mode": "regex",
      "pattern": "(password|api[_-]?key|secret)\\s*[=:]\\s*['\"][^'\"]+['\"]",
      "flags": "i"
    }
  ]
}
\`\`\`

### Context

Detects hardcoded credentials. Use environment variables
or AWS Secrets Manager instead.

---

This rule will trigger when someone adds code like const password = "secret123" in a JavaScript/TypeScript file.

JSONPath for Configuration Files

You can also use JSONPath to validate specific values in JSON files:

<!-- DECISION-API-002 -->
## Decision: API Rate Limit Configuration

**Status**: Active  
**Date**: 2024-03-10  
**Severity**: Warning

**Rules**:
\`\`\`json
{
  "type": "file",
  "pattern": "config/api.json",
  "content_rules": [
    {
      "mode": "json_path",
      "path": "$.rateLimit.maxRequests",
      "expected": 100
    }
  ]
}
\`\`\`

### Context

Rate limit must stay at 100 requests/minute. Changes can:
- Block legitimate users (too strict)
- Allow abuse (too loose)

Before modifying, test with production traffic patterns.

---

Setting This Up (It's Easier Than You Think)

The beauty of Decision Guardian is its simplicity. No complex YAML configuration files—just markdown documents.

Step 1: Create Your Decisions File

Create .decispher/decisions.md in your repository:

<!-- 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.

**Alternatives rejected:**
- MongoDB: No ACID guarantees
- Redis: Added unnecessary complexity

**Related:**
- [Slack thread](https://your-workspace.slack.com/archives/...)
- [Architecture review](https://your-docs.com/...)

---

Step 2: Add the GitHub Action

Create .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: true

Step 3: Test It Out

Create a test PR that modifies src/db/pool.ts and watch Decision Guardian automatically comment with the full context from DECISION-DB-001.

That's really it. No complex configuration files, no YAML sprawl—just markdown documents with your decisions.

What Makes This Different

You might be thinking: "Isn't this just like CODEOWNERS or linting?"

Not quite. Here's the key difference:

CODEOWNERS assigns reviewers but doesn't explain why review matters
Linting catches syntax errors but not architectural violations
Decision Guardian provides context at the exact moment it's needed

When someone modifies your database connection pool, they don't just get an error—they get the full story: what the decision was, why it was made, what was tested, and who to talk to if they really need to change it.

Real-World Scenarios

Here are some practical examples of decisions teams protect with Decision Guardian:

Security patterns:

No hardcoded credentials
Required authentication middleware
Specific encryption algorithms

Performance constraints:

Database connection pool limits
API rate limiting configurations
Cache invalidation strategies

Architecture boundaries:

Microservice communication patterns
Dependency injection requirements
Database access patterns

Business logic:

Payment processing flows
Data retention policies
Feature flag configurations

Real-World Impact

After implementing Decision Guardian, teams typically see:

Faster reviews: Senior developers spend less time on repetitive feedback
Better onboarding: New developers learn architectural constraints immediately
Consistent codebases: Violations get caught automatically, not sporadically
Living documentation: ADRs become actionable, not just informational
Knowledge preservation: Critical context survives even when team members leave

The real win isn't just catching violations—it's educating developers about why those violations matter. Each PR comment becomes a teaching moment.

Getting Started

The easiest way to start is to identify the top 3-5 architectural decisions you find yourself repeating in code reviews. Document them in markdown format, link them to the relevant files, and let Decision Guardian handle the rest.

Start small:

Pick one decision that causes the most friction
Document it in .decispher/decisions.md
Add the GitHub Action
Observe what happens over the next week

You can always expand from there.

Conclusion: Bridge the Gap

Decision Guardian represents a shift in how we think about documentation. Instead of static documents that live separately from our code, we can embed our architectural knowledge directly into the development workflow—right where developers need it.

This doesn't replace code review—it enhances it. Your senior developers can focus on architectural discussions, design patterns, and business logic instead of catching the same violations over and over.

If you're tired of repeating yourself in PR comments, give Decision Guardian a try. It's open source, free to use, and might just save your team hundreds of hours.

Resources

Website: https://decision-guardian.decispher.com/
Documentation: https://decision-guardian.decispher.com/docs
GitHub Repository: https://github.com/DecispherHQ/decision-guardian
GitHub Marketplace: Decision Guardian Action

Have you tried automating architectural decisions in your workflow? What challenges have you faced with keeping documentation and code in sync? Let me know in the comments!

How I Addressed the Real Pain Behind ADRs Enforcement?

Ali Abbas — Tue, 10 Feb 2026 12:45:03 +0000

Description

Technical deep-dive on building a GitHub Action that prevents institutional amnesia by surfacing past architectural decisions on Pull Requests

I spent 3 years building systems. During that time, I watched teams waste months repeatedly debating architectural decisions they'd already made. We use ADRs in our company, but enforcement is inconsistent - only senior devs remember to update them.

So I built Decision Guardian - a GitHub Action that surfaces past architectural decisions directly on Pull Requests.

Here's how I did it, and the technical challenges I solved along the way.

The Solution: Decision Guardian

Decision Guardian is a GitHub Action that:

Parses architectural decisions from markdown files
Matches them against PR file changes
Surfaces relevant context automatically as a comment

Example 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`

### Context

We chose Postgres over MongoDB because billing requires 
ACID compliance for financial transactions.

**Alternatives rejected:**
- MongoDB: No ACID guarantees
- Redis: Added unnecessary complexity

**Before modifying:** Consult with @tech-lead

---

When someone opens a PR touching src/db/pool.ts, Decision Guardian reacts.

Technical Challenge #1: Pattern Matching at Scale

The Naive Approach (O(N×M))

My first implementation was simple:

// For each file in PR
for (const file of prFiles) {
  // Check against every decision
  for (const decision of decisions) {
    if (decision.files.includes(file.path)) {
      matches.push(decision);
    }
  }
}

Problem: With 100 files and 500 decisions = 50,000 comparisons

On a large PR (3000 files), this took 12+ seconds and sometimes hit GitHub Actions timeout.

The Solution: Prefix Trie

I built a prefix trie to index decisions by file patterns:

interface TrieNode {
  children: Map;
  decisions: Decision[];
  wildcardDecisions: Decision[];
}

class PatternTrie {
  private root: TrieNode;

  constructor(decisions: Decision[]) {
    this.root = this.createNode();
    for (const decision of decisions) {
      for (const pattern of decision.files) {
        this.insert(pattern, decision);
      }
    }
  }

  private createNode(): TrieNode {
    return {
      children: new Map(),
      decisions: [],
      wildcardDecisions: [],
    };
  }

  private insert(pattern: string, decision: Decision): void {
    const parts = pattern.split('/');
    this.insertRecursive(this.root, parts, decision);
  }

  private insertRecursive(node: TrieNode, parts: string[], decision: Decision): void {
    if (parts.length === 0) {
      node.decisions.push(decision);
      return;
    }

    const part = parts[0];
    const remaining = parts.slice(1);

    // Handle wildcards specially
    if (part === '**') {
      node.wildcardDecisions.push(decision);
      if (remaining.length > 0) {
        this.insertRecursive(node, remaining, decision);
      }
      return;
    }

    // Handle glob patterns
    if (
      part.includes('*') ||
      part.includes('?') ||
      part.includes('{') ||
      part.includes('}') ||
      part.includes('[') ||
      part.includes(']')
    ) {
      node.wildcardDecisions.push(decision);
      return;
    }

    // Exact match - traverse deeper
    let child = node.children.get(part);
    if (!child) {
      child = this.createNode();
      node.children.set(part, child);
    }

    this.insertRecursive(child, remaining, decision);
  }

  /**
   * Returns a set of unique decisions that *might* match the given file path.
   */
  findCandidates(file: string): Set {
    const parts = file.split('/');
    const candidates = new Set();

    this.collectCandidates(this.root, parts, candidates);

    return candidates;
  }

  private collectCandidates(node: TrieNode, parts: string[], candidates: Set): void {
    // Collect wildcard matches at this level
    for (const decision of node.wildcardDecisions) {
      candidates.add(decision);
    }

    if (parts.length === 0) {
      // Reached the end - collect exact matches
      for (const decision of node.decisions) {
        candidates.add(decision);
      }
      return;
    }

    const part = parts[0];
    const child = node.children.get(part);
    if (child) {
      this.collectCandidates(child, parts.slice(1), candidates);
    }
  }
}

Performance improvement:

Before: O(N×M) → 12 seconds for 3000 files
After: O(M × log D) → 2.8 seconds for same PR

That's a 4.3x speedup on large PRs.

Technical Challenge #2: Security (ReDoS Protection)

The Problem

Users can define custom patterns using regex:

{
  "type": "file",
  "pattern": "src/**/*.ts",
  "content_rules": [{
    "mode": "regex",
    "pattern": "(a+)+b"  // ⚠️ Evil regex
  }]
}

That pattern (a+)+b is vulnerable to ReDoS (Regular Expression Denial of Service).

When tested against aaaaaaaaaaaaaaaaaaaa (no 'b'), it creates exponential backtracking:

20 'a's: ~1 second
25 'a's: ~30 seconds
30 'a's: freeze forever

This could DOS the entire GitHub Action.

The Solution: Multi-Layer Protection

Layer 1: Safe-Regex Check

import safeRegex from 'safe-regex';

function validatePattern(pattern: string): void {
  if (!safeRegex(pattern)) {
    throw new Error(`Unsafe regex pattern: ${pattern}`);
  }
}

Layer 2: VM Sandbox with Timeout

Even safe-regex can miss some cases, so I added a VM sandbox:

import vm from 'vm';

function runRegexWithTimeout(pattern: string, flags: string, text: string, timeoutMs: number): boolean {
  const sandbox = Object.create(null);
  sandbox.result = false;
  sandbox.text = String(text);
  sandbox.pattern = String(pattern);
  sandbox.flags = String(flags || '');

  const context = vm.createContext(sandbox, {
    name: 'RegexSandbox',
    codeGeneration: {
      strings: false,
      wasm: false,
    },
  });

  const code = `
    'use strict';
    try {
      const regex = new RegExp(pattern, flags);
      result = regex.test(text);
    } catch (e) {
      result = false;
    }
  `;

  try {
    vm.runInContext(code, context, {
      timeout: timeoutMs,
      displayErrors: false,
    });
    return Boolean(sandbox.result);
  } catch (e) {
    return false;
  }
}

Key security features:

✅ Isolated VM context - No access to Node.js globals or filesystem
✅ Hard timeout - Kills execution after 5 seconds
✅ No code generation - Prevents eval() and WebAssembly escapes
✅ String coercion - Prevents prototype pollution

Layer 3: Input Size Limits

const MAX_CONTENT_SIZE = 1_000_000; // 1MB
const MAX_REGEX_LENGTH = 1000;

if (content.length > MAX_CONTENT_SIZE) {
  throw new Error('Content too large for regex matching');
}

if (pattern.length > MAX_REGEX_LENGTH) {
  throw new Error('Regex pattern too long');
}

Layer 4: Result Caching

import crypto from 'crypto';

class ContentMatchers {
  private resultCache = new Map();
  private readonly MAX_CACHE_SIZE = 500;

  private createCacheKey(pattern: string, flags: string, content: string): string {
    const contentHash = crypto
      .createHash('sha256')
      .update(content)
      .digest('hex')
      .substring(0, 16);
    return `${pattern}:${flags}:${contentHash}`;
  }

  async matchRegex(rule: ContentRule, fileDiff: FileDiff): Promise {
    const changedContent = this.getChangedLines(fileDiff.patch).join('\n');
    const cacheKey = this.createCacheKey(rule.pattern!, rule.flags || '', changedContent);

    const cached = this.resultCache.get(cacheKey);
    if (cached !== undefined) {
      return { matched: cached, matchedPatterns: cached ? [rule.pattern!] : [] };
    }

    try {
      const matched = this.runRegexWithTimeout(
        rule.pattern!, 
        rule.flags, 
        changedContent, 
        5000
      );

      this.updateCache(cacheKey, matched);
      return { matched, matchedPatterns: matched ? [rule.pattern!] : [] };
    } catch (error) {
      return { matched: false, matchedPatterns: [] };
    }
  }

  private updateCache(key: string, value: boolean): void {
    if (this.resultCache.size >= this.MAX_CACHE_SIZE) {
      // LRU eviction
      const firstKey = this.resultCache.keys().next().value;
      if (firstKey) this.resultCache.delete(firstKey);
    }
    this.resultCache.set(key, value);
  }
}

Result: Zero ReDoS vulnerabilities in production. ✅

Technical Challenge #3: Handling Massive PRs

The Problem

Some PRs modify 3000+ files (dependency updates, refactors, migrations).

GitHub's API returns all changed files, but:

Loading 3000 file diffs into memory → OOM (Out of Memory)
Processing them serially → timeout
Posting a comment with all matches → exceeds GitHub's 65KB limit

Solution 1: Streaming Processing

Instead of loading all files at once:

async function* streamFileDiffs(
  token: string
): AsyncGenerator {
  const octokit = github.getOctokit(token);
  const { owner, repo, pull_number } = github.context;

  let page = 1;
  const MAX_PAGES = 30;

  while (page <= MAX_PAGES) {
    const { data } = await octokit.rest.pulls.listFiles({
      owner,
      repo,
      pull_number,
      per_page: 100,
      page,
    });

    if (data.length === 0) break;

    yield data.map((f) => ({
      filename: f.filename.replace(/\\/g, '/'),
      status: f.status as FileDiff['status'],
      additions: f.additions,
      deletions: f.deletions,
      changes: f.changes,
      patch: f.patch || '',
      previous_filename: f.previous_filename,
    }));

    if (data.length < 100) break;
    page++;
  }
}

// Usage
const matches: DecisionMatch[] = [];
for await (const batch of streamFileDiffs(token)) {
  const batchMatches = await matcher.findMatchesWithDiffs(batch);
  matches.push(...batchMatches);

  core.info(`Processed ${batch.length} files, found ${matches.length} matches so far`);
}

Memory usage:

Before: High memory usage for 3000 files → OOM risk
After: Constant memory (processes 100 files at a time) → No crashes ✅

Solution 2: Progressive Truncation

If the comment exceeds GitHub's limit, truncate intelligently:

function truncateComment(decisions: Decision[], maxLength = 65000): string {
  let comment = formatComment(decisions);

  if (comment.length <= maxLength) {
    return comment;
  }

  // Layer 1: Show 20 decisions in detail, summarize rest
  comment = formatComment(decisions, { detailLimit: 20 });
  if (comment.length <= maxLength) return comment;

  // Layer 2: Show 10 decisions in detail
  comment = formatComment(decisions, { detailLimit: 10 });
  if (comment.length <= maxLength) return comment;

  // Layer 3: Show 5 decisions in detail
  comment = formatComment(decisions, { detailLimit: 5 });
  if (comment.length <= maxLength) return comment;

  // Layer 4: Show 2 decisions in detail
  comment = formatComment(decisions, { detailLimit: 2 });
  if (comment.length <= maxLength) return comment;

  // Layer 5: Show counts only
  comment = formatCommentCounts(decisions);
  if (comment.length <= maxLength) return comment;

  // Layer 6: Hard truncate as last resort
  return hardTruncate(comment, maxLength);
}

Result: Never hit comment size limit, even with 1000+ matched decisions. ✅

Technical Challenge #4: Idempotent Comments

The Problem

GitHub Actions can run multiple times for a single PR:

New commit pushed
Workflow re-run
Manual trigger

Without proper handling:

3 runs = 3 duplicate comments
Spams the PR thread
Confuses reviewers

The Solution: Content Hash

async function upsertComment(
  prNumber: number,
  content: string
): Promise {
  const hash = crypto
    .createHash('sha256')
    .update(content)
    .digest('hex')
    .substring(0, 16);

  const marker = ``;
  const hashMarker = ``;
  const fullContent = `${marker}\n${hashMarker}\n\n${content}`;

  // Find existing comment
  const comments = await octokit.issues.listComments({
    owner,
    repo,
    issue_number: prNumber,
  });

  const existing = comments.data.find(c =>
    c.body?.includes('decision-guardian-v1')
  );

  if (existing) {
    const existingHash = existing.body?.match(/hash:([a-f0-9-]+)/)?.[1];

    if (existingHash === hash) {
      console.log('Comment unchanged, skipping update');
      return;
    }

    // Update existing comment
    await octokit.issues.updateComment({
      owner,
      repo,
      comment_id: existing.id,
      body: fullContent,
    });
  } else {
    // Create new comment
    await octokit.issues.createComment({
      owner,
      repo,
      issue_number: prNumber,
      body: fullContent,
    });
  }
}

Result:

✅ Single comment per PR

✅ Updates in-place when decisions change

✅ No spam, no duplicates

Architecture Overview

┌────────────────────────────────────────────────────┐
│                  DECISION GUARDIAN                 │
├────────────────────────────────────────────────────┤
│                                                    │
│  ┌──────────────────────────────────────────────┐  │
│  │         DECISION PARSER (AST-based)          │  │
│  │  - Markdown parsing with remark              │  │
│  │  - JSON rule extraction & validation         │  │
│  └──────────────────────────────────────────────┘  │
│                      ↓                             │
│  ┌──────────────────────────────────────────────┐  │
│  │      DECISION INDEX (Prefix Trie)            │  │
│  │  - O(log n) file lookup                      │  │
│  │  - Wildcard pattern optimization             │  │
│  └──────────────────────────────────────────────┘  │
│                      ↓                             │
│  ┌──────────────────────────────────────────────┐  │
│  │         FILE MATCHER (Rule Evaluator)        │  │
│  │  - Glob pattern matching                     │  │
│  │  - Content diff analysis                     │  │
│  │  - ReDoS protection                          │  │
│  └──────────────────────────────────────────────┘  │
│                      ↓                             │
│  ┌──────────────────────────────────────────────┐  │
│  │      COMMENT MANAGER (Idempotent)            │  │
│  │  - Hash-based update detection               │  │
│  │  - Progressive truncation                    │  │
│  │  - Retry with exponential backoff            │  │
│  └──────────────────────────────────────────────┘  │
│                                                    │
└────────────────────────────────────────────────────┘

High-level flow:

PR Created → Parse Decisions → Match Files → Post Comment → Check Status

Key components:

Parser (parser.ts): Markdown → structured data
Matcher (matcher.ts): Trie-based file matching
Rule Evaluator (rule-evaluator.ts): Advanced rules
Comment Manager (comment.ts): Idempotent PR comments

Lessons Learned

1. Performance matters from day 1

I could have shipped with the O(N×M) algorithm and optimized later.

But teams with large PRs would have hit timeouts immediately and never come back.

Lesson: Build for scale early, especially in tools that run on every PR.

2. Security is not optional

The ReDoS vulnerability wasn't theoretical - during testing, a user accidentally created a pattern that froze the action for 5 minutes.

Lesson: Validate all user input, especially anything that can loop or recurse.

3. Idempotency prevents pain

Early versions created duplicate comments. Users reported it as "spammy" and disabled the action.

Adding content hashing fixed this and improved adoption.

Lesson: Make actions side-effect-free and repeatable.

4. Documentation > features

I spent 60% of development time on README, examples, and error messages.

Users still ask "how do I use this?" constantly.

Lesson: You can never document enough.

Try It Yourself

Install:

- uses: DecispherHQ/decision-guardian@v1
  with:
    token: ${{ secrets.GITHUB_TOKEN }}

Example decision:


## Decision: Database Choice

**Status**: Active  
**Date**: 2024-03-15  
**Files**: `src/db/**`

### Context
We chose Postgres for ACID compliance.
Rejected: MongoDB (no ACID), Redis (complexity)

Links:

GitHub: https://github.com/DecispherHQ/decision-guardian
Docs: https://decision-guardian.decispher.com
Marketplace: https://github.com/marketplace/actions/decision-guardian

What's Next?

Short-term:

GitLab/Bitbucket support (if demand exists)
Decision templates

Long-term:

VS Code extension (show decisions inline)
Analytics dashboard
Cross-repository rules

Want to contribute? Open an issue or start a discussion.

Conclusion

Decision Guardian is free, open source (MIT), and takes 2 minutes to set up.

What architectural decisions does your team repeatedly debate?

Drop a comment - I'd love to hear your stories.

Made with ❤️ by Ali Abbas

How I Addressed the Real Pain Behind ADRs Enforcement

Ali Abbas — Tue, 10 Feb 2026 12:42:39 +0000

Description

Technical deep-dive on building a GitHub Action that prevents institutional amnesia by surfacing past architectural decisions on Pull Requests

So I built Decision Guardian - a GitHub Action that surfaces past architectural decisions directly on Pull Requests.

Here's how I did it, and the technical challenges I solved along the way.

The Solution: Decision Guardian

Decision Guardian is a GitHub Action that:

Parses architectural decisions from markdown files
Matches them against PR file changes
Surfaces relevant context automatically as a comment

Example 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`

### Context

We chose Postgres over MongoDB because billing requires 
ACID compliance for financial transactions.

**Alternatives rejected:**
- MongoDB: No ACID guarantees
- Redis: Added unnecessary complexity

**Before modifying:** Consult with @tech-lead

---

When someone opens a PR touching src/db/pool.ts, Decision Guardian reacts.

Technical Challenge #1: Pattern Matching at Scale

The Naive Approach (O(N×M))

My first implementation was simple:

// For each file in PR
for (const file of prFiles) {
  // Check against every decision
  for (const decision of decisions) {
    if (decision.files.includes(file.path)) {
      matches.push(decision);
    }
  }
}

Problem: With 100 files and 500 decisions = 50,000 comparisons

On a large PR (3000 files), this took 12+ seconds and sometimes hit GitHub Actions timeout.

The Solution: Prefix Trie

I built a prefix trie to index decisions by file patterns:

interface TrieNode {
  children: Map;
  decisions: Decision[];
  wildcardDecisions: Decision[];
}

class PatternTrie {
  private root: TrieNode;

  constructor(decisions: Decision[]) {
    this.root = this.createNode();
    for (const decision of decisions) {
      for (const pattern of decision.files) {
        this.insert(pattern, decision);
      }
    }
  }

  private createNode(): TrieNode {
    return {
      children: new Map(),
      decisions: [],
      wildcardDecisions: [],
    };
  }

  private insert(pattern: string, decision: Decision): void {
    const parts = pattern.split('/');
    this.insertRecursive(this.root, parts, decision);
  }

  private insertRecursive(node: TrieNode, parts: string[], decision: Decision): void {
    if (parts.length === 0) {
      node.decisions.push(decision);
      return;
    }

    const part = parts[0];
    const remaining = parts.slice(1);

    // Handle wildcards specially
    if (part === '**') {
      node.wildcardDecisions.push(decision);
      if (remaining.length > 0) {
        this.insertRecursive(node, remaining, decision);
      }
      return;
    }

    // Handle glob patterns
    if (
      part.includes('*') ||
      part.includes('?') ||
      part.includes('{') ||
      part.includes('}') ||
      part.includes('[') ||
      part.includes(']')
    ) {
      node.wildcardDecisions.push(decision);
      return;
    }

    // Exact match - traverse deeper
    let child = node.children.get(part);
    if (!child) {
      child = this.createNode();
      node.children.set(part, child);
    }

    this.insertRecursive(child, remaining, decision);
  }

  /**
   * Returns a set of unique decisions that *might* match the given file path.
   */
  findCandidates(file: string): Set {
    const parts = file.split('/');
    const candidates = new Set();

    this.collectCandidates(this.root, parts, candidates);

    return candidates;
  }

  private collectCandidates(node: TrieNode, parts: string[], candidates: Set): void {
    // Collect wildcard matches at this level
    for (const decision of node.wildcardDecisions) {
      candidates.add(decision);
    }

    if (parts.length === 0) {
      // Reached the end - collect exact matches
      for (const decision of node.decisions) {
        candidates.add(decision);
      }
      return;
    }

    const part = parts[0];
    const child = node.children.get(part);
    if (child) {
      this.collectCandidates(child, parts.slice(1), candidates);
    }
  }
}

Performance improvement:

Before: O(N×M) → 12 seconds for 3000 files
After: O(M × log D) → 2.8 seconds for same PR

That's a 4.3x speedup on large PRs.

Technical Challenge #2: Security (ReDoS Protection)

The Problem

Users can define custom patterns using regex:

{
  "type": "file",
  "pattern": "src/**/*.ts",
  "content_rules": [{
    "mode": "regex",
    "pattern": "(a+)+b"  // ⚠️ Evil regex
  }]
}

That pattern (a+)+b is vulnerable to ReDoS (Regular Expression Denial of Service).

When tested against aaaaaaaaaaaaaaaaaaaa (no 'b'), it creates exponential backtracking:

20 'a's: ~1 second
25 'a's: ~30 seconds
30 'a's: freeze forever

This could DOS the entire GitHub Action.

The Solution: Multi-Layer Protection

Layer 1: Safe-Regex Check

import safeRegex from 'safe-regex';

function validatePattern(pattern: string): void {
  if (!safeRegex(pattern)) {
    throw new Error(`Unsafe regex pattern: ${pattern}`);
  }
}

Layer 2: VM Sandbox with Timeout

Even safe-regex can miss some cases, so I added a VM sandbox:

import vm from 'vm';

function runRegexWithTimeout(pattern: string, flags: string, text: string, timeoutMs: number): boolean {
  const sandbox = Object.create(null);
  sandbox.result = false;
  sandbox.text = String(text);
  sandbox.pattern = String(pattern);
  sandbox.flags = String(flags || '');

  const context = vm.createContext(sandbox, {
    name: 'RegexSandbox',
    codeGeneration: {
      strings: false,
      wasm: false,
    },
  });

  const code = `
    'use strict';
    try {
      const regex = new RegExp(pattern, flags);
      result = regex.test(text);
    } catch (e) {
      result = false;
    }
  `;

  try {
    vm.runInContext(code, context, {
      timeout: timeoutMs,
      displayErrors: false,
    });
    return Boolean(sandbox.result);
  } catch (e) {
    return false;
  }
}

Key security features:

✅ Isolated VM context - No access to Node.js globals or filesystem
✅ Hard timeout - Kills execution after 5 seconds
✅ No code generation - Prevents eval() and WebAssembly escapes
✅ String coercion - Prevents prototype pollution

Layer 3: Input Size Limits

const MAX_CONTENT_SIZE = 1_000_000; // 1MB
const MAX_REGEX_LENGTH = 1000;

if (content.length > MAX_CONTENT_SIZE) {
  throw new Error('Content too large for regex matching');
}

if (pattern.length > MAX_REGEX_LENGTH) {
  throw new Error('Regex pattern too long');
}

Layer 4: Result Caching

import crypto from 'crypto';

class ContentMatchers {
  private resultCache = new Map();
  private readonly MAX_CACHE_SIZE = 500;

  private createCacheKey(pattern: string, flags: string, content: string): string {
    const contentHash = crypto
      .createHash('sha256')
      .update(content)
      .digest('hex')
      .substring(0, 16);
    return `${pattern}:${flags}:${contentHash}`;
  }

  async matchRegex(rule: ContentRule, fileDiff: FileDiff): Promise {
    const changedContent = this.getChangedLines(fileDiff.patch).join('\n');
    const cacheKey = this.createCacheKey(rule.pattern!, rule.flags || '', changedContent);

    const cached = this.resultCache.get(cacheKey);
    if (cached !== undefined) {
      return { matched: cached, matchedPatterns: cached ? [rule.pattern!] : [] };
    }

    try {
      const matched = this.runRegexWithTimeout(
        rule.pattern!, 
        rule.flags, 
        changedContent, 
        5000
      );

      this.updateCache(cacheKey, matched);
      return { matched, matchedPatterns: matched ? [rule.pattern!] : [] };
    } catch (error) {
      return { matched: false, matchedPatterns: [] };
    }
  }

  private updateCache(key: string, value: boolean): void {
    if (this.resultCache.size >= this.MAX_CACHE_SIZE) {
      // LRU eviction
      const firstKey = this.resultCache.keys().next().value;
      if (firstKey) this.resultCache.delete(firstKey);
    }
    this.resultCache.set(key, value);
  }
}

Result: Zero ReDoS vulnerabilities in production. ✅

Technical Challenge #3: Handling Massive PRs

The Problem

Some PRs modify 3000+ files (dependency updates, refactors, migrations).

GitHub's API returns all changed files, but:

Loading 3000 file diffs into memory → OOM (Out of Memory)
Processing them serially → timeout
Posting a comment with all matches → exceeds GitHub's 65KB limit

Solution 1: Streaming Processing

Instead of loading all files at once:

async function* streamFileDiffs(
  token: string
): AsyncGenerator {
  const octokit = github.getOctokit(token);
  const { owner, repo, pull_number } = github.context;

  let page = 1;
  const MAX_PAGES = 30;

  while (page <= MAX_PAGES) {
    const { data } = await octokit.rest.pulls.listFiles({
      owner,
      repo,
      pull_number,
      per_page: 100,
      page,
    });

    if (data.length === 0) break;

    yield data.map((f) => ({
      filename: f.filename.replace(/\\/g, '/'),
      status: f.status as FileDiff['status'],
      additions: f.additions,
      deletions: f.deletions,
      changes: f.changes,
      patch: f.patch || '',
      previous_filename: f.previous_filename,
    }));

    if (data.length < 100) break;
    page++;
  }
}

// Usage
const matches: DecisionMatch[] = [];
for await (const batch of streamFileDiffs(token)) {
  const batchMatches = await matcher.findMatchesWithDiffs(batch);
  matches.push(...batchMatches);

  core.info(`Processed ${batch.length} files, found ${matches.length} matches so far`);
}

Memory usage:

Before: High memory usage for 3000 files → OOM risk
After: Constant memory (processes 100 files at a time) → No crashes ✅

Solution 2: Progressive Truncation

If the comment exceeds GitHub's limit, truncate intelligently:

function truncateComment(decisions: Decision[], maxLength = 65000): string {
  let comment = formatComment(decisions);

  if (comment.length <= maxLength) {
    return comment;
  }

  // Layer 1: Show 20 decisions in detail, summarize rest
  comment = formatComment(decisions, { detailLimit: 20 });
  if (comment.length <= maxLength) return comment;

  // Layer 2: Show 10 decisions in detail
  comment = formatComment(decisions, { detailLimit: 10 });
  if (comment.length <= maxLength) return comment;

  // Layer 3: Show 5 decisions in detail
  comment = formatComment(decisions, { detailLimit: 5 });
  if (comment.length <= maxLength) return comment;

  // Layer 4: Show 2 decisions in detail
  comment = formatComment(decisions, { detailLimit: 2 });
  if (comment.length <= maxLength) return comment;

  // Layer 5: Show counts only
  comment = formatCommentCounts(decisions);
  if (comment.length <= maxLength) return comment;

  // Layer 6: Hard truncate as last resort
  return hardTruncate(comment, maxLength);
}

Result: Never hit comment size limit, even with 1000+ matched decisions. ✅

Technical Challenge #4: Idempotent Comments

The Problem

GitHub Actions can run multiple times for a single PR:

New commit pushed
Workflow re-run
Manual trigger

Without proper handling:

3 runs = 3 duplicate comments
Spams the PR thread
Confuses reviewers

The Solution: Content Hash

async function upsertComment(
  prNumber: number,
  content: string
): Promise {
  const hash = crypto
    .createHash('sha256')
    .update(content)
    .digest('hex')
    .substring(0, 16);

  const marker = ``;
  const hashMarker = ``;
  const fullContent = `${marker}\n${hashMarker}\n\n${content}`;

  // Find existing comment
  const comments = await octokit.issues.listComments({
    owner,
    repo,
    issue_number: prNumber,
  });

  const existing = comments.data.find(c =>
    c.body?.includes('decision-guardian-v1')
  );

  if (existing) {
    const existingHash = existing.body?.match(/hash:([a-f0-9-]+)/)?.[1];

    if (existingHash === hash) {
      console.log('Comment unchanged, skipping update');
      return;
    }

    // Update existing comment
    await octokit.issues.updateComment({
      owner,
      repo,
      comment_id: existing.id,
      body: fullContent,
    });
  } else {
    // Create new comment
    await octokit.issues.createComment({
      owner,
      repo,
      issue_number: prNumber,
      body: fullContent,
    });
  }
}

Result:

✅ Single comment per PR

✅ Updates in-place when decisions change

✅ No spam, no duplicates

Architecture Overview

┌────────────────────────────────────────────────────┐
│                  DECISION GUARDIAN                 │
├────────────────────────────────────────────────────┤
│                                                    │
│  ┌──────────────────────────────────────────────┐  │
│  │         DECISION PARSER (AST-based)          │  │
│  │  - Markdown parsing with remark              │  │
│  │  - JSON rule extraction & validation         │  │
│  └──────────────────────────────────────────────┘  │
│                      ↓                             │
│  ┌──────────────────────────────────────────────┐  │
│  │      DECISION INDEX (Prefix Trie)            │  │
│  │  - O(log n) file lookup                      │  │
│  │  - Wildcard pattern optimization             │  │
│  └──────────────────────────────────────────────┘  │
│                      ↓                             │
│  ┌──────────────────────────────────────────────┐  │
│  │         FILE MATCHER (Rule Evaluator)        │  │
│  │  - Glob pattern matching                     │  │
│  │  - Content diff analysis                     │  │
│  │  - ReDoS protection                          │  │
│  └──────────────────────────────────────────────┘  │
│                      ↓                             │
│  ┌──────────────────────────────────────────────┐  │
│  │      COMMENT MANAGER (Idempotent)            │  │
│  │  - Hash-based update detection               │  │
│  │  - Progressive truncation                    │  │
│  │  - Retry with exponential backoff            │  │
│  └──────────────────────────────────────────────┘  │
│                                                    │
└────────────────────────────────────────────────────┘

High-level flow:

PR Created → Parse Decisions → Match Files → Post Comment → Check Status

Key components:

Parser (parser.ts): Markdown → structured data
Matcher (matcher.ts): Trie-based file matching
Rule Evaluator (rule-evaluator.ts): Advanced rules
Comment Manager (comment.ts): Idempotent PR comments

Lessons Learned

1. Performance matters from day 1

I could have shipped with the O(N×M) algorithm and optimized later.

But teams with large PRs would have hit timeouts immediately and never come back.

Lesson: Build for scale early, especially in tools that run on every PR.

2. Security is not optional

The ReDoS vulnerability wasn't theoretical - during testing, a user accidentally created a pattern that froze the action for 5 minutes.

Lesson: Validate all user input, especially anything that can loop or recurse.

3. Idempotency prevents pain

Early versions created duplicate comments. Users reported it as "spammy" and disabled the action.

Adding content hashing fixed this and improved adoption.

Lesson: Make actions side-effect-free and repeatable.

4. Documentation > features

I spent 60% of development time on README, examples, and error messages.

Users still ask "how do I use this?" constantly.

Lesson: You can never document enough.

Try It Yourself

Install:

- uses: DecispherHQ/decision-guardian@v1
  with:
    token: ${{ secrets.GITHUB_TOKEN }}

Example decision:


## Decision: Database Choice

**Status**: Active  
**Date**: 2024-03-15  
**Files**: `src/db/**`

### Context
We chose Postgres for ACID compliance.
Rejected: MongoDB (no ACID), Redis (complexity)

Links:

GitHub: https://github.com/DecispherHQ/decision-guardian
Docs: https://decision-guardian.decispher.com
Marketplace: https://github.com/marketplace/actions/decision-guardian

What's Next?

Short-term:

GitLab/Bitbucket support (if demand exists)
Decision templates

Long-term:

VS Code extension (show decisions inline)
Analytics dashboard
Cross-repository rules

Want to contribute? Open an issue or start a discussion.

Conclusion

Decision Guardian is free, open source (MIT), and takes 2 minutes to set up.

What architectural decisions does your team repeatedly debate?

Drop a comment - I'd love to hear your stories.

Made with ❤️ by Ali Abbas