Common document topologies

This is a recommendation, not a taxonomy or product contract. These shapes are useful starting points for arranging existing flat documents and references around an outcome. A good topology also makes authority legible: which document owns the current answer, what it is answerable to, and what depends on it. Adapt or combine the shapes when the work teaches you something better.

Start with the flow

Choose a topology by asking how understanding should move:

Topology is outcome-relative. The same document can be a source in one view, the centre of another, and evidence in a third. It does not acquire a permanent parent or position.

Convergence and synthesis

Hub and spoke: many independent documents point into one synthesis. Use it when sources can remain intact while one document owns the current answer. Example: persona documents around a marketing strategy.

Funnel: broad inputs converge through intermediate themes into a conclusion. Use it when the synthesis would be difficult to justify directly from many raw sources. Example: interviews into findings, principles, and then a roadmap.

Bow tie: many inputs converge into one strategy or decision, then diverge into several actions. Use it when one understanding should coordinate multiple downstream efforts. Example: research into a strategy, then campaigns and experiments.

Exploration and judgment

Tree: one question branches into alternatives, subquestions, or scenarios. Use it when the space must be explored explicitly and each branch can be evaluated separately. A decision document may later distil the result without erasing the exploration.

Double diamond: exploration expands, contracts into a definition, expands again into possible solutions, and contracts into a result. Use it for discovery and design work where premature convergence is dangerous.

Argument map: claims connect to supporting evidence, objections, and rebuttals. Use it when the quality of reasoning matters more than a linear narrative, such as policy, strategy, research, or consequential decisions.

Execution and learning

Pipeline: documents transform through ordered stages. Use it when each stage has a distinct owner, review boundary, or artifact. Example: brief, research, draft, review, and publication.

Dependency graph: documents point to prerequisites without forming one parent hierarchy. Use it for architecture, plans, requirements, and implementation work where several downstream artifacts depend on the same decision.

Feedback loop: governing understanding produces work; work produces observations; review and distillation turn verified observations into changes to the governing understanding. Use it when the system should learn from outcomes rather than merely record activity.

Comparison and coverage

Matrix or bipartite graph: documents in one set connect to documents in another. Use it for many-to-many questions such as personas and needs, requirements and capabilities, risks and controls, or experiments and hypotheses.

Constellation: several peer documents describe a domain without one permanent synthesis owner. Use it when forcing a centre would imply authority that does not exist. Add a temporary synthesis when an outcome needs one.

Timeline: records remain pinned to their moments while retrospectives or current-state documents interpret them. Use it when history must remain faithful but present understanding must still evolve.

Attention topology

Place the artifact currently being judged at the centre. Put active evidence, decisions, and unresolved questions near it. Keep provenance, history, and inactive supporting material in an outer ring.

This helps humans see one object of attention without losing its context. An agent may traverse the wider graph, but it also benefits by loading only the context relevant to the current outcome.

Combining shapes

Useful systems often combine topologies. A question may branch as a tree, converge through a funnel into a strategy, diverge as a bow tie into experiments, and close as a feedback loop when results revise the strategy.

Combine shapes only when each transition has a clear job. Complexity is not evidence of sophistication.

How to judge a topology

A useful topology should make these questions easier to answer:

Which document is authoritative for the current answer, and who owns keeping it current?

Can evidence, reasoning, and the authority behind the current answer be traced?

Will a new observation reach the authoritative document it should update, and can dependent work notice that change?

If the arrangement does not improve those answers, reshape it.

References and projections

The documents and their references remain canonical. State what each reference means in the surrounding sentence, following Keep references close to what they support.

A lens, canvas, website, dashboard, or custom application may project the same graph as a hub, tree, pipeline, or another layout. Physical placement and interface structure are views, not a second source of truth. The underlying documents remain flat, and topology is never a document type, schema, or application hierarchy.

People and agents operate on the topology; they are not knowledge nodes in the same sense as the durable documents they read and change. This distinction lets the executor change while the organization’s knowledge, authority, and dependencies remain stable. Use Shape the document before refining it when one document contains several objects of attention. For autonomous or recurring work, Loop and Graph Engineering explains how agents can operate over the durable graph without becoming its source of truth.

A useful prompt

Ask your agent: "Map the documents relevant to this outcome. Identify which document owns each current answer, what evidence it is answerable to, and what depends on it. Say how understanding should flow between the documents, choose the simplest useful topology, and explain the role of each reference. Keep the documents flat. Treat agents as operators on the topology and visual or application layouts as projections, not as document ownership."

A document topology does not need to contain every system the work touches. An authoritative database, repository, analytics system, mailbox, or other external source can remain outside the document graph. The relevant document should make its role legible: what the source owns, how it can be reached, which definitions govern it, and what durable conclusions or decisions have been derived from it. Treat generated tables, charts, dashboards, and visual layouts as projections for attention and review rather than as ownership of the underlying state.

When an agent discovers a topology that repeatedly helps your organization, preserve it there: explain the flow, show it with a small text diagram, and say when to use it. Link to that document from AGENTS.md when it is organization-wide guidance; keep task-specific arrangements with the work they serve.