The DAG Was Perfect. The Documentation Still Missed the Point.

A practitioner building auto-documentation for data pipelines posted an honest observation on Hacker News. They switched from plain text descriptions to graphviz dot format as pipeline representation. GPT-4 handled the graph well. Tactical documentation — what each node does, how nodes connect, what transformations run — came out accurately. Then it stopped improving.

Higher-level intent. The why of the pipeline. Why it exists, what business question it was built to answer, what decision it was designed to support. That stayed out of reach. Their read: push prompting harder.

The structural read is different.

When you represent a pipeline as a DAG, you’re encoding execution logic: nodes, edges, transformation sequences, data flow. That’s what graphs carry. The format worked for exactly the domain it could work for.

Intent isn’t a node. It isn’t an edge. It isn’t in the dot file at any level of refinement. The purpose of a pipeline was created by different people, at a different time, for a different purpose. It doesn’t appear in the execution graph because it was never placed there.

Before accepting “more prompting” as the fix, one test: can this gap be closed by changing the representation of data already in the system?

No. The information is structurally absent, not malformatted.

Notice what happened. The improvement occurred exactly where the graph carried information. The remaining gap appeared exactly where the graph carried none. The team kept iterating on representation because representation had just produced a visible gain. But the unresolved question no longer lived there.

In StratoAtlas terms, this is Level Mismatch — an intervention applied at the representation level, a problem persisting at the context model level. The diagnosis keeps pointing at representation because that’s where the last improvement was visible.

Prompting iterates on what’s present in the input. RAG over execution logs produces more execution-level signal. Neither imports what isn’t there.

The structural move: augment pipelines with architectural context from their origin. Design rationale, product requirements, intent annotations captured at authoring time. Not RAG over execution logs — RAG over design documentation. Or better: intent fields at creation time, so the information exists to be indexed.

Without that import, documentation will continue to accurately describe what pipelines do while remaining structurally blind to why they exist.

The graph was right. The input corpus was incomplete.

Full structural diagnosis: https://stratoatlas.com/cases/case-a-ai-2026-045.html

Roman Kir · StratoAtlas Research ORCID: https://orcid.org/0009-0004-2907-9522 stratoatlas.com · CC BY-NC-ND 4.0 · stratoatlas.com/legal/license