Burnable Visual Briefs

Overview

Turn dense material into an adaptive visual-first, minimal-text, self-contained HTML brief. The brief is a disposable communication surface, never the authoritative evidence store. “Visual” means information is made faster to understand through deliberate spatial, typographic, relational, or measured encoding; it does not require a conventional graph or chart.

canonical evidence / source material
               ↓
      burnable visual brief
               ↓
  short chat caption + HTML attachment
               ↓
     seven-day cleanup review

This package is standalone: its bundled starting assets, selection reference, and Python standard-library validator require no companion skill, private workspace policy, or preconfigured cleanup service.

Trigger gate

Use when at least one condition holds:

• the user explicitly asks for a visual, graphic, map, diagram, dashboard, or burnable HTML report;
• a comparison, architecture, process, dependency, decision, risk boundary, or body of evidence would be clearer through deliberate visual structure than prose alone;
• a long unattended automation period has produced enough outcomes, changes, verification, remaining risks/decisions, or next-frontier updates that a chronological chat dump would impose high catch-up cost;
• the content would otherwise require a long, dense chat response that the user must study rather than answer immediately.

Do not use for:

• a simple fact, short answer, exact command, urgent alert, or routine status;
• source code or a diff that must be copied exactly;
• canonical research, investment, audit, or legal artifacts that require a durable domain-specific report contract;
• decoration without information gain.

For simple communication, answer directly in chat. A brief must reduce reading cost, not add another artifact by habit.

Artifact contract

Choose the operator's active project workspace and write final briefs under:

<active-workspace>/scratch/visual-briefs/
  <profile>/<YYYY-MM-DD>/<YYYYMMDDTHHMMSSZ>-<concise-slug>.html

<profile> is a non-sensitive grouping label; use default when profiles are not in use. Replace path placeholders with actual locations. <skill-package> in commands below means the directory containing this package's SKILL.md. No particular home directory or Hermes installation layout is assumed.

Rules:

• one standalone UTF-8 .html file with a responsive viewport;
• mode 0600 on POSIX systems; on Windows, use equivalent user-only access controls and verify them separately, since the validator does not check ACLs;
• inline CSS only; inline SVG and CSS shapes are allowed;
• no JavaScript, external stylesheets, web fonts, trackers, forms, iframes, embedded objects, or remotely loaded images/assets;
• ordinary https:// source hyperlinks are allowed, but nothing is fetched merely by opening the file;
• include hermes-artifact-kind metadata set to burnable-visual-brief, plus machine-readable hermes-created-at and hermes-expires-at UTC metadata;
• expiry defaults to seven days after creation; a shorter lifetime is allowed, but it must be after creation and no more than seven days later;
• include human-readable generated and expiry times in the footer;
• never include credentials, private tokens, hidden raw data, private filesystem paths, or unrelated personal information.

Choose a starting asset only after selecting the communication grammar:

• use assets/burnable-visual-brief-neutral.html for adaptive spatial, typographic, evidence-cluster, state, comparison, or catch-up compositions;
• use templates/burnable-visual-brief.html when a branching route plus nested authority/boundary map genuinely matches the information.

Both are starting assets, not mandatory layouts. Delete or reorder any region that does not improve the named reading outcome. Run scripts/validate_brief.py before delivery.

Communication contract

Visual usefulness before visual form

Before choosing any graphic, name the reader question it must answer. A visual element is justified only when it lets the reader understand structure, state, change, evidence, comparison, or required attention faster or more accurately than nearby text. If it cannot pass that test, omit it.

Choose one dominant visual grammar from the information topology. Examples are options, never a checklist:

Read references/visual-grammar-selection.md for the full selection procedure. A conventional diagram or chart is optional. Deliberate hierarchy, proximity, containment, alignment, annotation, emphasis, and whitespace can carry visual meaning when relationships or measured scale do not justify connectors or axes.

Use position, grouping, color, line, direction, and scale only when they encode meaning. Labels inside shapes must stay short. Avoid pseudo-graphics that are long prose inside boxes, decorative meters without measurements, rows of option cards that could have been bullets, and collections of graphics chosen to show design effort rather than improve comprehension.

Long-automation catch-up

When the trigger is a long unattended run, derive the brief from durable state, not message chronology. Optimize the reader's path to:

• the achieved or current outcome;
• material changes and why they matter;
• verification evidence;
• remaining decision, risk, or blocker requiring attention;
• the current frontier.

These are information goals, not mandatory panels. Merge, reorder, or omit them when the named reader question is answered more efficiently another way. The brief should replace or compress the long prose update, not duplicate it.

Minimal text

• Lead with one visual thesis.
• Prefer labels, numbers, short card text, and one-line caveats.
• Keep details behind compact evidence/source cards near the bottom.
• Preserve clarity when removing prose; do not compress away scope, uncertainty, material risks, or the requested action.
• Use real data only. Never invent metrics to make a chart look complete.

Chat delivery

Deliver the HTML attachment and keep the chat message to:

1. one-sentence conclusion;
2. at most three decision-relevant bullets when needed;
3. expiry or cleanup note.

Do not paste the report back into chat.

Durable-source boundary

A visual brief may summarize or point to canonical evidence, but it must not be the only copy of durable facts, approval records, source ledgers, recovery instructions, or project specifications. Keep those in their normal durable locations. Use non-sensitive artifact names when a link would expose a private path. The brief may expire without losing the underlying work.

If the HTML itself is the requested durable deliverable, use the applicable domain report workflow and store it under <active-workspace>/reports/ or the project's designated durable location, not this transient path.

Workflow

1. Name the primary reader question and the intended reading outcome: understand, compare, decide, monitor, or catch up.
2. Read the authoritative sources and separate durable evidence from temporary presentation.
3. Identify the information topology, then select the smallest dominant visual grammar that answers the reader question. Use at most two supporting patterns; they are optional, not a target.
4. State internally what each visual region lets the reader understand faster. Remove any region that fails that usefulness test.
5. Choose the neutral shell or specialized route template, then delete, reorder, or combine regions to match the actual information.
6. Fill every placeholder and add concise provenance, confidence, caveats, and the exact next action.
7. Set UTC creation/expiry metadata and permission 0600 where applicable.
8. Run the bundled standard-library validator, passing the chosen root explicitly when not invoking it from the active workspace:

python3 "<skill-package>/scripts/validate_brief.py" \
  --root "<active-workspace>/scratch/visual-briefs" \
  "/absolute/path/to/brief.html"

9. Open locally and inspect desktop, approximately 390px mobile width, and 200% zoom.
10. Check browser console errors and repair clipping, overlap, tiny text, body-level horizontal overflow, weak contrast, broken ARIA references, and focus-order problems. Confirm connectors and containment reflect actual semantics when used.
11. Deliver the file with the short communication contract above.

Portable validator interface

The validator needs Python 3.10 or newer and only the standard library. It is a read-only check of the supplied brief; it does not render, publish, or delete it.

• Positional path: HTML file to check.
• --root PATH: allowed final-artifact root; defaults to ./scratch/visual-briefs relative to the process's working directory.
• --template: check a starting asset while allowing placeholders and skipping final-artifact metadata, root-containment, and permission checks. Never use this mode as delivery validation.
• --self-test: run bundled checks in a temporary directory; no path required.
• Normal validation prints JSON with path, valid, and errors; it exits 0 on success and 1 on validation failure.
• Python callers retain validate(path, *, template=False, root=DEFAULT_ROOT) with path and root supplied as pathlib.Path objects.

The validator enforces structural, resource, anchor, metadata, lifetime, root, and POSIX-permission checks. It neither requires nor judges a particular visual grammar. It is not a comprehensive security or accessibility audit: manually review sensitive content, resource behavior, semantics, and rendering as well.

Seven-day lifecycle

Review individual HTML files beneath the chosen scratch/visual-briefs/ root at least daily, manually or through an operator-approved workspace hygiene process. Propose each file for cleanup when its declared expiry is reached, no later than seven days after creation, even if newer briefs exist beside it. The review remains read-only: the operator approves deletion separately. This package installs no scheduled job and performs no automatic cleanup.

Do not keep refreshing modification times to evade expiry. If a brief still matters, regenerate it from the durable sources with a new date and current facts.

Common pitfalls

1. HTML for everything. Use it only when visual communication materially improves comprehension.
2. Prose in cards. A wall of text with borders is not graphic communication.
3. False geometry. Connectors and containment must reflect actual semantics.
4. Decorative data. Charts require observed values, not invented metrics.
5. Remote assets. They add privacy, availability, and tracking risk.
6. Orphaned truth. Burnable HTML cannot be the sole evidence or approval record.
7. Silent expiry. Always show the expiry date in the artifact and delivery.
8. Unverified rendering. Validator success does not replace desktop/mobile visual inspection or accessibility review.
9. Report accumulation. Use the chosen transient root so each expired file can be identified independently during cleanup review.

Verification checklist

• Trigger gate passed; the brief reduces reading cost better than a short message or compact table.
• The primary reader question is named and one dominant communication grammar answers it; a conventional diagram/chart is present only if useful.
• Every information-bearing visual element makes structure, state, change, evidence, comparison, or attention faster or more accurate; ornamental or checklist-shaped regions were removed.
• Prose adds evidence, caveat, or action instead of repeating the visual.
• Text is concise without hiding scope, uncertainty, risk, or action.
• Sources and durable artifacts are linked or named without exposing private paths.
• One h1, logical headings, named regions, unique IDs, valid ARIA references, visible focus, meaningful link text, and DOM reading order pass.
• Status is not encoded by color alone; contrast is WCAG AA. SVGs have a title/desc; tables have a caption and scoped headers when used.
• No secret or unrelated private data is present.
• File is self-contained, script-free, and mode 0600 on POSIX; equivalent user-only access is verified separately on Windows.
• Creation and expiry metadata are valid, lifetime is no more than seven days, and generated/expiry times are visible in the footer.
• Standard-library validator passes in final-artifact mode with the correct root.
• Desktop, ~390px mobile, 200% zoom, overflow, keyboard, contrast, and console checks pass. Necessary pan regions are labeled and keyboard usable.
• Delivery is the attachment plus a short caption, not duplicated prose.