How to Debug ZeroContentPipeline Proofs
A practical workflow for aligning claims, Mermaid diagrams, proof captures, the manifest, and audit checks before publish.
Last updated: 2026-04-05 · Tested against the current ZeroContentPipeline v0.1.0 workspace build
In this run, I checked one thing first: do the draft, the manifest, and the audit name the same state? They did not line up on the first pass. I found placeholder proof entries in visual-manifest.json, and the audit report flagged a Mermaid block whose file-path comment was not in the exact format the validator expected.
I also had to compare the draft and the asset plan side by side, because the screenshot itself looked fine while the metadata still said reviewed: false.
I tested the draft against the local validator after that, because the block-comment syntax was the part most likely to drift again.
Proof captures are evidence, not decoration. The draft makes the claim. The visual backs it. The manifest explains it. The audit checks whether the package still tells one true story.
The structure matters because generative systems prefer clean attribution and concrete claims. The Princeton GEO paper is a useful reminder here: citations and specific details make a page easier to quote and reuse (paper). For the mechanics of the capture itself, Playwright documents both full-page and element screenshots (screenshots), and Mermaid keeps the workflow shape readable (flowchart docs).
%% File: content/20260405-165339-how-to-debug-zerocontentpipeline-with-proof-screenshots/visuals/diagrams/mermaid/zcp-debug-proof-flow-01.mmd
flowchart LR
A["brief.md sets the claim"] --> B["draft.md states the claim"]
B --> C["proof capture shows the state"]
C --> D["visual-manifest.json describes the asset"]
D --> E["pipeline audit checks the package"]
E --> F["publish only when all five agree"]What problem do proof screenshots solve in this workflow?
Proof screenshots settle a simple argument: did the run actually reach the state the article describes? If the post claims an audit passed, an asset was reviewed, or a step produced a visible result, the capture is the fastest way to show the receipt.
What's a proof screenshot? A truthful, sanitized image of the exact state that supports one sentence in the draft. Not the whole screen. Not a nearby screen. The exact state doing the work.
That distinction matters because screenshots and diagrams do different jobs. Mermaid explains the path. A screenshot proves a rendered state. If the post needs both, use both.
How do you debug the run?
-
Start with the sentence that needs proof. Open
brief.mdanddraft.mdtogether. Find the line that would fall apart first if a reviewer asked for the receipt. -
Choose one decisive state. Pick the smallest visible moment that settles the claim. A reviewed asset entry, a generated result, or an audit outcome is usually enough.
-
Sketch the path before you capture it. A Mermaid block forces the workflow into the open. If the flow feels muddy on paper, the capture will usually be muddy too.
-
Capture the narrowest honest frame. Full-page screenshots look thorough, but they bury the point. Element screenshots keep the evidence tight and readable, which is exactly what the Playwright docs recommend for focused capture work (screenshots).
-
Write the manifest like a reviewer will read it. Alt text, caption, source environment, and review state tell the next person what the asset proves and whether it is safe to publish.
-
Run the audit after the package lines up. If the audit disagrees with the article, trust the audit first. Walk back through the sentence, the capture, and the manifest until they say the same thing.
When should you use Mermaid, and when should you use a screenshot?
Use the lighter proof surface that answers the real question.
| If you need to show... | Use this | Why |
|---|---|---|
| The order of the workflow | Mermaid | It explains the path without interface noise |
| A real state the article depends on | Screenshot | It gives evidence instead of a sketch |
| One control, panel, or result | Element screenshot | It keeps the proof readable |
| A sensitive flow you cannot safely capture live | Mermaid | It avoids leaking extra context |
This run taught me one practical thing: the visual layer can look almost ready while the manifest still carries placeholders.
That is why I keep the proof asset, the draft sentence, and the manifest entry in the same review pass.
The clean capture is usually the one with a narrow job. If you need three zooms and a paragraph of explanation to make it land, the frame is too wide.
Common errors and gotchas (troubleshooting)
The first failure mode is drift. The draft promises a specific proof point, but the stored image shows a nearby step instead of the one that matters.
The second is over-capturing. Big screenshots feel safe, but they often make the reader hunt for the one visible state that matters. That weakens the proof and slows review.
The third is thin metadata. The image exists, but the caption is vague, the alt text says almost nothing, or the review state is unfinished. That is usually where publishing friction lives.
If the issue is still unclear, check the manifest first. In this workflow, reviewed: false or sanitized: false means the asset is not ready for publish, even if the image itself is technically accurate.
Frequently asked questions
- What does a proof screenshot need to show?
It needs to show the exact state that supports the sentence doing the real work in the draft. If the reader has to guess what they are meant to notice, the capture is too loose.
- What if the screenshot is real but still fails review?
Check the manifest entry before you blame the image. Weak alt text, a vague caption, or an unfinished review state can make a truthful capture fail the workflow.
- Can Mermaid replace screenshots completely?
No. Mermaid explains the route through the system. It does not prove that a particular run reached a particular state.
- Do I need both visuals for every post?
No. Use the lightest useful format. If the post is conceptual, a diagram may be enough. If the post makes a visible workflow claim, use a proof asset as well.
What should you do next?
Keep the claim narrow. Capture one honest proof state. Make the manifest carry the same story as the draft. Then let the audit be the grumpy reviewer in the room.
That approach is not flashy, but it holds up. If you want the broader publishing context, You don't need an AI agent is a good reset on keeping the workflow small, How Claude published directly to Labs via MCP shows the far end of the chain, and the AI Workflows zone holds the rest of the cluster.
The short version: one claim, one proof point, one tidy chain of evidence.