⇩ Markdown

considering dark software factories→dark software factory -- concepts→context right in the repo

context right in the repo

^ context right in the code repo

This means logs, metrics, and also a documentation context graph

context engineering

Backlinks

code-associated specification files are just a part of the documentation context graph

For example, you can have a code-associated specification file, but for the graph to be complete, you should also have associated use cases that role up to design principles, persona needs, etc. Put that context right in the repo. If it's a documentation context graph, it needn't cause context rot because progressive disclosure is a fundamental aspect of graphs.

see in context
dark software factory -- concepts

context right in the repo

see in context
free recall - Open AI harness blog post - 2026-02

The second principle was strive for dim - legibility -- higher for the agent... AKA agent legibility. This means giving the agent everything it needs to get the job done: context right in the repo specs right alongside the code, all the logs, traces, etc. it also means keeping the code base structurally legible. Obvious folders, strict and clear naming conventions, etc.

see in context
specialized agent -- code merge

One thing that can help such an agent is context right in the repo, especially a documentation context graph

see in context
what is the 'spec' in spec-driven development?

I believe that a well factored documentation context graph is superior way to model that context, and that there are many advantages to storing that context right in the repo. I think that specs for features should be a a PRD-ERD hybrid that should be deconstructed into a well-factored documentation context graph that can help orient the agents and the humans working with the system. Basically, the 'spec' part of a documentation context graph should be at a PRD and light ERD hybrid level.

see in context