Artifact Pyramids

Artifact Pyramids for Agentic AI Research

Progressive disclosure governs how we feed agents context: metadata at startup, instructions on activation, resources on demand. The Artifact Pyramid applies the same principle to what agents produce. Three layers of increasing depth, each independently consumable, each linking down to the next.

Loading Guidance

When producing an artifact pyramid, load these references as a required set (not piecemeal):

These four define complementary aspects of the spec that the others assume. Loading only a subset risks violating content contracts (e.g., putting findings in 00-index) or skipping required navigation affordances. Load the full set before writing any pyramid files.

The reference table below describes when to load each file; the four above are always required for pyramid production. The remaining references (framework, worked example, canonical article, intellectual lineage, provenance, composite synthesis) are supplementary — load when the task calls for conceptual depth or a worked pattern.

The Pyramid

      ┌──────────────┐
      │  L1 SUMMARY  │  One file: research question, key findings,
      │    🎯        │  most important implications. Links to L2 files.
      └──────┬───────┘
      ┌──────┴───────┐
      │  L2 ANALYSIS │  Per-dimension files: market, competitive,
      │  COLLECTION  │  technical feasibility, risk. Self-contained,
      │   🧩        │  each links to L3 dossiers.
      └──────┬───────┘
      ┌──────┴───────┐
      │  L3 DOSSIERS │  Source excerpts, raw data tables, interview
      │    📦        │  transcripts, methodology notes. Reference
      └──────────────┘  library, pulled on demand.

The pyramid is consumed top-down but produced via recursive gap analysis: start with the summary, embed links to analysis files, write analysis files that link to dossiers, and evaluate after each round whether gaps remain.

Layer numbering is top-down — L1 is the most distilled layer (the entry point), L3 is the most detailed (pulled on demand). This mirrors the Agent Skills input model: metadata (L1) → instructions (L2) → resources (L3).

The Navigation Mechanism

Every file at every layer carries, at the bottom, an explicit SOURCES section with absolute path references and descriptions:

SOURCES (LAYER 2 NAVIGATION)
research/analysis/market-position.md
 -> Competitor mapping and market share analysis supporting Section 2
research/analysis/technical-feasibility.md
 -> Architecture evaluation supporting Section 3
research/dossiers/competitor-profiles.md
 -> Raw competitor data dossiers

These aren't footnotes. They are navigation affordances for agent consumers. Each description answers the question the consuming agent asks before loading: what will I find if I go deeper?

Reference Files

Scripts

Templates

Quick Start

# Scaffold a new research project with all three layer directories
mkdir -p my-project/{01-summary,02-analysis,03-dossiers}
cp assets/pyramid-template.md ./my-project/00-index.md

# Check structural coverage of an existing project
scripts/pyramid-status.sh ./my-project

# Extract candidate atoms from source text
scripts/extract-atoms.py ./my-project/03-dossiers/source-1.txt

Project Structure

my-project/
├── 00-index.md              # Project scaffold (from template)
├── 01-summary/              # L1: one file — key findings, implications, links to L2
├── 02-analysis/             # L2: per-dimension files (market, competitive, technical)
├── 03-dossiers/             # L3: source excerpts, transcripts, raw data, methodology
└── artifact-inventory.md    # Cross-layer tracking (from template)

The numbered prefixes mirror the pyramid's top-to-bottom orientation: 01 is most consumed, 03 is pulled on demand.

Key Principles

1. Progressive disclosure is symmetric. The same three-tier model governs what agents consume (metadata → instructions → resources) and what they produce (summary → analysis → dossiers).
2. Each layer is independently consumable. A product-manager agent reads only the L1 summary. A data-scientist agent reads a single L2 analysis file. A verifier reads L3 dossiers.
3. Navigation is explicit. Every file carries a SOURCES section with absolute paths and descriptions — not footnotes, but agent navigation affordances answering what will I find if I go deeper?
4. Depth varies by mission complexity. A simple brief may produce only L1 + 2 analysis files. A competitive landscape may need all three layers with multiple files per layer.
5. Quality gates are directional. Material moves from L3 (sources) toward L1 (summary) only when it meets the gate for the target layer.
6. 03-dossiers/ is flat — no subdirectories. The dossier layer is a flat reference library. Organize with epoch-prefixed or category-prefixed filenames (epoch-1-validation-edit-3.json), not nested directories. Subdirectories inside 03-dossiers/ violate the flat-file contract and break the SOURCES navigation path.
7. Root-level files are amended; lower-level files are fixed. In multi-epoch or multi-phase systems, 00-index.md, 01-summary/findings.md, and 02-analysis/ trajectory files grow as new data arrives. They are rewritten to reflect the current state. Files in 03-dossiers/ and per-category analysis files below 02-analysis/ are created once and never modified — they represent a fixed point in time.

Validation Script Pitfall

scripts/pyramid-status.sh currently discovers layers by matching file names, not canonical directory names. A compliant tree such as 01-summary/findings.md, 02-analysis/topic.md, and 03-dossiers/source.md can therefore be falsely reported as missing L1/L2 when the nested file names do not themselves match the script's layer patterns. It also reports missing YAML frontmatter as a quality issue even though frontmatter is not required by the layer contracts above. Treat this script as a heuristic only; verify canonical directories, one L1 file, per-dimension L2 files, flat L3 files, final ## SOURCES sections, and link resolution independently.

When NOT to use

• Single-turn Q&A with no research artifacts to preserve
• Tasks producing only ephemeral output (one-off calculations, quick lookups)
• Workflows where the source material IS the final output (no synthesis needed)

Portability

This skill is intentionally host-neutral. Use your agent's normal mechanisms to load the references, templates, and scripts listed here. Do not assume a particular profile system, task orchestrator, memory service, or response-handoff format.