I'd like to propose some tools addressing the "how" part. I recently worked on a SKILL to generate user stories (or recipes, depending on the implementation stage) based on an AIP. The idea is to assist AIP writers to showcase specific ways to use the new functionality. Although this SKILL generates standalone files, my idea was to include them inside the feature docs (or perhaps under a new docs section called recipes/playbook - since if this is adopted broadly, the best practices section might explode). The PR is here: https://github.com/apache/airflow/pull/65776 (just saw that Jarek already approved it)
As for intent docs: the above PR contains a collapsed section called "Manifest / ADR". This has the spec whose implementation resulted in the PR you see, and documents some decisions made while defining and implementing the feature -- in a way a coding assistant can follow and verify. This uses the https://github.com/doodledood/manifest-dev agent plugin, which can also produce human-readable ADRs from a session transcript (examples here: https://github.com/Dev-iL/manifest-dev/tree/2603%2Fadr_examples/docs%2Fadr). I think we might be able to add another layer to this (on the Airflow side) that turns an AIP+comments into a manifest. On Sun, 26 Apr 2026, 5:10 Jarek Potiuk, <[email protected]> wrote: > Of course - but if we want to "force" (do we? How?) user > documentation before a feature is developed then without expressing intent > of what we want to implement first, it might be extra effort that will be > difficult to do. > > I never proposed to "force" ADR, I suggested treating it as a good > practice. I was even thinking that as a first step of introducing them we > could retroactively generate ADRs and first ensure consistency between ADRs > and user documentation. Then, we could add agentic instructions to keep > these in sync (which is more than possible now). This would be my way of > "gently" introducing them rather than forcing. I think this has a chance of > working quite naturally. > > BTW. Do you want to propose a way to "force" users to read the > documentation? Or should it just suggest/recommend? What would you suggest > there? How would you implement it? > > I really like the approach of Python PEPs, where mandatory part of any > change is "How to teach this?". So... how? >
