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.

Thank you for taking your time to explain this in such a detail, greatly appreciated! I was talking about https://adrs.systems/screens/extension-open-questions.png .

Indeed, the acronym ADR is extremely confusing for everyone knowing Architecture Decision Records. Obviously i (and many others) misunderstood and so, my comment is moot.

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 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"?

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.

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///adr/#) 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).

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?

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!

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.

> Thanks for the poem, the feedback and the interest.

It's a paraphrasing of bowies "Life on Mars"

> pneumatic

Interesting! Will check out.

> ... 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

Okay this is an aspect I've not considered enough maybe. But this then applies mostly to decisions that can be phrased project-agnostic.

> My understanding of your implication is that this isn't worthwhile

No. I actually think it is worthwhile!

But I don't think it differs substantially from just having an ad-hoc project harness that's just a bunch of markdown and is maintained by the agents based on the discussions.

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!

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.