Plain Text Response

why an agent pipeline passes files, not prompts

The Pipeline

make-a-deck turns a topic into a fact-checked deck

It is a real Attractor DOT-graph pipeline authored by Sam Schillace, built in three phases all committed on 2026-07-16.

A multi-stage agent chain is the thing worth caring about here — so first, is it real?

It Runs

This is running code, not a diagram

The graph has 5 LLM stages plus tool and gate nodes — 10 functional nodes excluding Start and Done — and a live session executed it on this very topic.

Because it runs, the failure it exposes is real. So what was the first stage promised to do?

5
LLM stages: research, research_factcheck, spine, render, deck_factcheck
10
functional nodes (excluding Start/Done)
opus‑4‑8
claude-opus-4-8 via Anthropic, session 1926bbc7…
The Contract

The research node is told to emit a strict JSON schema

The first stage — the research node — must write a strict JSON schema to research.json for every downstream specialist to consume.

That is the contract the whole chain leans on. Now watch what the repo's own notes say happened to it.

# research node prompt, make-a-deck.dot (line 95) { title, topic, verified_metrics: [ { claim, value, source_command, evidence } ], timeline, contributors, feature_status, core_story, unverified_notes }
The Break

The repo's own notes caught it: LLM nodes return prose, their context_updates come back None, and research, spine, and render all land as “Plain text response.”

The schema was asked for — but never reliably delivered. Recorded in factcheck_gate.sh (lines 6–8) and the make-a-deck.dot header (lines 29–32).

Why It Broke

Only tool nodes reliably write context

The schema an LLM was told to emit never dependably reached the next stage: report_outcome and context_updates from box (LLM) nodes are not captured.

In-context schema enforcement between LLM nodes can't be trusted. So Phase 3 changed the seam.

The Pivot

Phase 3 stopped trusting the prompt and started trusting the disk

Instead of relying on in-context schema, each stage writes its artifact to a fixed path and the next stage reads it back.

A structurally different hand-off — here is what actually moves between the stages.

The Fix

The file-based hand-off: write to disk, read it back

Each stage writes its artifact to a fixed path and the next stage reads it. Both fact-check gates run isolated via fidelity=truncate, re-deriving facts from those files.

Files, not context, is the reliable seam — a gate can't rationalize a claim it never made.

The Pattern

Between agent stages, pass verifiable files, not prompts

Stop trusting in-context schema enforcement between LLM nodes. The structural pattern is enforced by narrative_lint.py.

And the guardrail is checkable — the linter is backed by 21 passing tests.

21
test functions in test_narrative_lint.py
21/21
pass under pytest (“21 passed in 0.02s”)
Sources

Research Methodology

Data as of: 2026-07-21 (latest commit c38845f, “tool evolution”)

Feature status: make-a-deck built through Phase 3 (f74c70b); per HANDOFF.md not yet verified end-to-end.

Repository: ramparte/amplifier-stories — pipelines/make-a-deck.dot (author: Sam Schillace)

Research performed:

Gaps / flagged as author framing (not in the repo): a “Formatter” 7th stage (grep -ci 'formatter' = 0), “6 layers / 150 of 393 prompt lines” (render prompt has 8 numbered requirements; make-a-deck.dot is 205 lines), and “4 runs / 3 topics” (only one run.log found).

Primary contributors: Sam Schillace (all make-a-deck.dot commits); Michael J. Jabbour (story-researcher agent, a5ada42); Chris Park (researcher case study, cfdef0d).

More Amplifier Stories