Gate AI Drafts of Design Decision Records Before You Merge

Auto-drafting a decision record from an AI chat or a pull-request diff is useful. Before you begin, decide three things: what counts as a record, who will review the draft, and where the process must stop before a commit or merge.

📑Table of Contents

1. Compare recording methods before you automate
2. Record the why of a design decision, not the finished screen
3. AI drafts fail on the context window and missing reasons
4. Stop missing records at commit or merge, not as homework
5. Go / no-go checklist
6. FAQ
7. Summary

The cost of writing lands on the person who records it now. The benefit lands on later maintainers. The EASE 2026 paper (arXiv 2604.03826) cites earlier work that about half of repositories that start ADRs abandon the practice before five records. Manual cleanup alone tends to stall.

Eligibility, reviewer, and gate

Do not treat discovery popularity as an adoption reason. Proceed only if you can name the eligibility rule, the reviewer, and the gate.

---

Compare recording methods before you automate

Pick the method by input and by the human stop point. A description of the finished screen is not the same artifact as a record of what was accepted and rejected.

Official ADR, in-flow draft, and transcript extraction

Method	Input	Human stop	Published limit
Official ADR (Nygard / MADR)	One human-written decision	Review before accept; superseded, not deleted	One to two pages. No cross-industry DDR standard
In-flow AI draft + hook	Chat context + git diff	Confirm draft, then save under docs/ddr/. Typos without meaning change are out of scope	Origin team workflow. Public reproduction is limited
Transcript extraction (GADR)	Raw meeting text	Human-in-the-loop validation is required	The paper argues one-shot prompts degrade

---

Chat-log extract and PR gate

Method	Input	Human stop	Published limit
Mechanical chat-log extract	Agent utterances and edit diffs	Ask the author one line when the reason is missing	191 of 1,157 utterances (16.5%). Reasons in about 30% of corrections
PR gate (gh-aw)	PR body / docs/adr/ / diff	If a decision cannot be inferred, comment and stop; do not draft	Default: implementation label, or more than 100 added business-dir lines

---

Sources

Sources:

• Nygard 2011
• adr.github.io
• GADR (arXiv 2608.17694)
• Qiita / Nagata
• gh-aw Design Decision Gate (as of August 2026)

“Auto-record” is not one product. If you mix drafting and leak detection, a plausible reason can land in the repo before anyone checks it.

---

Record the why of a design decision, not the finished screen

Keep the rejected options and the accepted consequences. Do not keep a caption of the final UI.

Nygard’s sections

Michael Nygard’s 2011 post says that without rationale later readers can only accept blindly or reverse blindly. The recommended sections are Title, Context, Decision, Status, and Consequences. Store files such as doc/arch/adr-NNN.md in the repo. Do not reuse numbers. Mark overturned records superseded instead of deleting them.

---

MADR path

adr.github.io defines an ADR as one justified decision. The collection is a decision log. The same shape can cover any decision record, including design. MADR 4.0.0 initializes docs/decisions.

npm install madr && mkdir -p docs/decisions && cp node_modules/madr/template/* docs/decisions/

---

ADR, PDR, and DDR

glukhov.org treats ADR (technical), PDR (product), and DDR (UX / interaction) as the memory layer for AI-assisted work. Code stores what shipped. It does not store why. DDR is not an industry-wide Open Standard. Teams copy the ADR idea and name their own fields.

---

Origin field list

The origin SoftBank Zenn write-up lists record ID, change type (wording / meaning / criterion / approved rule exception), background, decision, alternatives, impact, and a verification plan. One example ID is DDR-001_delete-confirmation-dialog (2026-08-07). That is a primary workflow description, not a standard.

Fix the path (docs/adr/, docs/ddr/, or docs/decisions/) and four required sections on one template. Mixed locations become unsearchable.

---

AI drafts fail on the context window and missing reasons

The binding constraint is not model size. It is which prior records you pass, and whether the log still contains a reason.

Recency window

The EASE 2026 study compared no-context, all-history, First-K, Last-K, and RAFG on a 750-repository sequential ADR corpus. A recency window of the last 3–5 records was the best quality/cost balance. RAFG did not add a statistically significant gain on linear workflows. Some tasks generate a body from the next ADR title. That is not the same as your chat-log quality.

---

Transcript extraction

GADR (arXiv 2608.17694) extracts Nygard-form drafts from raw meeting transcripts with a multi-agent self-correcting workflow. Humans must validate the output. The claim is to capture knowledge when it is created, not reconstruct it later. The authors argue one-shot prompts degrade.

---

Chat-log yield

Nagata’s Qiita measurement found 191 complete four-tuples (input, intervention, output diff, reason) in 1,157 user utterances across three projects (16.5%). About 30% of 612 correction signals still had a reason. One writing example moved 0/8 to 5/8 (+62 points). Six other examples moved +0. What helped was a numeric criterion already in the log, not an abstract rubric. The author says not to generalize from one person and a writing-heavy sample.

Pass the last 3–5 accepted records into the draft prompt. If the reason field is empty, mark TODO and ask the author one line. Do not accept a fluent invented rationale.

---

Stop missing records at commit or merge, not as homework

Separate draft from leak detection

Separate draft generation from leak detection. The mechanical stop belongs immediately before commit or merge. That split matches harness design that separates instruction, guard, and verification.

---

Eligibility and save path

1. Write eligibility on one page. In scope: meaning changes to rules, criteria, or execution flow. Out of scope: typos and formatting.
2. Put “chat + diff → template draft” in the agent instructions. For chats outside Git, request a formatted draft at the end of the thread and attach a share URL.
3. Pin the save path to docs/adr/ or docs/ddr/.

---

Choose one gate

4. Choose one gate. A pre-commit hook stops if a staged meaning change has no new record. The gh-aw Design Decision Gate fires on an implementation label, or more than 100 added lines under src|lib|pkg|internal|app|core|domain|services|api. Required sections: Context, Decision, Alternatives Considered, Consequences. If those are missing, it can push a draft from the diff. If a decision is not inferable, it comments and stops. Turn budget 20; one safe output.

---

Same-PR record and why-only questions

5. Rick Pollick argues the same PR that introduces a pattern must include the record. After-the-fact ratification is a failure mode. If you cannot write the record, the change is not ready to ship.
6. ADR AI Manager for VS Code classifies selected commits, asks only the why that is not in the code, and writes MADR under docs/adr/. Unknowns stay TODO. It supports Claude, OpenAI, and local Ollama, LM Studio, or vLLM.

---

Start point

The origin hook’s inspection logic is only thinly published. gh-aw is public, but missing labels will cause over-firing or under-firing.

A solo repo can start with an end-of-chat template. A shared branch should put the PR gate first. Treating a completion claim as different from a real state change is the same discipline as separating test edits from verification.

---

Go / no-go checklist

Decide from eligibility

Decide from eligibility and review load, not from the phrase “automatic recording.” Packaging the procedure and defining pass criteria is the same move as growing an internal agent with Skills and evals.

---

Checklist

• ✓ The decision is technical (ADR), product (PDR), or UI (DDR). Do not mix the files.
• ✓ Out-of-scope items (typos, formatting, trivial refactors) fit in one line.
• ✓ Humans review the actual decision, alternatives, and consequences. They do not accept a plausible AI reason.
• ✓ The gate is pre-commit, PR, or manual. Ungated auto-save is out.
• ✓ The last 3–5 records can be passed as context. If not, a human writes three first.
• ✓ You can ban “write a nice ADR” one-shots.

---

What RAKUS changed, and when to skip

RAKUS split the work into premise, plan, options, independent review, consensus, then draft, with an eligibility gate first. The first pass took about 60 minutes, about 20 boundary checks, and three review rounds, and stalled. They cut idle time with conditional auto-advance, stop-only-on-blocker, and a two-review cap. Standing agent teams bloated context. On one session, a subagent plan cut session time to about one third.

Skip the project if eligibility is fuzzy every time, nobody reviews the drafts, logs almost never include reasons, or you cannot install a gate.

This week the focus is one template and one eligibility question. Generation comes after that.

---

FAQ

Are DDR and ADR different standards?

No. adr.github.io says the same record type can cover design decisions. DDR is a name for UX and interaction choices. Teams choose the fields.

---

Should we archive the entire chat?

No. In the Qiita measurement, the four-tuple held for 16.5% of utterances. Most corrections had no reason. Only records that keep the criterion and the rejected option become assets.

---

How many prior records should the prompt see?

The published default is 3–5. Full history raises cost. On linear workflows, RAFG did not add a significant gain.

---

Can a design chat without Git start?

Yes. Hand the template at the end of the thread, attach a share URL, and have a human save the file. Add a hook or PR gate later for leak detection.

---

May we accept the model’s written reason as-is?

No. glukhov.org and GADR require human validation. Unknowns stay TODO. ADR AI Manager is designed not to invent rationale.

---

Is bookmark count a reason to adopt?

No. It is a discovery signal. Adopt only if eligibility, a reviewer, and a gate exist.

---

Related articles:

• 13572
• 13574

Summary

If you want design decisions as assets, do not start with automatic recording. Stop the draft for a human check, then stop leaks before commit or merge.

Next actions:

1. Put one four-section template in the repo
2. Put one eligibility question at the front
3. Pass the last 3–5 accepted records as context
4. Choose either a pre-commit hook or a PR gate
5. Do not auto-save without a gate

Uncertainty remains around the unpublished origin hook, the gap between paper corpora and your logs, and the Qiita sample size. Popularity is not an adoption reason.