preview-report-template-writer

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

1. Determine report kind based on what was attempted.
2. Read the canonical schema (see references).
3. Fill artifact rows with paths + sizes + truth labels.
4. Fill validation rows with the checks performed.
5. Note the runtime path used (Path 1 host a / Path 1 host b / Path 2 / CLI).
6. Note tool versions if available.
7. Compute top-line status from the rows.
8. 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

• Report kind chosen
• Every artifact row has a path or Not Produced
• Every artifact row has a truth label
• Runtime path recorded
• Tool versions recorded or marked unknown
• Validation notes per artifact
• Top-line status matches the rows
• No truth label upgraded beyond evidence
• Handoff to next skill named

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.md
• references/truth-label-rules.md
• references/handoff-recipients.md
• ../../laws/evidence-before-done.md
• ../../docs/skill-system.md