[victorsavkin]

> That doesn't make the decision set good. And if the only documentation produced came from the implementation phase, then it's going to be self-defending regardless of how good the design actually is (and your review agent, lacking the context, won't know the difference). Multiply that with the many parallel PRs in parallel repos you get with some features, and that's just asking for trouble.

Firstly, I think it's a misunderstanding of where the truth lies. The truth is in the code and in the process that produced it. The code isn't out of date. The written documentation always is (to some degree). It's a map vs. terrain situation. Maps are useful, but they aren't a replacement for the terrain.

On top of that, when I review a coworker's code I also get their session, ready to explore. I ask questions about the decisions they made, and I can interact with their version of the code if something wasn't captured in the session. It's like getting access to their whole environment: the code, the agents' state, and everything else.

You just can't do that with a markdown doc.

This doesn't mean markdown docs aren't useful. They are useful. Maps are useful. But it's simply not the same thing.

Secondly, let's imagine it's possible to document really well every nuance of every decision made. This assumes everyone will do it, so it requires effort from every eng on the team. This is different here cause you get episodic memory without any effort :)