F1. Narrative Clarity

Diagnoses: D1. The Scattered Story Related fixes:

• F2 (Data Flow Primacy) — visible data flow is the substrate narrative rides on
• F3 (Interpreter Pattern) — making intent visible as data is the strongest form of narrative clarity

The concept

A well-structured codebase has the quality of a well-told story. For any given event, there is a spine — a traceable path from trigger to outcome — that a reader can follow without needing to hold the entire system in their head. This is the code-level manifestation of Brooks’s conceptual integrity (see sources.md): the system feels like it was designed by one mind, with a coherent plot.

Narrative clarity doesn’t mean everything lives in one file. It means that at each point along the spine, the reader can see:

• What just happened (the data arriving at this stage)
• What will happen next (the transformation or decision at this stage)
• Where the result goes (the output or the next stage)

When narrative structure is absent, the reader must reconstruct the plot from scattered clues — a callback registered here, a state mutation there, an event emitted somewhere else. Each jump consumes a chunk of working memory. After a few jumps, the reader’s mental model collapses.

Remedy

For every significant event path in the system, ensure there is a single place where the reader can see the outline of the story — even if the details live elsewhere. This might be:

• A top-level function that calls each stage in sequence
• A pipeline where each step’s input and output are visible
• A module whose exports correspond to the stages of the event path

The details can be deep (hidden behind well-named function calls), but the spine must be shallow — visible in one reading.