Reports as Deliverables

Two Classes of Report

Everything standalone the chief of staff writes into Efforts/reports/ is a report. Two classes, derived from the type: field and never edited after the fact:

The review surface shows deliverables prominently and de-emphasises reference artifacts with a one-line “why this is here”, so a curator’s raw digest never gets mistaken for a decision you owe.

The Contract Frontmatter

---
type: research-report        # drives classification forever after
title: <human title>
date: <YYYY-MM-DD>
ventures: [<slug>, …]
bead: <task id>              # the task that asked for it
src: <message id / inbox file>
---

Pick the type honestly at creation. A working audit filed as a report will surface in your face; a deliverable filed as a curator-report will hide.

A Table of Contents, Always

Every report opens with a table of contents linking to its sections, directly under the title — Markdown as anchor links, HTML as a <nav> with stable ids on every heading. Reports got long enough that navigation mattered, and the rule was made universal rather than judged per report: fewer than three sections may skip it; everything else carries one. It is authored with the report, not retrofitted.

Task References Are Live Handles

Every task mentioned in a report is a handle the review surface can open — never a bare ID in prose:

• Markdown: write the ID naturally; the renderer links any ID that actually exists in the task database (so a stray four-letter word is never a false hit).
• HTML: an explicit chip — <span class="bead" data-bead="<id>">…</span> — that the surface wires to the task modal. Standalone, the chip degrades to plain text.

Click the handle, get the full task and the disposition menu. A report is a surface, not a document.

HTML When It Leaves the Machine

Any report that reaches you as a file attachment is authored as standalone HTML: light styling embedded, renders fully with JavaScript disabled, metadata in HTML comments. The rule exists because two deliverables went out as raw Markdown attachments and opened on the phone as unstyled plain text. Markdown remains right for reports only read inside the review surface and for vault-internal working artifacts.

Presentation Decks

When the ask is “present this”, the deliverable is a CSS-only slide deck: sections with scroll-snap, sixteen-by-nine, fonts in container units so text scales with the slide, no JavaScript (the review surface’s frame never runs it). Full-screen in the surface is present mode. Two hard rules from the first deck: proximity snap, never mandatory — mandatory snap swallows trackpad gestures and the human experienced it as “I can’t scroll” — and never clip a slide; an overfull slide splits into two. If the deck will be shown to an outside party, task chips and system machinery stay off the slides and provenance goes in comments.

The Lifecycle

1. Create — trigger: “do a report on X” / “prep me for Y” / a cos-exec task. Type, format, frontmatter, TOC, handles.
2. Deliver — per spec: surface-only, file via the channel, or a message. The receipt names the exact path.
3. Review — you read it in the surface or on the phone; comments and task dispositions go through the surface’s intention files or direct task actions.
4. Disposition — each comment becomes an edit, a task, or an answer; the report file is never rewritten in place for a comment. A revised report is a new dated file that supersedes the old one.
5. Audit — reference-class artifacts stay findable but quiet.

Bundles

A report that needs assets — screenshots, generated images, an audio version — is a folder in Efforts/reports/, first-class in the surface, with an index.html or index.md as the entry. Folders were invisible to the surface once; a screenshot bundle exposed the gap and the fix was a decision record.

Why So Many Conventions for a “Document”

Because every convention here replaced a moment where a report was read and then nothing happened. A TOC gets it read; handles get it acted on; HTML gets it opened; the type keeps it from being mistaken for something else; the lifecycle makes the comment loop real. The report is where the system’s work becomes your decision — it is worth the rules.

#reports · #deliverables · #html · #conventions