Source of Truth
Time for a more technical note: The debate is raging on over whether the age of agentic software development means that the most important piece of documentation is THE SPEC. That mythical document that writes down, in plain language, all the things the system should do, must do, and should never do. From this spec, the agent can generate pesky details like working code.
In my view, the only source of truth for a software system is the code itself. Everything else can (and therefore will) drift. Comments? Requirements documents? Specifications? All are outdated the moment you touch the code without remembering to touch the supporting document. The only thing that can't possibly lie about what it does is the code.
The problem with that, as someone pointed out: Code can be hard to read, even when it's well-written. Business logic and domain knowledge are spread out over various functions and classes. Piecing it all together is a big task. So if a product manager wants to know, "Hey, how does our contract review software handle a counterparty redline in this edge case?" someone has to dive into the code and piece it all together.
Sure, AI can do that relatively efficiently, but what would be even better: If for each piece of business logic - each edge case that gets handled one way versus another - there exists a test in the automated test suite. Remember, code doesn't lie. Tests are code. So tests don't lie. Tests are the antidote to the sprawl that can happen with business logic once it gets translated to code. In our fictitious example, there'd be a test that sets up a contract with a counterparty redline that triggers that edge case and explicitly spells out what we expect the software to do.
You could even have an AI that translates these tests back into plain language for non-technical people to enjoy, but even their raw source code is quite readable.
When it comes to bridging the business side to the software side, we don't need to reinvent the wheel. Test-cases already do a fantastic job at that.
