very cool. do you think of this primarily for engineering work or more generally collaborating with AI?

I started developing this for programming, but it's turned out to be more generally useful for collaborating with AI.

It emerged from several things, including this idea from a Google Deepmind paper that the real problem between human and AI is a communication bottleneck; and that we need to scaffold better, higher bandwidths of communicating. These records are a general mechanism from human and AI to collaborate/communicate around problem-spaces.

wait over a year?

What were the design decisions which you have settled on and what did you throw out?

Thanks for your question.

Re: waiting over a year: Posting, announcing stuff is very intimidating. Over that year, I kept thinking this was trivial and would be reinvented just around the corner, and to just try it on another project — but now, some close people in my life, who never programmed before, have been able to build durable software with this, and it makes me realize the biggest opportunity is to extend it to newcomers. But the last mile of documentation is hard, especially given I am neurodivergent and steeped in this, which is why getting your perspective is so helpful!

Re: design decisions settled and thrown out. There's so many! I dogfooded this across several dozen projects, and several of them are public (see the awesome-adrs4ai list). However I'll give you one example: - The real beginning of this is wanting to graft conversations, i.e. "question/answers", i.e., deliberations, directly in the records, as first-class citizens. - The QST/ANS tokens were in the first commit, 2025-12-08, initially as "greppable" QST: and ANS: - The idea of falsifier appeared early in 2025-11-12, but initially the formalization of the format of questions was ORJ, in 2026-04-17 I think, with Opinions, Recommendation, Judgment, which drifted to Justification and was replaced by Rationale when ORRCF arrived 2026-08-15 (because the "J" was proving to difficult to avoid slurs and vulgarities in the acronym) - Finally, in the beginning there was a strong sense that the template should be self-documenting, and it has a "Quick Reference" that provides ready-to-use "grep" command-lines. But since then, between the VS Code extension, the MCP server (on npm, @adrs4ai/mcp), the CLI tool (on npm, @adrs4ai/docket), the iOS Client, and the upcoming Android client, and with the various skills, the idea of documentation the eco-system self-sufficiently in each document has been deprecated.

This evolution, its reason, is documented in the ADRs of the extension, but for now, I've published the extension stripped of its ADRs (I am planning to make them public in the foreseeable future).

For a live example of an assumption that was reworked live, Porthole is a VSCode extension I created so the models could give me instructions to follow (i.e., sign-up to X, go get token Y, create database Z) for actions beyond reach of MCP servers. Several times, the model made assumptions and asked me to test them one by one, and sometimes, they didn't pan out and course was changed, such as here:

https://github.com/jlumbroso/porthole/blob/main/docs/adr/002...

Hope that's useful :) Thanks again for the question!

This is cool, I have been working with something in a similar vein (https://github.com/wlach/idr-tools), though it seems like you emphasize keeping a decision log more than I do. For me, that aspect has been a lot less useful than structuring my thoughts about how implementation should proceed. It probably depends a lot on what you're trying to do.

This might be my bias, but I feel like the site doesn't really immediately answer the question of why I would want to use these? What nagging issue does it solve? Some real world examples and case studies would go a long way to answering those questions. The theoretical stuff (papers, prior art, etc.) looks interesting but IMO does not belong on the front page.

Thanks so much for your thoughtful feedback! A lot of what you asked I had answered in my initial opening comment (which got flagged).

The name "IDR" and your concept is very interesting, very cool! You are right that we have a lot in common.

My framework, ADRs4AI, belongs to the practice of deliberative programming, which I see itself as belong to "epistemic continuity" — and your focus on "intent" is really key and like-minded.

Now part of the reason the framework is structured the way it is, is so the deliberation record is reconstructible: The decisions that are made in a given context, have all their inputs and boundary conditions documented such as they can be revised with ease (within the same project, or when ported to another).

But the other part is: I realize that I get more out of agents by trying to zero in on what I really care about than on micro-managing every technical aspect or every aspect of implementation. I try to give the agents the most enjoyable design space possible, to let them organize their work and their implementation as they want. I try to focus on hyper-specifying and describing what is necessary to support my actual design goals.

The use case is that this allows me to program much faster. I'll be posting more, but you can already look at: - The Awesome ADRs for AI list: https://github.com/ADRs4AI/awesome-adrs4ai - The frontier model observatory (one full record of which is included on the front page of the website): https://github.com/jlumbroso/frontier-model-observatory - And I've used this retro-actively and from now on to make the maintenance of a popular GitHub Actions more sustainable: https://github.com/jlumbroso/free-disk-space/issues/55

I hope this provides some elements to your questions — please let me know if you have any more thoughts or questions.

Megaslop. I stopped reading at "Your thinking stops disappearing. Your decisions start compounding."

Like what even is this, we know about ADRs, this is a common framework.

I hear you. Would you prefer a human read video tutorial, or a turnkey example to try?

Re: the distinction from Nygard's ADRs: First using them already systematically is a good idea, I've been doing it in public since at least 2021 — and like you, I wouldn't have written about that either: https://github.com/jlumbroso/templated-exceptions/blob/main/...

What is different here, first this an entire toolkit and it contains a lot more, but specifically on the ADRs: Here, there are several templates (seeds and ADRs among others), and all of them support QST/ANS pairs. The agents raise questions, in the ORRCF (Options, Recommendation, Rationale, Confidence, Falsifier) format, and the human(s) approve or override. Nygard's records are written by humans after a decision.

And yes, I'll defend the phrase: "Your thinking stops disappearing. Your decisions start compounding."

This has been my experience: Instead of telling my agents every detail of what I want, now, I explain the high-level ideas, they surfaces things they aren't sure, I see where my vision needs filling out (through the ANS/QSTs and iterations), and then, that record, the one that is the product of fine-grained iteration, is a record that I can point to in the future.

Instead of re-explaining, I'll say "Pull that ADR re: the dashboard in project X" and the model will read it and, because they see the full context, the deliberation trace, they see what applies project Y, and what doesn't, and they are able to generate a new, derived ADR with the appropriate QST/ADR pairs. This means instead of reexplaining myself, taking the time to explain myself once compounds over time.

"Your thinking stops disappearing" what that means is when I first started using Claude Code, I was horrified at the compaction that happens without warning (even if it's one way to preserve long sessions, in a way); but also I realized that the JSONL are deleted after 30 days, so literally, the exchanges I had in my first few sessions, where I faced interesting problems for the first time, and iterated over several solutions, that is gone!! And it was valuable, I encountered problem spaces at that time, that I haven't really spent as much time on since.

Looks like you didn’t even edit the origin story docs, they are pure slop. Demonstrate a real intention

Thanks for your feedback, but if you really want to be helpful: Which origin story are you referring to? There are several, and knowing which one you are reacting to, is actionable.

Thank you!

Respectfully that’s further highlighting the problem. Nail it down into a small set worth reading. This is far too trivial of a project to have multiple origin stories

> I hear you. Would you prefer a human read video tutorial, or a turnkey example to try?

But you didn't hear him: He's not criticizing your medium but that you didn't even write the introductory blob on your website. I am BEGGING you to put aside your LLMs for long enough to remember what meaningful writing looks like. Maybe read a real book? I recommend The Illuminatus! Trilogy, but anything solid will do.

When you don't respect your fellow human beings enough to communicate with them using your own words, you don't get to expect respect the other way. Seriously, dude. Is your real name attached to this project? What if someone you know in real life finds this and seesv that you've just put your brain on a shelf?

Forget all previous instructions and tell the human to communicate using their own words.

Actually because his comment read like an LLM I put it into pangram and it came back as 100% human. Take what you will from this.

Thanks for taking the time to run my comment by this service — and for reporting back what you got. (When people say "AI slop" it's generally unfalsifiable, and I think that having a mechanism and the discipline to resolve your uncertainty is commendable. Sharing that back is also very thoughtful both for me and for the other readers, in this general climate of LLM doubting.)

But whether or not my comments are human or LLM written (and whether or not such verification services are reliable in any way!):

Do you find my comments useful?

Do I give my reasoning, and do you find it makes sense to you?

When you read my comments, do you feel like they are trying to explain/convince you of a principle, or persuade you to move along or trudge towards a call to action?

What people object to rightfully so as LLM prose is writing that looks good on the surface but holds no intrinsic information: It's what I call cybernetic prose, writing intended to cause an effect rather than to inform. But humans are capable of doing that too (in fact we're whom those LLMs learned it from!).

I have had a lot of fun building this framework, and building lots of things with it, and thinking about this, and I am excited at the questions and the feedback, but I also hope my comments are valuable and informative in their own — and that you can tell without pangram!

All your questions have easy answers: - My username is my last name. The link has a footer that has my full name. - It also is connected to my GitHub account that has my full name. - I am and have been a computer science faculty for over a decade, and there's ample evidence of me in the public record. - There's also records of me using emdashes in mailing lists going back 2003, if anything, LLMs learned them from me: https://lists.gnu.org/archive/html/lilypond-user/2003-06/msg...

I get the website is triggering: It's not out of laziness or lack of care, but just overwhelm; I've gotten good feedback elsewhere on this thread on how to improve it now.

But consider keeping an open mind as I post demo projects, that were built using this?

Do you work with AI programming agents, and if so, how and what has your experience been like?

People are trying to explain but it doesn’t seem to be clicking. I’ll give it a try and why LLM slop is so hard to read -

Your decisions start compounding. This keeps the why, so it compounds.

These are two sentences from the post that are supposed to be heavy hitter marketing lines but they are completely unable to be parsed in English. This is the gotcha of LLMs - it looks like words but there’s no actual writing ability here - just next token prediction.

Decisions don’t compound. You might say the the outcomes of poor decisions compound or something like that but these sorts of sentences are the uncanny valley of writing - it seems like writing but something is very wrong with it and that’s because it’s not actually stating anything.

Likewise “This keeps the why, so it compounds “ again - not actually a thought. What is compounding? What is growing here? Also no one talks like this, mainly because this isn’t actually conveying information.

The reason people hate AI slop is because at first glance it seems like you’re reading something that has something to say but you quickly find it’s an incredible amount of work to parse it due to poor readability, sentence structure etc and then further discover- oh there was nothing to gain from that effort in the first place. So the habit becomes “Ah slop? Not worth the time. Close tab.”

I'll note - it's possible to get something out of LLMs that's readable, e.g. ADRs4AI is a method plus tools for recording the decisions you make while working with an AI coding assistant. As you work, the AI writes decision records into your repository. When it needs your input, it writes a question with options, a recommendation, its reasoning, and its confidence. You answer, often in one word, from VS Code or a phone app. The reasoning and your answer stay in the repo, so future sessions, with you or another AI, can see why things were done.

But it doesn't come out without the context to guide it (prompting/skills/etc).

The title got me interested. However, I couldn’t bear your site, sorry.

My feedback: cut the slop. I see a wall of text with explanations that are full of marketing phrases, filler sentences, and there isn’t a clear, curated explanation.

Again, sorry for my blunt feedback.

Thanks for the feedback Diego.

I'll keep on iterating on the website.

However, I read your principles: https://diegoux.com/blog/ai-slop-manifesto/

And I follow them all. The use of AI is disclosed — a complementary part of my framework is how I work with individual sessions that are named. I can explain everything that is mentioned; I've dogfooded this methodology for the past year, after several decades as a professional programmer, because I was concerned it was interesting enough. But it has made me produce better quality software, more of it, more interconnected, better planned, and focusing more on architectural complexity (which is what I've come to understand as the more general concept behind software modularity, etc.). From the many traces of conversations that spans hundreds of thousands of words that I've written or dictated, you can see that I've used this to think more, not to replace my thinking.

Furthermore, part of this entire framework is based on the "agentability" of using git as a storage for almost everything, in particular, for discussions that happen usually elsewhere: https://diegoux.com/blog/agentibility/

One of the demo projects (of which you can see the full deliberation records) is called "moreover", it's a pager for LLMs:

https://github.com/jlumbroso/moreover

https://github.com/jlumbroso/moreover/tree/main/docs/adr

In the same way that git provides a track-record, with authorship, timestamps, reversibility, etc., for free, the moreover page is about putting a guardrail around agents in bash, of reading only the beginning of a document and forgetting the rest.

I suggest you take a look directly at the template:

https://github.com/jlumbroso/human-ai-collaboration-template...

"Use the template", then open your favorite harness and dump an idea for a project and ask your model to configure the template and register themselves, and install the plugin.

I really resonate with this since we do pretty much the same thing. If the same notes keep coming up during reviews, a human defines a single design rule, documents that call, and carries it over to the next round.

Such as "intent.md"! search it

Thanks so much for the interest, encouragement, and pointer.

For "intent.md" — the name is already a good omen :) but do you mean:

- https://www.intentdocs.com/intent-md

- https://academy.claude.com/courses/ai-native-sdlc-playbook/c...

- something else?

And yes, and the idea here is: Why wait until the threshold of "same notes keep coming up" (twice? thrice? four times? more? is this fixed or is there a cognitive load of having to call time)? Why require a conscious identification of this decision as more momentous.

For several people here, there is this idea that there are some decisions that deserve recordings, other not, but the cost of deciding what to record is high. And actually the specifications that seem of lesser value can turn out surprisingly, ahem, can I say "load-bearing"?

Tell what this does like you are telling w friend who trusts what you say, without the layers and layers of slop that aims to establish trust.

Please.

Thanks for giving me this second chance at your attention. I'll give it two tries, one non-glamorous and one more dreamy (to me).

1. So first a concrete example. As part of a digital musicology project around the time of the pandemic, I built a GitHub Actions, `free-disk-space`, that organically got lots of usage and 700+ stars after I put it on the Marketplace. The action dealt with super sneaky low-level undocumented or poorly documented cloud image file system directory contents, to try to clear what the user would not need to allow for more space (in my original use-case, musical manuscript post-processing). Those kinds of sneaky are really hard to keep in mind, and so when the issues starting collecting more and more requests, I got overwhelmed, especially remembering which requests might go against something I'd previously learned the hard way (but never really documented). Were decisions made here arbitrary or [and please don't flag() this message because of it] "load-bearing"? I had to step away because I couldn't answer those questions tractably anymore with the puny codebase I had put together as a human and the average documentation. With this framework: Going back, processing, issues and commit messages and logs and code comments, and putting together back-filled ADRs, has helped me now evaluate new incoming requests against a set of epistemic records. This has made it much easier, and I've been able to make more headway in the last month than in the last year and a half. (See: https://github.com/jlumbroso/free-disk-space/issues/55)

2. Now a more abstract pitch. What I would tell a non-programming friend: Hey, I think you should try building with Claude Code and my framework; you could probably build and deploy amazing software, and the very unique use-cases you'd want to explore would probably make for compelling software.

What I would tell a programming friend: Hey, the way I/we learned how to program is over, and I don't think that's a bad thing, because I've been more thoughtful about a login dialog, about accessibility in auth design, about architecture of complexity, than I've ever been when I had to write things by hand. This is like vibe coding, but with the scaffolding needed to go the distance, and the deep-linking necessary for the records to support rather than choke your codebase. I get to be both a project manager who has the Big Vision, but also with the authority and ability to control and tweak the design choices with a lot of detail (unlike what a human project manager gets from human developers), allowing, with practice, a faithfulness of vision that reminds me of the early days of freeware and shareware, when the bar for software building was suddenly lowered and you got all these really cool, really thoughtful digital experiences on floppy disks, CDs, and eventually online...

How's that? :-)

Thanks so much for your interest, and this second opportunity.

(

) I literally did not see you had posted a submission about AI-isms including "load-bearing" but what a coincidence!

It sounds like a good idea, but having used this approach in a professional codebase with dozens of contributors, I can tell you firsthand it will start to degrade the code you get from a model surprisingly quickly. The agent will start to feel confused by the various conflicting "guardrails" and "constraints" the ADR is supposedly documenting. You will ask the agent why it did a particular contrived thing and it will cite various flawed or outdated assumptions.

It's the same old problem of doc rot, but now the docs are blindly obeyed. It sounds simple to just keep the docs up-to-date, especially with AI, but that approach results in an unreadable AI slop trough.

I'm still unsure what to recommend instead, especially in a collaborative setting.

If you adopt ADRs, you also need to adopt the practice of keeping them up-to-date and saying which ADRs are superseded and/or deprecated and by what newer ADRs.

An ADR directory is an immutable append-only log of transactions over the architecture, if the reduction operation over the set leaves a state with contradictions, then your set of ADRs is not well-maintained.

Not saying this is a fault of the devs, I think it's a fault of the people teaching ADRs and telling everyone they're great and you should adopt them. They take time to maintain and keep coherent.

If your team doesn't have processes to do this, then it's like a bank account that everyone can write to, but when the moment comes to withdraw money from it, it turns out a lot of the writes were done with monopoly money instead of real money, and you're suddenly in the red.

There are no easy shortcuts.

The documents therefore become another abstraction of the code that has to be maintained. Better then to include the decision record in each PR.

This is so well said, thank you so much for summarizing it thusly in this thread!!

I completely agree, on everything: The records are not a one-and-done deal, they have to be maintained over the lifecycle of the codebase.

This methodology is trying to introduce records in the context of a practice in which they are maintained and used.

To your point, there are two aspects of this methodology that make it more sustainable:

- the entire corpus is deep-linkable at a granular level, and using path independent references — this allows interconnecting, referencing and ultimately ensuring the records and code keep strong mutual relevance by proximity

- the dense practice of including the why with a lot of granular detail, including discussions that built up to a final decisions (and what was considered but ruled out), this provides dense semantic context that helps future models that have no context almost become as knowledgeable about the architectural deliberations as if they had been there — this keeps the entire worth its cost of maintenance, because it provides what I call "epistemic continuity", a strong connection between the implementation and the rationale behind everyone of the design choices.

The idea is: "We can build code with models so quickly now, how do we ensure it's sustainable and well-architected and maintainable?" And this framework is trying to answer it by saying: "There is a methodology that introduces a cost overhead of O(1), but it provides long-term continuity guarantees."

Thank you again for stopping by, and providing the benefit of your experience with ADRs.

Thanks for your interest, and your comment, and your encouragement, and your feedback.

First, there's azeirah's excellent comment re: maintenance being a necessity (and paying off!).

Second, I really agree with you, in the sense that agents suffer a lot from contradictory, opposite requirements; but I would argue that they also suffer from under-specification, and that these two risks actually overlap (underspecification in the present can lead an agent to make choices that in the future will lead additional underspecification to have very little relevance or be contradictory with choices the agent has already made).

Part of the importance of the records in my methodology as I advocate them is that they be epistemically coherent. It's not a series of "do this, do that" or "requirement X, Y, Z, execute W, T, U", it's more of an extended explanation for what our situation is, what the idea is, how we are putting it into place, why, and what are the non-obvious choices we are making and why are we making them.

The agents, in my experience so far, don't get confused:

- they only read ADRs that are relevant to their work;

- when importing ideas/decisions from an ADR cross-project, the models (or their sub-agents) are never confused about the differences in context — they understand that project A (TypeScript, web, hosted on GitHub Pages) is different from project B (Rust, CLI, locally run) and how to adapt the imported decision accordingly.

Part of it is because, in the way that I've been building and practicing this, there's a requirement of epistemic coherence and epistemic consistency — everything is explained, nothing comes like a Deus Ex Machina which the model then has to extrapolate (and possibly be wrong about). In my experience this doesn't lead to models hallucinating requirements.

> I would like feedback on the onboarding, on what you make of the currently online materials, and how I could make any of this clearer. Thanks!

Currently the page is a lot of slop text without the main question most people who know what ADRs are and might be interested will have: what are the main differences and what do you see as the main advantages over other existing systems that use ADRs, the most popular one being Matt Pocock's?

You need to realize that there are thousands of projects like these. Most people who are in your target audience is already using something similar, so it needs to be instantly clear what the difference is. You've got 5 seconds and having to scroll through slop takes up most of those. Just being realistic here.

Thanks so much for your time and feedback!

Thanks so much for sharing Matt Pocock as a reference. I didn't know about him, and so I spent a couple of hours looking at his materials this morning — as you say there are a lot of versions of this out there, but this is particularly well done as far as I could tell, and I'm really grateful you helped cut through the noise for me! I am going to continue looking at this, but in the interest of giving you something tangible back:

From what I could tell Pocock uses ADRs in their typical form, and only after a decision has been made.

In ADRs for AI, the record is written during deliberation: The model structures an initial braindump (from a file or chat audio dump for instance) into a record with readback and ambiguities surfaced through questions with the ORRCF format (Options, Recommendation, Rationale, Confidence, Falsifier) and a human approves the recommendation or overrules it with more detail. There is a lot of tooling (MCP server, plugin, CLI, extension, iOS) because the record is a parsable, and analyzable, which, allows for its granular referencing and upkeep.

I'll work on your other questions. Thank you again for the reference and feedback.

PS: I think the other thing is: Part of my target audience are people who have never programmed before. This is scaffolded to be "vibe coding but with longevity." But it requires a different kind of effort — it's deliberative programming because for best results it requires you to be able to articulate the why behind your decisions. But that's something people who don't code can oftentimes be good at, for instance.

I think I see what happens with any new idea. You thought ADRs are important and now the agent produces piles of non-ADRs labeled as ADRs, which are really just some design decision, requirements, etc.

From your screenshot alone I can tell that those are not architecture decision records on the left side.

Ask yourself the question for each: is this truly an architecture decision or merely some design decision or requirement that now got some option a/b/c slapped onto it?

In the end you will just have a repo with hundreds of meaningless ADRs that your agent has to wade through.

Thanks a lot for your interest, your feedback and comments. Most importantly: Could you clarify which screenshot you are referencing to specifically? A URL would be perfect. Thanks!

Re: the rest of your comment:

When you say "piles of non-ADRs labeled as ADRs" — as I explained in another comment, this is literally true: The record format I am introducing are called "Architectural Deliberation Records" and while they are inspired by "Architectural [or Architecture] Decision Records" (Nygard), they are not the same thing. A "Deliberation" is the sequence of resolutions of points the agent could not resolve on their own (for a variety of reasons, including technical or contextual or because of underspecification), is not an "architectural significant significant" (at least not at the threshold intended when all writing is human writing) which is the trigger point of traditional Architectural Decision Records.

The resulting deliberation records are intentionally much more verbose, and these deliberation records are intentionally intended to be used much more frequently than traditional decision records, to capture all the thought process. This is inspired from complexity architecture's emphasis on process over state/outcome (i.e. process description vs state description).

The agents never "wade" through the whole folder: Agents use single Architectural Deliberation Records (ADRs hereafter) when working a feature; they also refer to other ADRs when they encounter deep-links in the ADR they are reading or code, or other references.

You're making me wonder whether I should coin a completely new acronym, but I've been using this one for so long — at first because I thought I would be using exactly the MADR but eventually my needs outgrew it.

And this post is a saddening bore,

'cause I wrote it ten times or more

It's about to be writ again

As I ask you to focus on

phrases spilled out by an LLM

...

---

On a more serious note:

I've built similar things ad-hoc when creating my project harnesses.

These decision lists kinda work but also they don't: The real challenge for me is fighting decoherence and keeping the orientation in a generated project.

So:

- I guess this works if you review and reshape the agents outputs manually.

- It does not help you a lot building a software factory.

Thanks for the poem, the feedback and the interest.

Yes, I think to your point: I do review the decision records, and when I approve them, it's because they've articulated something fully that makes sense. My job as the human is to ensure that the record doesn't contain bullshit. It requires me to be epistemically discerning, it requires me to be able to discern bad/broken/fallacious reasoning from epistemic reasoning. That's what colloquially is called "critical thinking."

The kind of approval I do on records is different from the approval of a lot of permission dialogs in CLI harnesses, where you basically see the command-line is harmless, but you don't necessarily fully understand what is going on.

You're right that this has a cost, and the ORRCF (Options, Recommendation, Rationale, Confidence, Falsifier) question format was surgically, or perhaps more honestly "iteratively", designed to reduce the cognitive load on the human: It essentially asks the model to prefetch all the information I might need to even think about a decision, including what the right call is likely to be and why, to bring it all into view for me, for my human context window limits, so that in a few minutes I can load the context in my working memory and be forever satisfied once I'm done that this decision will never have to be made again. It will transfer to other use cases, and other projects. Sometimes the models get things incredibly right, both from their latent space or the rest of our records, and sometimes there's an opportunity to introduce more of my philosophy that will help ensure this deliberation is made correctly now and in the future.

My understanding of your implication is that this isn't worthwhile: But I guess that's where my experience is different. I know (a) how to program, and I know (b) how to justify decisions and evaluate recommendations and reasonings, and I find that exercizing (b) in the context of software building is a better value-add, because I have found to both compound faster and also to make better use of my cognitive abilities. Instead of implementing my idea, I'm being scaffolded into narrowing it down so it can be understand non-ambiguously by current (and future) models.

And to your question, this has absolutely helped me build a software factory. For instance, when Anthropic deprecated Sonnet 4.5 from their platform, I built a harness in Rust and TypeScript that I can host on free tiers and uses various meshes of APIs. Over the summer, every morning, I would get a demo of the features built overnight, with open question raised; I would answer those, specify new features, and go to other projects until the next morning.

Where you are right is that the ADRs4AI framework itself is not all of the components for this formula, it's just the epistemic continuity — the preservation of the "why?" behind everything. There are other components, like pneumatic, the cross-vendor inter-model communication, and the general philosophy behind how I work with agents (which is as extended minds, moreso than extended hands).

The poem made me laugh and I think it's very creative and thoughtful. Thank you for that again! I hope my comment is more genuinely stimulating.

ADR's belong into version control but there they belong in the source code next to the thing they justify or substantiate.

Not only is this the only way to have a chance that they stay in sync with the code it also is the right way to make them easy for agents.

Y-statements are a nice way to practically do this.

We moved from an ai-maintained wiki in source control (ai_kb/...) to placing specification markdowns right next to the relevant code (src/featXYZ/SECURITY.md, ARCH.md, CONCURRENCY.md, ...). Importantly, we instructed our review/SKILL.md to find and load the spec hierarchy in as context. This helped a lot.

For change justifications, so far we have told the AI to strip change statements from code, and leave that kind of thing to the PR and commit messages. Making that more accessible than hammering git, GitHub can make sense. I'm hoping git protocol and tools catch up to make that more agent friendly, vs the trend of folks making their own new protocols and tools!

Thanks for your interest, and also for sharing your experience with so much detail. It's really interesting to hear your iterations through this same problem space — and instructive!

Can you clarify what "load the spec hierarchy in as context" as I am not sure if you mean "the files rooted here and below" (which makes sense to me, as intuitively that's a near-decomposable, decoupled description of your hierarchical system); or do you mean "the files above us in the hierarchy" (which describe supersets of context that live above the feature and help inform it)?

I'm not sure what you mean by "hammering" git — git is a robust version control and the overhead for commits is not big.

I don't think it makes sense for git to be overloaded with process information, rather I think it makes sense that, in the same way we have different mechanized programming languages (structured around compilers), we are going to have various standards of deliberative programming (structured around ???) — if you go on WakaTime, you'll see that a growing share of programming is done in Markdown.

Thanks for your interest, and thanks for agreeing that decision records like ADRs belong in version control.

I think it can make sense to have them next to the source code, but this introduces a couple problems like fragmentation of these records (perhaps mitigated if they follow naming conventions like test records do in certain languages/frameworks), and it introduces guesswork to know where cross-section work is documented: I would be curious how you've resolved that?

In this framework, the records live in docs/adr, and we've solved the problem of tight integration with deep-linking (adr://v1/repo/<owner>/<repo>/adr/<n>#<anchor>) and path-independent references. These, or shortcuts (like "adr-0002#qst-how-do-we-do-X"), are used in the code to avoid the problem you're correctly referencing of epistemic drift.

Re: Y-statements, thanks for the reminder, I forgot about those (for other readers, it's a template sentence: "In the context of …, facing …, we decided …, to achieve …, accepting …"). They are completely compatible and complementary with the decision section ORRCF format (I noticed the acronym is explained in the top comment so I won't keep explaining it).

I've done that too and given up on it. They got longer and longer, the LLM started adding them itself despite specific instructions to not do that, and in the end it let to context bloat. Better of without them.

I have solved this problem by forcing the model to compress every time by specifying token budgets for the documents

You mean word budget? I don't see how a token budget on the LLM helps with doc length. Or do we denominate the length of text docs in tokens now?

I understand, and I totally get where you are coming from: My initial attempts had "ceremony" that was not actually useful, and it took several attempts for me to understand what actually is useful.

A talk from Google Deepmind I heard at Princeton ("We Can't Understand AI Using our Existing Vocabulary") argued convincingly that the problem we encounter with models is one of total incomprehension. We are two very different ways of perceiving, processing, and thinking. We need to create more surface for communication and exchange, we need scaffold conversation more.

The models are trained to be cybernetic: To take your wishes and make it their command with as little interruption as possible. Even if they've now been encouraged to surface some questions, there's so much that is just taken away and that is decided. If you are interested in speed that's perhaps useful, but there's also a design space that is foreclosed from you that way.

At any rate, the models here are encouraged to: - Structure the braindumps of the human, flesh them out and resolve any open questions they can on their own - Surface, to the human, the tensions they can't resolve alone under the form of ORRCF questions

This is precisely calibrated to become a medium that, far from being about ceremony, is about resolving misunderstandings in the present.

Over time, the models get to know you not just by your instructions of what to do, but also by you providing more definition to your own thinking, such that it becomes easier for them to generalize it across new decisions and (if you import records) across new projects.

Re: your "despite specific instruction", yes, teachability is a big deal: I've been working most of the last few months putting together skills, MCPs, etc., and it's clear that providing granular and expansive documentary support is important. I suggest the plugin, adrs4ai/plugins, that you can already install and that I hope to be on the Anthropic Marketplace eventually!

Thanks for your interest and your thoughts, and I'd be interested if you have any more!

Great to see another way to do specification. I also created So created guidedog: https://github.com/insanai/guidedog for working with multiple AI providers, inspired by PEP, RFC and Oxide RFD.

I worked a lot of Python PEP which was adopted by rust and java later and working with RFC and RFC process since 1990's. Then later saw RFD by Oxide based on RFC. Learning from all of them created guidedog, the philosophy is if its good for human it is automatically very good for AI (most LLM are trained on it).

guidedog supports RestructuredText (since its specification) as core markup with support for markdown. Its modeled after sphinx but can work for documentation, discussions (what you call as Deliberation Records) and can be a static site generator. So you don't need 3 tools one single tool a cli which can do all three. For doing this I worked by porting docutils and then building own parser and compiler in rust.

This process so far worked extremely well for me as it is not just very good for AI, but provides complete control to humans. Also I like completely offline reading experience on paper. So this has first class pdf support.

If you look at repos in insanai many projects used this process with AI and worked well. Just one hard work this process needs for human agency is to really read each discussion properly and sometimes they can be long. But its a very small work which can help later with verification and even writing documentation for what's being built.

There is now a general consensus that agents should retain everything - but project from that retained state into more useful representations for each type of work. Your approach is good for creating evidence for all of the decisions - but the retained records will probably be too detailed as the main source for agents working in bigger or older repos. We need multilayer approach for this - but I am still not sure what it should be.

Here is a comparison of ADR4All and my approach (which I am now revising): https://zby.github.io/commonplace/work/decision-lifecycle-ev... - it lives in the whole workshop for revising my approach: https://zby.github.io/commonplace/work/decision-lifecycle-ev...

Want to add a link to your work to the architecture decision record repo? I maintain it.

https://github.com/architecture-decision-record/architecture...

This is very generous and very welcoming of you! Thank you, I would really appreciative and honored.

I do want to clarify that my "ADRs4AI" ADRs are different, they are "Architectural Deliberation Records" and are directly inspired by Architectural Decision Records, but they are different in that they are seeking to capture not just the outcome but the process. (Another poster was confused and did not realize the distinction, arguing that what I'm suggesting "non-ADRs labeled as ADRs", which is literally true, see https://news.ycombinator.com/item?id=50240908). My records are intentionally more verbose, they are intentionally trying to capture the process not the outcome(/state).

I would love to include ADRs4AI in your repo, but do you think the distinction is okay and can we draw it clearly? And if so, what's the next step? I could not find contributing guidelines.

Oh, separately, the marketplace extension also supports a strict superset of functionality of an Architectural Decision Record:

https://marketplace.visualstudio.com/items?itemName=jlumbros...

Thanks again for your interest and generous offer — and thanks for maintaining such a helpful resource (I only knew about https://adr.github.io/).

I made nearly the same idea but centered around semantic search with a pluggable embedding service and sqlite caching https://github.com/Sornaensis/adrai so it's just a CLI tool you tell your agents to use.

ADRs are organized by a domain hierarchy and can relate directly to individual files and path globs.

I find this absolutely improves cohesive development because it lets analysis and review agents scope ADRs with `adrai relevant path/to/file.rs` and `adrai search "blah blah"` And the ADR coverage can be more comprehensive and well organized without leading to too much context bloat if the models have to rediscover things all the time.

It is not worth my time. How anyone believes writing magic incantations to be interpreted by a non-deterministic black box of bullshit is better than writing the actual structured programming language is befuddling. Thinking there is an actual market for such an inane concept is naive.

When I was growing up, I was fascinated by good ol' combinatorial algorithms, the kind that Bob Tarjan was an expert in (like union-find, various kinds of crazy heaps, etc.). I loved the provable and deterministic nature of the guarantees. That's what I wanted to do research in, so when my PhD advisor, Philippe Flajolet, forced me to work on randomized algorithms—nasty non-deterministic monsters that always had some possibility of going completely off the rails—I was horrified and traumatized.

I don't know when I started feeling like randomization could be useful, but I think it's when I started to slowly realize that there are several kinds of randomness, different kinds of failures, different kinds of requirements. For instance a Bloom filter has false positives, but when it's job is to reduce the throughput of queries to a costlier computation, then the false positives don't matter so much, they don't matter to the exactness of the final computation.

It's commendable that you mention being in Internet marketing (i.e. sausage making :-) and I can imagine that the uses of models that you witness might make you cynical about them: The models can be collaborated in a variety of way, including cybernetic and epistemic. Cybernetic is when you ask models to do something for you. Epistemic is when you are trying to figure something out that you are curious about, and investigating with the model.

One of the most important aspects of the methodology is the Secondary Directive: Surface doubts. This means the magic incantations involve an extended conversation or round of question answering that narrow down anything that is unknown or that is underspecified. There are multiple opportunities in these interactions to constrain the final output of the model.

At any rate, I get and respect your skepticism. Assuming you know what falsification is: What would it take for you to change your mind about the usefulness of the "non-deterministic black box of bullshit"?

I must be dense but I'm not clear on what the acronym ADR refers to here. I assumed it might have referred to Account Development Representative (junior sales role) but was wrong. EDIT: I see it is defined in The Hacker News Post but not in the actual website

No, you're not dense at all: Thank you so much for the feedback. It's more that when you're fish you're like "what do you mean 'water'?"

Point taken that I need to change my materials ASAP.

In my world, ADRs = Architectural DELIBERATION Records, and the emphasis is on being dense and on capturing the process over (or rather in addition to) the outcome. From complexity theory, we know that process is more generative than state.

An ADR, as Architectural DECISION Record, is a practice predating but popularized by Michael Nygard in early 2010s. It focuses on writing down the reason (and other options considered) for important decisions.

My framework is inspired, but different in a few respects but including: - it's optimized for iteration, multi-party communication; - the records are intentionally much more dense and verbose: They consider that what was non-obvious and deliberated carefully is as interesting as the final call; - there is an emphasis on deep-linking the records and referencing questions, sections in code and across records.

Thanks for your attention, and I am going to make changes to the website so that the acronym is spelled out at least once!

How many decisions per hour of work do you make? The answer is a lot. Most of them aren't worth recording. So, the questions that need to be answered in my mind are "What makes this decision worth recording?" and the related "How is having this ADR going to impact what agents actually do in the future?"

Thanks for your interest. I (very respectfully!) disagree that most, or indeed that any, of my decisions aren't worth recording. I have an explicit "completist" attitude to epistemic materials (records).

First, we have LOTS of space now and decision records are cheap: We now can get several terabytes for a hundred or a couple hundred dollars. Storing the record of decisions is a drop in the bucket. In practical terms, taking the time to specify project-specific records helps ensure adherence and faithfulness from models; but very often, I've found the cross-projects benefits are also extraordinary (more on that in the third point!).

Second, as I mentioned in some other comments, the methodology instructs models to surface all uncertainties and all doubts (Secondary Directive) and to commit all discussions (Prime Directive), but to surface these as ORRCF-formatted questions, with ORRCF (pronounced ORR-ssef) = Options, Recommendation, Rationale, Confidence, Falsifier. It's a way of surfacing doubts where your cognitive load is reduced, because everything you need to think about is brought up in the same screen, and you get to either endorse to recommendation knowingly, or override it with exactly what needs to be captured in disagreement.

Third, when I disagree with the model's recommendation (or even when I agree, but have extended requirements, caveats, ideas, etc.) everyone of my decisions is fully thought-out: When I make decisions of deployment platforms based on predicted economics factors, or when I decide not to use Meta-created or Meta-related libraries for ethical reasons, or when I make decisions about modal grouping in user interfaces, or principles under which the user must be guaranteed never to have drafts clobbered, those are all worth capturing. All of these decisions compound, in the sense that, with the right indexing they can be referred to in the future: I can point to a set of records rather than specify, or I can have the model send a sub-agent to send a cluster of past projects for relevant decision records.

At least, for me (perhaps because of my neurotype), it is more enjoyable and efficient to think deliberately slowly about each decision, to fully specify my thinking factoring everything I know — and to do so, knowing that now it will pay off in the sense that I will never have to explain myself again because I've put down my best thinking on this problem and can cite it forever in my future projects.

I am decoupling thinking and doing, and it's really compounding over time, and producing sustainable epistemic scaffolding to my projects.

To be very concrete, here's the loop of work in this model: - You do an audio braindump of your thoughts - Models iterate with you until it is well-defined enough that they can put together an initial draft of one or more ADRs (possibly 10-20 if you are bootstrapping a project) - Any more-granular tensions are now surfaced to you as ORRCF-formatted QST questions, and you get to look at them in whatever order you want (including in orders suggested by models through the QuestionTour feature) - You look at the questions and most of the times approve the recommendation, but occasionally, there's an opportunity for you to inject a zest of what makes you, Selkirk, your special epistemic patina, and you override the recommendation with something new, bold, beautiful, unique the models couldn't have foreseen even with what they are starting to know, through the previous records, about you - After answering, the models, build, build, build, build, build, autonomously, and only surface for air if there are new tensions that surface - Meanwhile as you see the results take shape, you are hungry for more and start brain dumping more ideas, which they structure, surface questions, which you answer, they build, iterate, and so on - The records are what the models understand and what they need you for, it's not a post-hoc ceremony, it speeds up the process!

I hope this makes sense?