The shared context is a counter, not a trunk

When a step ends and the next one starts, what travels between them? Two opposite sins:

1. Passing everything always. The context grows step by step. Raw text, intermediates, metadata, debug logs. By step 6, the prompt has 8K tokens of junk and the cost tripled.
2. Passing too little. Step N needs something step N-1 already discarded. You start doing round-trips to the database, or worse, the model hallucinates because it lacks context.

The rule: each step receives the minimum it needs to do its job well. No more, no less.

What to pass (typically)

• Relevant output from the previous step. If extract returned fields, the next step receives fields. Not the raw text it came from, unless it needs it.
• Shared metadata. Category, severity, trace_id. small values almost every step uses.
• References, not payloads. If you need the full document, pass a document_id, not the document. The step that needs it fetches with a tool.

What NOT to pass

• Secrets. API keys, tokens, credentials. Never via context. Runtime-side access, not in the prompt.
• Embeddings or binary blobs. They're heavy and the model doesn't process them.
• Raw text if you already extracted the relevant bits. Pass it only if the next step REALLY reads it. If it just carries it "just in case", you're drowning it in dead tokens.
• Intermediate debug steps. Traces live in the log, not in the model's context.

An analogy

Think of shared context as the kitchen counter. You have what you're using now, not the whole pantry. If you work with ALL the pantry open on the counter, you can't find the knife when you need it. The model is the same: with too much context it loses sight of what matters.

The right way to declare it

In the chain YAML, explicitly declare what enters each step. Not "everything in the context", but "these keys, from these steps":

- id: recommend
  input:
    category: from chain.steps.classify.output.category
    severity: from chain.steps.severity.output.score
    fields: from chain.steps.extract.output.fields
  # NOT: 'the whole context'

Declarative, auditable, debuggable. If a step receives something, it's written; if it doesn't, that's written too.

Your exercise

On the right, four transitions in your chain. For each one, drag the piece that describes the correct minimum that should be in the context. One of the pieces is never passed. that one goes in the "never" slot.