IDRs as Records of Intent

This is good, however it’s unclear to me how to manage it in the long run. The list [0] will grow to hundreds of IDRs or more in the long run, and inevitably some will become inapplicable, contradict other IDRs, or become actively misleading when the software evolves. Since the IDRs are supposed to provide information the LLM can’t infer by itself, using the LLM to evaluate their continued applicability is likely not practical.

To effectively manage them, you’d need some sort of topical (?) index to be able to find the relevant IDRs that may need to be updated or removed. Sometimes they might be tied to a particular submodule, but many IDRs may have more crosscutting concerns.

In the end, it’s a form of documentation that needs to be maintained, instead of remaining one-offs limited to the task at hand.

[0] https://github.com/wlach/repo-parser/tree/main/idrs

I don't really know why it's important to "provide a durable record of a decision made during the implementation of a feature", but other than that I do something similar. I have the agent write a PLAN.md which looks just like this IDR template. It's written before implementation begins, and I approve it before the agent goes. I don't save them after the session ends.

For each project, I define "review surfaces": parts of the code that I have a strong opinion about. These get resolved in detail before implementation begins; the LLM can do whatever it wants to other parts of the code, but the parts I list can't change without another review. Typically, these are things like the public API or database schema.