I've been stuck with this problem for 10+ years now. I'm tired I'm exhausted. Every single time I come to new company, nobody writes spec and expects you to magically understand how app works, just by reading legacy artifacts.

But in my experience, engineers writing quality artifacts are rare. Usually it's Staff+ where they understand importance of proper context.

So I want to show the world it's not that hard to do, and while doing so I believe I can automate like at least 50% of the pain everyone is having while "reverse-engineering specs/ACs from code".

The initial thought I had: "what if I edit a file and I immediately can tell which spec is gonna blow up?". That led me to SCIP indexes. OK cool, how do you actually connect Spec to codebase?

I've stuck for a long time for this one.

Then I figured ok this can be just Routes! Rails routes. Django routes. Whatever. The entry level to your application is the edge between business logic and your client-side app.

1. /auth -> Spec that explains how auth works 2. POST /urls/new + GET /urls -> Spec that explains how to create new URLs

OK cool... what next? Spec captures real world. It is lossy compression. And it is still not enough to go from spec -> code directly.

Spec is implemented with Acceptance Criterions.

What is AC? It's E2E test with the concrete steps user makes to show "this AC works".

OK cool. How do I verify "AC works"?

Evidence Artifacts.

When you create `POST /urls/new`, what do you expect to happen?

1. `insert into urls values (...)` 2. HTTP status 200 3. UI message "URL created" 4. ... whatever else you care about

Cool! Now what? How does that help me understand code I'm looking at?

Simple. One AC -> map to functions/classes/symbols that are used during execution (ever heard of traces?). So when I open a file, I see "okay so this file is used in AC1, AC21, AC8912, and so on". If I touch this file, I have to check those ACs. How do I check them? I run E2E tests that they point to. And I read ACs (English), and I verify what is going on in the system (code + artifacts).

So far so good?

Okay next. Let's say we reviewed that this new feature added 1 AC, modified another AC. And all good. We mark it as green. How do I commit it? Well, you go and describe exactly, what was the context behind this AC (SPEC we're touching, real-world context, anything that helps engineer to understand what is the situation we're in), why we did this change (because... business! or maybe because we made an incorrect assumption, so bug appeared, or we just doing refactor/tech debt removal), and how to test it (verify section, which could be just pointers to ACs/tests we were running).

If I haven't lost you yet, here's final part.

You can build this schema without EVER integrating it into codebase. It can live on your disk. You just work normally on your project. But once you realized "okay so this needs to work according to Spec...", you no longer have to store it in your brain, you just run Rust CLI script to create new spec object, and link files that are important. And when you are doing code review, you just run yet another CLI tool "git diff | blast-radius" -> which specs/ACs are affected, what should I be testing? And keeping specs/ACs mapping to codebase is simple: when something changes, you need to update index, and new files must be under a spec, deleted files should be removed from SCIP, edited files should be re-tested, to see whether they still belong to same spec or you need to update the maps.

I believe this already provides value even if nobody else is using it. I'm giving away structure for your spec/ac/e2e/evidence/review artifacts. For free.

I just want proper feedback on this. What do you think?

edit: I will make a proper post on HN after I build the MVP with instructions on how to use and example workflows (greenfield project / legacy project with 10-500k LoC), the code would be Apache/MIT whatever. And later maybe I'll try to build something like Stage with nice UI and so on. But I want to solve this problem first, which is "teaching people to leave proper work artifacts and connecting their work from requirements to code, all the way through".

Hope that makes sense!

And thanks for reading.