artifact-pyramids

Files (24)

• LICENSE
• README.md
• SKILL.md
• artifact-inventory.md · assets/
• pyramid-template.md · assets/
• artifact-pyramid-framework.md · references/
• canonical-article.md · references/
• companion-session-summary.md · references/
• composite-pyramid-synthesis.md · references/
• delegation-context-template.md · references/
• flat-to-pyramid-migration.md · references/
• intellectual-lineage.md · references/
• methodology-to-pyramid-mapping.md · references/
• nested-pyramid-pattern.md · references/
• output-classification-framework.md · references/
• pipeline-stages.md · references/
• provenance-artifacts.md · references/
• quality-gates.md · references/
• skillopt-baseline-pyramid.md · references/
• skillopt-pipeline-integration.md · references/
• synthetic-example.md · references/
• extract-atoms.py · scripts/
• pyramid-status.sh · scripts/
• pyramid-status.sh.bak · scripts/

SKILL.md (first lines)

# 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):**

| Reference | File |
|-----------|------|
| Pipeline Stages — layer definitions, navigation format, production flow | `references/pipeline-stages.md` |
| Output Classification Framework — role-agnostic content contracts, 00-index/L1 boundary | `references/output-classification-framework.md` |
| Quality Gates — verification checklists per layer | `references/quality-gates.md` |
| Delegation Context Template — exact text for subagent output mandates | `references/delegation-context-template.md` |

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

| Reference | Load when | File |
|-----------|-----------|------|
| Framework & Symmetry | You need the full conceptual foundation — the asymmetry problem, multi-agent routing, DIKW relationship | `references/artifact-pyramid-framework.md` |
| Pipeline Stages | You're building or auditing a pyramid — detailed definitions per layer, navigation format, production flow | `references/pipeline-stages.md` |
| Quality Gates | You need to verify an artifact meets the standard for its layer | `references/quality-gates.md` |
| Worked Example | You want to see a complete synthetic walkthrough of all three layers | `references/synthetic-example.md` |
| Canonical Article | Read the published groktop.us piece — the Layer 3 artifact that defines the concept | `references/canonical-article.md` |
| Intellectual Lineage | How software architecture documentation (4+1 Views, C4, arc42, ADRs) independently discovered progressive disclosure under different names — and what the Artifact Pyramid generalizes beyond them | `references/intellectual-lineage.md` |
| Methodology-to-Pyramid Mapping | How specialist profiles map domain-specific methodologies into the universal pyramid structure, with dimension boundary rules | `references/methodology-to-pyramid-mapping.md` |
| Output Classification Framework | **Role-agnostic** — three questions any specialist can ask to map their outputs into the correct layer: who consumes it, how often, what question it answers. Includes per-layer content contracts to eliminate duplication between 00-index and L1 files. | `references/output-classification-framework.md` |
| Composite Pyramid Synthesis | How to merge multiple subagent pyramids into a root-level composite pyramid — orchestrator flow, SOURCES convention, worked example from jobs-finder pipeline | `references/composite-pyramid-synthesis.md` |
| Delegation Context Template | You're delegating research to subagents and need the exact text to include in context strings to ensure artifact-pyramid output | `references/delegation-context-template.md` |
| Flat-to-Pyramid Migration | You're converting existing flat JSON outputs to artifact-pyramid format — the pattern for L1/L2/L3 structure, 00-index rules, and downstream consumer fallback reads | `references/flat-to-pyramid-migration.md` |
| Nested Pyramid Pattern | You're designing a single system that produces multiple artifact streams over time (multi-phase, multi-epoch) — avoid scatter, nest epochs under a single root pyramid | `references/nested-pyramid-pattern.md` |

## Scripts

| Script | Load when | File |
|--------|-----------|------|
| pyramid-status | You want to audit an existing research directory for structural coverage | `scripts/pyramid-status.sh` |
| extract-atoms | You have raw source text and need candidate atomic claims | `scripts/extract-atoms.py` |

## Templates

| Template | Load when | File |
|----------|-----------|------|
| Project Scaffold | You're starting a new research project and need the index skeleton | `assets/pyramid-template.md` |
| Artifact Inventory | You need to track what exists at each layer across a project | `assets/artifact-inventory.md` |

## Quick Start

```bash
# 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.

From Sayskh/hermes-agent, MIT.

More from Sayskh/hermes-agent