DEV Community: Ali Abbas

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