Chapter 12

The lessons pipeline

Reflects Holonograph v0.23.0 · ~10 min read

A system's interactions contain the information that should make it better. This chapter is how Holonograph turns that information into shipped improvements: captured human overrides cluster, the drafter proposes concrete corrective artifacts for each cluster, a named human approves or rejects at the gate, and only then does anything get published. Nothing bypasses the gate.

What it is

A five-step pipeline, one endpoint per step:

1. Override: a human corrects the system's output. Recorded as first-class ground truth: what the system produced next to what good looks like.
2. Cluster: similar overrides group together, so one fix can address a pattern instead of a single instance.
3. Draft: the drafter proposes a concrete corrective artifact for a cluster. Four kinds: skill, lesson, fixture, code-change-recommendation.
4. Approve or reject: a named approver reads the draft, edits or rejects. This is the gate.
5. Publish: an approved draft becomes substrate. Versioned, captured, and attributable in future readings like any other change.

Why it matters

Feedback in most agentic systems is either noted-and-forgotten or wired into a slow fine-tuning loop. Neither is a good fit for the operator running a real product on a real timeline. The lessons pipeline gives that operator a third path: capture the correction, cluster the pattern, ship a concrete artifact through a named gate. The artifact (a new skill, a lesson, a fixture, a code change) is the smallest unit of "the system got better," and every one of them is attributable in future drift readings.

How to use it

1. Record an override

When a human corrects the system, capture both sides:

POST /hil/override
x-holonograph-run-mode: production
Content-Type: application/json

{
  "agentId": "billing-triage",
  "surfaceId": "classify-intent",
  "correlationId": "corr_01H...",
  "originalOutput": { /* what the system produced */ },
  "correctedOutput": { /* what the human sent instead */ },
  "rationale": "Refund lookup wasn't invoked; agent guessed.",
  "tags": ["fix_tier=tool-input-schema"]
}

Response: an eventId. The override is now in the substrate, tagged and correlated with the original call.

2. Cluster overrides over a window

Run the clustering endpoint to group similar overrides, usually on a schedule (nightly), sometimes on-demand when an operator wants to see what's been building up.

POST /lessons/cluster
x-holonograph-run-mode: production
Content-Type: application/json

{
  "surfaceId": "classify-intent",
  "since": "2026-07-01T00:00:00Z",
  "until": "2026-07-05T00:00:00Z"
}

Response: clusters[] plus a total eventCount. Each cluster carries its member override ids and a summary shape the drafter can consume.

3. Draft a corrective artifact

Ask the drafter to propose an artifact for a cluster. Pick the kind that fits:

POST /lessons/draft
x-holonograph-run-mode: production
Content-Type: application/json

{
  "kind": "fixture",
  "cluster": { /* cluster payload from the previous step */ },
  "parentSurfaceId": "classify-intent",
  "seedEventId": "evt_01H..."
}

For fixture drafts, provide either a seedEventId (a real event to base the fixture on) or a seedRawRequest (a hand-authored request shape). Optionally supply a parentFixtureId if this fixture should stack on an existing one.

Response: a draft object, an optional classification label the drafter applied, and an enqueued flag reflecting whether the draft was queued for the gate.

4. Approve or reject at the gate

Approve:

POST /hil/approve
Content-Type: application/json

{
  "draftId": "draft_01H...",
  "approverId": "brian",
  "comment": "Correction verified against the surface's rules. Approving."
}

Reject (a comment is required; the record of why matters):

POST /hil/reject
Content-Type: application/json

{
  "draftId": "draft_01H...",
  "approverId": "brian",
  "comment": "This one's not a pattern — the customer was testing us. Discarding."
}

Both endpoints return the current status and a history[] of the actions taken on this draft so far.

5. Publish

Once approved, publish the draft to make it live. Provide any existing lessons the publisher should consider superseding; the publisher will merge/replace/link as appropriate.

POST /lessons/publish
Content-Type: application/json

{
  "draftId": "draft_01H...",
  "candidateExistingLessonIds": ["lesson_01G..."]
}

Response: a publish report naming the new artifact id, any superseded artifacts, and the substrate event the publish itself produced.

Re-run a published fixture

Once a fixture is live, you can re-run it any time against its parent surface:

POST /fixtures/rerun
Content-Type: application/json

{ "fixtureId": "fx_01H..." }

Response includes the actual result the run produced and the expected[] assertions the fixture carries. The diff between the two is your regression signal.

Reading the output

Published artifacts become substrate. That means they show up as their own events, they get versioned, and, crucially, future drift readings can point at "this artifact was published on Tuesday" as a candidate explanation for a movement in the numbers.

The pipeline is recursive by construction. The drafter's own model call passes through the lens, so the act of proposing a correction is itself observed. Getting better is a measured event.

Reference

Endpoints

POST /hil/override: request

POST /lessons/draft: request