| Yeah the single file SYSTEM.md would not scale. When you are working on something, you don't load entire context of entire app in your head, only "minimal viable context" (MVC). In my ERD this is a record in the Spec table. And sure, some specs might reference other specs. Some can depend implicitly or explicitly. But this is a clear anchor point you can approach two ways: either from searching from a list of specs, or by going to file you know needs editing, and calling `blast-radius` script to fetch which specs link to it. Intent can be represented as granular artifacts. The tiniest granularity in my schema is Acceptance Criterion, where it is represented in code as a test. It can be e2e, unit, integration — depends on the context and what is "acceptable" way to prove AC works on system level. For example, AC for product-level spec that says "Invalid input is rejected with clear feedback" (Submitting invalid input shows validation error and does not create a short URL record) means that we have e2e test in playwright that starts from the URL creation page and follows user across steps to receive the error. And the engineers who are working on this AC see it with their own eyes. But this might not be enough. Why? Because you can still show an error on screen, but the record in the DB would be created. So I decided there should be one more window that shows state of the objects (their properties) in real time. This could be simple TUI that just visualizes "evidence artifacts". Think of how a debugger works: you can step forward and you have local variables you can track. So the idea is simple: "Watch how playwright script executes steps for AC one by one, while you look at the DB table. After every step you see updated object state. If multiple state changes happened after a single step, ideally we want to display history of updates. At the end of run we compare evidence before/after state for every tracked object." I call this "runtime engine". This is approximately how engineers simulate it in their head when reading code. But why even bother simulating it, when we can simply run and observe what happens? |