The Real Reason AI Ignores Existing Decisions - Designing an ADR Context Auto-Injection Hook

TL;DR

In May 2026, I reworked a Claude Code plugin to share a workflow across development projects. One challenge was ensuring past design decisions (ADRs) carried forward into subsequent sessions. I built a script that indexes accepted/amended ADRs and injects a concise list into the context via a Claude Code hook. The initial version ran on every turn (UserPromptSubmit), then was optimized to fire only at session start (SessionStart). Subsequent improvements focused on performance-reducing latency from 3,842ms to 94.7ms-and refining the indexing logic to keep only key metadata (number, title, status). While this ensures the existence of decisions reaches the model, it does not guarantee the AI will interpret or act on those decisions.

---

Problem Statement

When a new AI session begins, prior design decisions stored in documents (e.g., Architecture Decision Records, or ADRs) are not automatically available to the model. Even though a repository might contain 100 documents, unless they appear in the context as something to read, they remain undiscovered to the model. The original design record of the project in question had 27 of 29 files in scope, and all 27 were shown-but this relied on manual effort rather than an automated pipeline.

This creates a practical gap: the model receives no signal that certain decisions exist, leading to repeated reinvention of choices across sessions. The goal was to create a mechanism that makes these decisions discoverable and actionable at the start of each session.

---

Solution Overview

The plugin set aims to make workflows-spec authoring, review, testing, deployment verification, and similar processes-reusable across multiple development projects. Rather than requiring users to paste explanations repeatedly, design decisions should be registered as Claude Code skills and hooks and executed when appropriate.

ADRs present a parallel problem: while they can be searched later, a new AI session does not inherently inherit the previous conversation. The solution splits the problem into three distinct stages:

1. Deliver existence - Put a list of currently effective design decisions into the context.
2. Read the relevant documents - Select the ADR bodies related to the current work.
3. Reflect them in the implementation - Turn decisions and constraints into diffs and tests.

The hook described below handles only Stage 1. Claiming it guarantees stages 2 and 3 would overstate the implementation's reach.

---

Implementation Details

Index Construction

The script operates on the working project's docs/adr/ directory. Its processing pipeline is:

1. Determine the working project - Identify the correct project context.
2. Gather ADR files - Directly under docs/adr/.
3. Read each file's heading and Status - Extract metadata from each document.
4. Filter - Keep only documents marked Accepted or Amended.
5. Emit a limited list - Include the entry number, title, and status for up to 30 entries.
6. Inject into context - Return the list via the additionalContext hook parameter.

The first version emitted approximately 500 tokens for 20 entries and about 750 tokens at the 30-entry cap. The index contains only "what has been decided"; the detailed reasoning resides in the ADR bodies themselves.

Hook Registration

The initial version targeted UserPromptSubmit, injecting the same index on every prompt. In July 2026, this was changed to SessionStart (firing at session start and resume), and the plugin version advanced from 0.4.0 to 0.21.0.

---

Evolution of the Implementation

Date	Change	Impact
May 2026	Per-turn injection on UserPromptSubmit	List arrives near new instructions, but consumes ~750 tokens per turn (30 entries × ~25 tokens each).
July 2026	Moved to SessionStart (start, resume, compact)	Reduces redundant transmission; list stays within the session context.
August 2026	Consolidation: read 121 files through a single awk run	Median latency drops from 3,842ms to 94.7ms (minimum 71.4ms). Token usage remains bounded (~750 for 30 entries).
September 2026	Changed to insert only a short pointer on compact/resume instead of the full index	Further reduces overhead for large projects where new ADRs are added mid-session.

The awk-based consolidation was critical. Before, the first version used grep and sed multiple times per ADR, creating ~1,100 processes for a single start when 121 files were present. The new approach runs everything in one pass, dramatically improving throughput.

---

What Can Be Guaranteed (and What Cannot)

It is important to clarify the boundaries of the hook's behavior:

• What IS deterministic: The hook firing, the generation of the index string, the application of filters (only Accepted or Amended), and the capping at 30 entries. These elements are fully controlled by the script and are independent of the model's judgments.

• What is NOT deterministic: Whether the model selects the relevant ADRs, reads their bodies, or correctly applies the decisions to the current work. Those steps depend entirely on the model's interpretation and reasoning capabilities.

The phrase "a system that guarantees the AI follows existing decisions" is therefore inaccurate. The system guarantees that the existence of decisions is communicated to the model; it does not guarantee that the model will honor them.

---

Measuring Success

Since the hook only controls the first stage, success should be measured against three indicators:

1. Hook fire rate - Proportion of target sessions where the hook executes.
2. Relevant ADR body read rate - Proportion of sessions where the injected list includes ADRs actually relevant to the current task.
3. Violation rate - How often the model proposes actions that contradict existing decisions (this metric was not tracked in the current implementation).

These metrics provide a clearer picture than simply reporting a percentage drop in violations, since the underlying cause may vary across projects.

---

Summary

The core insight is that delivering existence is distinct from enforcing adherence. By constructing a lightweight index of accepted/amended ADRs and injecting it into the Claude Code context at session start, we ensure the model knows what decisions are active. However, meaningful adoption requires that the model subsequently select, read, and act upon those decisions-which remains outside the scope of this hook. Future iterations could explore integrating the index with the second and third stages (document retrieval and decision reflection), but such extensions would require additional modeling and validation beyond the current implementation.