| name | preview-report-template-writer |
| description | Generate the structured preview-report Markdown that glb-web-handoff and non-blender-user-response-writer consume after a render or export run. |
preview-report-template-writer
Purpose
Standardize how a preview / render / export run's evidence is summarized so that downstream skills (handoff, final response writer) consume a known schema instead of re-parsing free-form text.
Quick start
- pick the report kind (preview-only / render-only / export-only / full)
- fill the schema with measured values + truth labels
- attach evidence paths verbatim
- mark fields not measured as
Not Run
When to use
- after
render-export-evidence produces measurements
- before
glb-web-handoff is composed
- before
non-blender-user-response-writer writes the final summary
When not to use
- planning-only flows with no runtime
- raw debug logs (use
blender-troubleshooting instead)
Trigger phrases
- "summarize the render"
- "write up the export evidence"
- "what's the preview status"
Prerequisites / readiness
- runtime evidence (or explicit absence) is known
- output paths are known
- validation notes are written or marked missing
Input schema
Required inputs
| Input | Why it is required |
|---|
| Report kind | Determines which sections appear |
| Output paths | Anchors all artifact rows |
| Validation notes per artifact | Determines truth label |
Optional inputs
| Input | Use |
|---|
| Tool / runtime path used (Path 1/2/CLI) | Records provenance |
| Tool versions | Helps reproduce |
| Operator name | Useful for multi-operator repos |
Assumptions to confirm
- Output paths are real on the machine the report was generated; consumers should not assume they exist on other machines without copying artifacts.
- Truth labels (
Not Run, Attempted, Produced, Verified, Failed) match laws/evidence-before-done.md exactly.
Output schema
Primary output
A Markdown file (or block) following the canonical preview-report schema (see references/report-schema.md).
Secondary output
- a top-line truth status (
Pass / Warn / Fail)
- pointers to next skills (
glb-web-handoff, non-blender-user-response-writer)
Evidence / caveat output
Runtime status: Not Run | Attempted | Produced | Verified | Failed | Blocked / Not Run
Artifact status: Not Run | Not Produced | Produced | Verified | Failed
Evidence used: <links, paths, logs, or "none">
Limitations: <known gaps>
Required laws
../../laws/evidence-before-done.md../../laws/non-blender-user-language.md../../laws/no-arbitrary-python-interface.md../../laws/official-runtime-only.md
Official runtime boundary
This skill is documentation. It does not run Blender, render, or export. It only formalizes how an existing run's evidence is recorded. If the run did not happen, the report has every artifact at Not Run / Not Produced.
For runtime path attribution, follow ../../docs/runtime-stack-strategy.md (Path 1 / Path 2 / CLI fallback) — record the path explicitly per row.
Operating procedure
- Determine report kind based on what was attempted.
- Read the canonical schema (see references).
- Fill artifact rows with paths + sizes + truth labels.
- Fill validation rows with the checks performed.
- Note the runtime path used (Path 1 host a / Path 1 host b / Path 2 / CLI).
- Note tool versions if available.
- Compute top-line status from the rows.
- Hand off to glb-web-handoff (web) or non-blender-user-response-writer (final).
Decision tree
Render attempted but file missing?
→ Artifact: Failed
Render produced but no validation?
→ Artifact: Produced (not Verified)
Render produced and validated?
→ Artifact: Verified
Path 1 + Path 2 mixed in one run?
→ Forbidden by single-bridge constraint; mark Failed and explain
Playbooks
Playbook A: Preview-only report
- One section: preview screenshot path + dimensions + truth label.
- Used for early scene review before render.
Playbook B: Render-only report
- Render output paths + resolution + frame range + render time + sample count + engine.
- Used after
render-export-evidence capture.
Playbook C: Export-only report
- GLB output path + size + Draco status + animation channel count + texture count.
- Used after a GLB export step without a fresh render.
Playbook D: Full report (preview + render + export)
- All three sections.
- Used at the end of a complete recipe run.
Mode handling
Text-only mode
All artifact rows are Not Run / Not Produced. Report is a planning placeholder.
Runtime-ready mode
Real measured values. Truth labels honest per evidence-before-done.
Blocked runtime mode
Report explicitly notes the blocker; remaining rows stay Not Run.
Validation checklist
Pass / Warn / Fail rubric
| Verdict | Criteria |
|---|
| Pass | All applicable rows filled with consistent truth labels; runtime path recorded; handoff named. |
| Warn | Rows filled but tool versions missing, or validation notes thin. |
| Fail | Truth label upgraded beyond evidence (Verified without validation), or path not recorded, or rows fabricated. |
Failure handling
- If artifact path is unknown → row is
Not Produced with a note.
- If validation note is thin → keep label at
Produced, not Verified.
- If runtime path is unclear → mark
unknown and let runtime-bridge-conflict-resolver triage.
Troubleshooting
| Problem | Response |
|---|
| Asked to write a "summary" without measurements | Output a placeholder report with all Not Run rows; do not fabricate. |
Operator pushes for a Verified label without validation | Refuse upgrade; explain which validation step is missing. |
| Multi-path attempt | Record each path's rows separately; do not merge into one ambiguous total. |
Best practices
- Match the canonical schema verbatim; consumers parse it.
- Keep truth labels strictly per
evidence-before-done.
- Always anchor a row in a path (even if the path is
<missing>).
- Use ISO date in the report filename (
preview-report-YYYY-MM-DD.md).
Good examples
- "Render:
out/render-2026-05-09.png, 1920×1080, Cycles 128 samples, 23s, Path 1 host a, Verified by reference image diff < 2%."
Bad examples
- "Render done." — no path, no label.
- "Verified GLB." — no validation evidence.
User-facing response template
# Preview report (kind: <preview / render / export / full>)
Date: <YYYY-MM-DD>
Operator: <name or unknown>
Runtime path: <Path 1 host a / Path 1 host b / Path 2 / CLI fallback>
Tool versions: <blender X / addon Y / mcp host Z>
## Artifacts
- <kind>: <path> | <metric: e.g. resolution / size> | truth: <label> | validation: <notes>
- ...
## Validation
- <check>: <pass/fail/skip> | <evidence>
## Top-line
Status: Pass / Warn / Fail
Next: glb-web-handoff / non-blender-user-response-writer
Limitations: <gaps>
Anti-patterns
- Free-form prose summary that downstream skills cannot parse.
- Upgrading truth labels.
- Mixing artifact paths into a single comma-separated cell.
- Omitting the runtime path.
Cross-skill handoff
- Render/export evidence input →
../render-export-evidence/SKILL.md
- Web handoff →
../glb-web-handoff/SKILL.md
- Final response →
../non-blender-user-response-writer/SKILL.md
- Pre-handoff verification →
../pre-handoff-verification/SKILL.md
Non-goals
- Run Blender.
- Render or export.
- Parse log files (out of scope; consume measurement output of
render-export-evidence).
- Promote a label without evidence.
References
references/report-schema.mdreferences/truth-label-rules.mdreferences/handoff-recipients.md../../laws/evidence-before-done.md../../docs/skill-system.md
