Build an AI Architecture Decision Gate for GitHub Pull Requests

Code explains changes, but it doesn't often explain why.

A developer might introduce a cache, switch databases, or change a service boundary. The implementation lands, but the reasoning behind it exists only in a pull-request discussion, or nowhere at all. Months later, someone else has to reconstruct the decision from the code.

Architecture Decision Records (ADRs) solve this by documenting a decision's context, alternatives, and consequences. The trouble is it's tempting to postpone writing them.

On October 15, 2026, GitHub Agentic Workflows highlighted a Design Decision Gate that inspects pull requests, checks for existing ADRs, and drafts one when needed. Let's build a smaller version using GitHub Agentic Workflows, GitHub's framework for repository automation powered by AI agents.

1. Set up GitHub Agentic Workflows

You'll need a GitHub repository with Actions enabled, the GitHub CLI, and access to a supported AI engine. This example uses GitHub Copilot; other engines require their corresponding authentication setup.

Install the Agentic Workflows extension and authenticate your GitHub CLI account:

gh auth login --scopes repo,workflow
gh extension install github/gh-aw

GitHub Agentic Workflows are in public preview, so syntax and capabilities may change. Check the current quickstart before following the setup process.

Create a repository label named implementation. We'll use it to decide which pull requests require analysis, instead of spending tokens on every documentation touch-up.

2. Define the workflow

Create a workflow source file in the repository's GitHub workflows directory, for example .github/workflows/adr-gate.md:

---
description: "Propose ADRs for significant pull requests"
on:
  pull_request:
    types: [labeled, ready_for_review]
    names: ["implementation"]
permissions:
  contents: read
  pull-requests: read
  copilot-requests: write
engine: copilot
tools:
  github:
    mode: gh-proxy
    toolsets: [default, repos]
safe-outputs:
  add-comment:
    max: 1
  push-to-pull-request-branch:
    allowed-files:
      - docs/adr/**
  noop:
timeout-minutes: 15
---

Its configuration specifies the pull-request events to monitor, the AI engine, the permissions required, and the permitted write actions. The crucial safety setting is a restriction on generated changes: even when the agent is authorized to propose a change, its branch-write operation is limited to the ADR directory. The agent job itself has read-only repository permissions; configured safe outputs handle permitted writes separately.

For personal repositories, Copilot authentication may require a COPILOT_GITHUB_TOKEN secret. Follow the authentication guide for your chosen engine.

3. Give the agent a narrow job

The agent's instructions should define a single responsibility: determine whether a pull request introduces a significant architectural decision that needs documenting.

It should read the pull-request description, inspect changed files, and search existing ADRs for a record covering the decision. If the change is routine, it should explain why no ADR is necessary. If an existing ADR already covers the change, it should report whether the implementation aligns with that decision.

When a significant decision lacks documentation, the agent should draft an ADR with four sections: context, decision, alternatives considered, and consequences.

Every claim must be grounded in the pull request or existing repository evidence. If the rationale or alternatives cannot be inferred, the agent should explicitly say so instead of inventing the author's reasoning.

The workflow should propose the draft in the designated ADR directory and leave a concise pull-request comment explaining what requires review.

Append the following instructions beneath the closing ---:

# Architecture Decision Gate

Inspect the triggering pull request and determine whether it
introduces a significant architectural decision.

## Procedure

1. Read the pull-request description, changed files, and diff.
2. Search `docs/adr/` for an existing decision that covers the change.
3. If the change is routine or no architectural decision is evident,
   use `noop` and briefly explain why.
4. If an existing ADR covers the change, compare its decision with
   the implementation and report alignment or specific divergences.
5. If a significant decision lacks an ADR, draft one using:
   - Context
   - Decision
   - Alternatives Considered
   - Consequences

Base every claim on the pull request or existing repository evidence.
Write "Not inferable from current PR evidence" where information
is missing. Never invent the author's rationale or alternatives.

If a draft is justified, write it under `docs/adr/` using a
filename based on the pull-request number and a short title.
Use the configured branch-write safe output to propose the draft,
then use the comment safe output to explain what requires review.

Keep the comment concise and provide one clear next action.
If nothing requires action, use `noop`.

This is deliberately smaller than GitHub's own example, which includes additional handling for labels, linked issues, large diffs, configurable directories, and reporting templates. Consult the original workflow when you need those features.

4. Compile and review it

Compile and validate the workflow using the Agentic Workflows CLI:

gh aw compile
gh aw validate

Review the generated .github/workflows/adr-gate.lock.yml alongside the Markdown source, then commit both files to the repository:

git add .github/workflows/adr-gate.md \
  .github/workflows/adr-gate.lock.yml
git commit -m "Add AI architecture decision workflow"
git push

Do not treat successful compilation as proof that the agent behaves correctly. Compilation checks the workflow definition; runtime behavior still needs testing.

5. Test two contrasting pull requests

Use a test repository before enabling this workflow on a production codebase.

Test A: routine change. Open a pull request that only corrects a typo. Add the implementation label to trigger analysis. The agent should explain why no ADR is needed and take no further action.

Test B: architectural change. Open a pull request that introduces a new database or changes a service boundary, without documenting the rationale. The agent should either draft an ADR grounded in the available evidence or identify what information is missing.

Inspect the Actions logs, comments, and any generated file. Confirm that writes stay within the designated ADR directory and that unsupported or ambiguous cases are handled safely. Do not claim success until both scenarios have actually run.

6. Treat it as a reviewer, not an architect

An ADR generated from a diff is still a hypothesis about the author's intent. A patch can show that a database changed; it usually cannot explain every alternative the team considered or every operational constraint.

The workflow should therefore create a starting point for review, not silently turn plausible guesses into institutional knowledge. Pull-request diffs are untrusted input, too: keep permissions minimal and inspect the generated workflow before enabling it.

This prototype comments on decisions and proposes documentation. It does not guarantee that a pull request cannot merge without an ADR. To enforce that policy, add and test an explicit required-check or branch-protection mechanism; a comment alone is not a merge gate.

The payoff is simple: significant design decisions get documented while their context is fresh, without asking engineers to start every ADR from a blank page. The agent handles the first draft. The humans remain responsible for the decision.