documentation context graph

^ documentation context graph

Backlinks

an issue tracker doesn't feel like the right place for app specification

An issue tracker feels like a reasonable place for quick bugs, but a better place for specification feels like documentation context graph.

see in context

In an ideal world, you'd work with an agent to modify your documentation context graph and then the agent would do a reconciliation between before and after and propose some migration-like ephemeral work to get you there. That work would make sense in an issue tracker, but putting it there should be the agent's job, not the human's. Humans should essentially be working at the "epic" level in a way that updates the documentation context graph.

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

^ code-associated specification file is a part of documentation context graph

see in context

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
context right in the repo

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

see in context
documentation context graph -- document

^ documentation context graph -- document

see in context
modularity in app specification files

Something very modular would be like a documentation context graph

see in context
review - Open AI harness blog post - 2026-02-22

Note: in this section they describe their documentation. I've been referring to this type of documentation as a documentation context graph

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
the 'spec' part of a documentation context graph should be at a PRD and light ERD hybrid level

^ The specification part of a documentation context graph should be at a PRD-ERD hybrid level of detail

see in context
thoughts on Symphony Spec and Gas Town 2026-03

The Symphony spec makes me think about how I thought the specification was best as documentation context graph, but this one long doc seems to work well, too

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

I think that question gets at the heart of the matter. It's just not clear what specification actually is. So far, in my experience doing agentic coding, a reasonable specification has been, essentially, durable and persistent ERD-level artifacts that are decomposed into a documentation context graph. Or, more specifically the 'spec' part of a documentation context graph should be at a PRD and light ERD hybrid level

see in context

To actually complete the coding, I start with those specifications then do a more ephemeral, detailed, and interactive planning phase, then work iteratively with the agent to complete the actual coding. When complete, that process can lead to some updates to the documentation context graph as a side-effect of the implementation process, but they tend to be pretty high-level updates. Perhaps we came up with a better name for a folder, or added some additional high-level constraint.

see in context

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