Clanker Technical Architect: First on the Scene with Progressive Disclosure#

Evolution keeps discovering the same solution. Sharks and dolphins both arrived at the same hydrodynamically optimal shape. Bats and birds both evolved wings. The fitness function doesn’t care about ancestry. It only cares about what works in the environment.

Something similar happened in software architecture between 1995 and 2011. You’ve probably seen a C4 diagram. Maybe you’ve written an ADR. What you probably haven’t heard is that these tools, and four others, independently discovered the same structural insight without knowing the others existed: complex information about a system must be partitioned by audience and need, because revealing everything to everyone simultaneously produces documentation that serves no one well.

None of them called it progressive disclosure. The term came from HCI. But the mechanism was identical.

The fact that six different communities discovered it independently, across three decades, is the strongest possible evidence that progressive disclosure is a fundamental principle of information design. It is not a UX trick. It is not an AI workaround. It is a constraint of how complex knowledge must be structured to be consumable.

Six independent discoveries, three decades apart, all converging on the same principle.

The artifact pyramid names this principle and generalizes it in a way that no single architecture methodology ever did. And the Technical Architect profile in the Clanker pipeline? It carries this lineage directly. Its SOUL.md says “document decisions as ADRs.” Its methodology references the C4 Model. It was built on thirty years of practice that most AI engineers have never read.

Six Independent Discoveries#

The pattern appears earliest in Philippe Kruchten’s 1995 paper on the 4+1 Architectural View Model. Kruchten’s motivation reads almost like a progressive disclosure manifesto: “this use of multiple views allows to address separately the concerns of the various stakeholders of the architecture.” His Table 1 maps each view to a specific audience and set of concerns. The logical view shows end-users what they care about. The process view shows integrators what they need. The development view shows developers the module structure. The physical view shows operations the deployment topology. Each audience sees a deliberately partial representation, and the paper explicitly allows views to be omitted: “views that are useless can be omitted from the architecture description.” This is the first explicit statement in the architecture literature that what you show should be determined by who needs to see it.

Kruchten called them “concurrent views.” He did not say “progressive disclosure.”

Five years later, the IEEE 1471 standard formalized this insight. The standard defined a view as “a partial expression of the architecture with respect to a particular viewpoint” and established that “architecture descriptions are inherently multi-view: no single view captures all concerns.” The vocabulary shifted: “stakeholder concerns,” “viewpoints,” “partial expression.” But the mechanism was unchanged: partition the knowledge, scope each partition to a specific audience.

The standard called it “partial expressions.” It did not say “progressive disclosure.”

Simon Brown created the C4 Model around 2011, taking a different path to the same destination. Where Kruchten and IEEE 1471 partitioned by stakeholder role, Brown partitioned by level of abstraction. His four levels (Context, Container, Component, Code) form a strict hierarchy of increasing detail. The metaphor is spatial: the C4 Model is “Google Maps for your code,” zooming from satellite view to street level. Each level targets a specific audience, and the model explicitly discourages mixing them. Practitioners at Visual Paradigm and DevIQ now explicitly label C4 as “progressive disclosure,” and one of the most telling details in the C4 literature is the estimate that 80% of the value comes from Levels 1 and 2 alone. Brown never used the term. He said “hierarchical abstractions” and “zoom levels.” The community retroactively named the principle.

The mapping from C4 to the artifact pyramid is almost too clean. C4’s Level 1 (Context) is an L1 summary: a single diagram showing the system in its environment, consumable by anyone. Levels 2 and 3 (Container and Component) are L2 analysis: technical depth for developers and architects. Level 4 (Code) is L3 dossiers: implementation detail pulled on demand by the developers who need it.

Notice a pattern yet? Three of the six methodologies already mirror the pyramid’s three-layer structure. The others just needed different labels to get there.

The C4 Model's four zoom levels map almost one-to-one to the artifact pyramid's three layers.

The arc42 template, created by Peter Hruschka and Gernot Starke around 2008, followed a different route. arc42 is a 12-section template, but its design philosophy incorporates three built-in depth modes: lean (lightweight, minimal), essential (the core information you must always document), and thorough (formal, auditable, complete). These are the same 12 sections applied at different disclosure levels. The arc42 Canvas pushes this further: it is a one-page summary described as “the zip-version of conventional arc42 documentation,” designed to replace the full template for quick consumption. A practitioner who needs the elevator pitch reads the Canvas. A practitioner who needs the full picture reads the template. This is the closest architectural analog to an artifact pyramid L1 summary: a compressed entry point that leads to deeper detail on demand.

arc42 called it “tailoring.” It did not say “progressive disclosure.”

Architecture Decision Records, proposed by Michael Nygard in a 2011 blog post, solved a completely different problem with the same logic. Traditional architecture documentation was monolithic and quickly grew stale. Nygard proposed capturing one decision per short document, numbered sequentially, stored in version control. Each ADR has five sections: Context, Decision, Status, Consequences. The progressive disclosure insight is in the chaining mechanism: “the consequences of one ADR are very likely to become the context for subsequent ADRs.” A consumer reads as many ADRs as their context requires. The chain naturally reveals itself as the reader follows the thread of consequences backward or forward. ADRs are progressive disclosure at the atomic unit level: bounded, self-contained, chainable.

Nygard called them “small, modular documents.” He did not say “progressive disclosure.”

The SEI’s “Documenting Software Architectures: Views and Beyond” (Clements et al., 2010) contributed perhaps the most directly relevant insight. The “Beyond” in the title refers to the process of choosing which views to produce: going beyond individual views to the methodology of selecting, relating, and packaging architectural documentation for a specific audience and context. This is progressive disclosure applied to the production side: you do not document everything; you decide what to document based on who will read it.

Views and Beyond called it “view selection.” It did not say “progressive disclosure.”

What Architecture Found and What It Missed#

Six methodologies. Six different names for the same mechanism. None of them recognized that they were discovering a principle that the HCI community, working in a completely different domain, had begun calling progressive disclosure.

The artifact pyramid, published at Groktopus and open-sourced at github.com/groktopus/artifact-pyramids, names what they all found and extends it along three axes that architecture documentation never addressed.

The Hybrid: A Complete Agentic Architecture Framework#

Six methodologies converged on progressive disclosure, but no single one of them was designed for what an AI agent needs to consume. C4 gives structural hierarchy. ADRs give decision rationale. arc42 gives constraint and context boundaries. Each is strong where the other two are silent.

For a human architect, this gap doesn’t matter much. A human sees a C4 diagram and fills in the reasoning from experience. They know which constraints apply because they were in the meeting. They remember past decisions that led to the current structure. The knowledge is distributed across their career, not their document set.

An agent has no career. It has context. And if the decision rationale and constraint framework are not in the artifacts it receives, they don’t exist for it.

This makes the hybrid not an optimization but a requirement. The three methodologies address orthogonal dimensions of the same problem:

Three orthogonal dimensions of the hybrid framework — structure, decisions, and constraints — each addressing a different axis of what an agent needs to consume.

Structure, decisions, and constraints braid together into a single consumable framework. Three lineages, one convergence point.

The three cards map each methodology to its native layer within the artifact pyramid. The convergence diagram captures the braiding visually: three separate lineages, each carrying a critical dimension, converging into a single consumable framework.

Why This Works for Agents#

The hybrid is not arbitrary composition. It follows from the artifact pyramid’s three-layer structure.

What is this system, who does it serve, and what quality attributes constrain its design? At L1 (Summary), C4 Context diagrams and arc42 quality trees frame the answer. C4 provides the system boundary. arc42 provides the constraint envelope. Together they define the problem space without overwhelming detail.

All three methodologies converge at L2 (Analysis), but from different directions. C4 Container and Component diagrams decompose the system into service boundaries and module responsibilities. ADRs attach to those components to explain why they are structured the way they are. arc42 sections layer in cross-cutting concerns: performance targets, security requirements, deployment topology. An agent at this depth answers: what are the pieces, why are they arranged this way, and what constraints shaped that arrangement?

At implementation depth, L3 (Dossiers), the picture sharpens to code level. C4 Code diagrams give class-and-interface detail. Implementation-level ADRs capture protocol choices and library selections. arc42 risk and deployment sections enumerate real-world constraints like budget and timeline. An agent here is doing detailed design review or code generation within bounded scope.

What makes this framework work for agents is that each dimension is independently consumable. An agent that needs only the structural zoom reads the C4 layers without touching a single ADR. An agent evaluating a design decision jumps straight to the ADR chain without re-reading the C4 diagrams. The dimensions are not interleaved; they are parallel, each navigable on its own axis.

What C4 Alone Misses#

C4 is the cleanest structural fit. Its four-level hierarchy maps to the three pyramid layers with almost no translation. But C4 alone is insufficient for agent consumption because it is fundamentally a visual notation. A C4 diagram communicates structure to a human who already understands the domain. It does not communicate rationale. It does not enumerate constraints. It does not document what was rejected or why.

To be fair, C4 isn’t blind to these concerns. Some practitioners use supplemental diagrams or annotations to capture decisions and constraints alongside the structural views. But the model itself has no native notation for rationale or constraints, and that gap matters enormously when the primary consumer is an agent rather than a human. For an agent, the structure is necessary but not sufficient.

ADRs supply the missing temporal dimension: decisions over time. Without ADRs, the agent sees a snapshot of the structure but cannot reconstruct the path that led to it. arc42 supplies the missing contextual dimension: constraints and quality attributes. Without arc42, the agent sees the solution but not the boundaries that define what constitutes a valid solution within it.

This is why the most complete answer is not a single methodology but a selective hybrid:

C4 structures the vertical axis, ADRs supply the temporal axis, arc42 defines the contextual envelope. Every methodology maps to a specific pyramid depth.

The artifact pyramid is the abstraction that makes the hybrid coherent without ceremony. It does not replace C4, ADRs, or arc42. It provides a container that respects what each methodology does best.

And this is what the Technical Architect profile carries into the Clanker pipeline: not a single methodology, but the judgment to select and combine them based on what is needed at each level of disclosure.

What This Means for the Clanker Pipeline#

In Part 1, I introduced the Technical Architect profile. Its SOUL.md says “document decisions as ADRs.” It carries a systems-architecture methodology skill with references for architecture patterns, ADR templates, and failure mode analysis. It traces its lineage directly to the methodologies described above.

This is not decoration. When the Technical Architect produces an artifact pyramid, it is participating in a 30-year tradition of structuring complex knowledge for selective consumption. The 4+1 model partitioned by stakeholder. The C4 model partitioned by abstraction level. arc42 partitioned by depth mode. The artifact pyramid partitions by all three: audience, depth, and lifecycle phase, in a single unified structure.

The architects who designed the 4+1 model and C4 and arc42 were doing progressive disclosure decades before anyone needed to fit a system design into an LLM context window. They just had a different name for it.

But here is the question I keep coming back to: if six independent communities converged on the same principle across thirty years without ever naming it, how many other fundamental principles are hiding in plain sight in our existing disciplines? How many patterns have we already solved that we just haven’t recognized as solutions because we described them in domain-specific language?

The artifact pyramid is not the answer. It is a name for something that was already working. The real discovery is that progressive disclosure is a property of how complex knowledge must be structured to be consumable. Architecture discovered it through stakeholder concerns. HCI discovered it through cognitive load. AI discovered it through context windows. Same principle, three lineages, one underlying constraint.

The full research behind this article is available as an artifact pyramid at /private/tmp/architect-documentation-research/, and as vault notes at 2 - Molecules/Intellectual Lineage of the Artifact Pyramid — Progressive Disclosure in Architecture Documentation.md with linked atoms covering each methodology individually. Source dossiers include Kruchten’s 1995 IEEE paper, the IEEE 1471 standard, the arc42 documentation site, Nygard’s 2011 ADR post, the C4 Model’s canonical sources, and the SEI’s Views and Beyond methodology.

So what do we build next? What other principles are we standing on without recognizing them? If this pattern of convergent evolution resonates with you, I would love to hear what other unrecognized principles you have found hiding in your own discipline.