5.5 KiB
Writing reports
Reports are YAML files stored under reports/. The filename determines the PDF
filename, while the YAML determines its content.
Top-level fields
| Field | Purpose | Required |
|---|---|---|
title |
Main report heading | Recommended |
id |
Report or ticket identifier | No |
organization |
Name displayed in the header | No |
subtitle |
Context below the title | No |
report_type |
Report purpose: technical or briefing |
Recommended |
theme |
Visual theme: default, cic, or eridani |
No; defaults to default |
status |
Overall workflow state | No |
severity |
Overall urgency | No |
metadata |
Key/value facts; must contain Date and Author |
Yes |
summary |
Executive summary callout | No |
timeline |
Chronological event table | No |
findings |
Evidence and assessments | No |
sections |
Free-form structured content | No |
actions_title |
Custom heading for the action plan | No |
actions |
Ordered work items and commands | No |
closing |
Current state or handoff point | No |
Missing optional fields are simply omitted from the PDF. Compilation fails when
the required metadata.Date or metadata.Author value is missing or empty and
prints the YAML needed to fix it.
Theme
Select one of the built-in visual themes at the top level:
theme: cic
default— neutral, understated corporate styling.cic— a sharper corporate space-operations/cyberpunk palette.eridani— a rugged, grass-and-earth palette.
The default is used when theme is omitted. An unknown name stops compilation
and lists the available themes. See Advanced setup
to customize or add themes.
Report types
Classify reports by their purpose, not merely whether they are internal or external:
| Type | Use it for | Typical content |
|---|---|---|
technical |
Investigation, engineering review, and shift handoff | Detailed evidence, commands, timelines, hypotheses, and operational precautions |
briefing |
Sharing verified findings with customers, managers, or other stakeholders | Concise impact, confirmed findings, decisions, ownership, and next steps |
report_type: technical
A technical report may still be shared when appropriate, and a briefing may be
internal. The distinction describes depth and purpose rather than access
control. The renderer displays Technical report or Stakeholder briefing as
a badge near the title.
Avoid putting secrets, credentials, personal data, or unnecessarily sensitive infrastructure details in either type. Classification does not provide security or redact content.
Status and severity
Typical workflow states are open, pending, confirmed, and resolved.
Typical severity values are info, medium, high, and critical.
The renderer also recognizes warning, ok, and success when choosing badge
and callout colors. Values are case-insensitive, but lowercase keeps YAML files
consistent.
Metadata
Metadata accepts arbitrary labels and values:
metadata:
Date: "2026-09-05"
Author: "Your Name"
Device: "DESKTOP-EXAMPLE"
Owner: "Operations"
Ticket: "INC-1234"
Quote dates and identifier-like values so YAML does not reinterpret them.
Date and Author are required with exactly this capitalization.
Timeline and findings
timeline:
- time: "09:15"
event: "Alert received"
notes: "Monitoring detected repeated storage timeouts."
findings:
- title: "Storage controller timeout"
severity: high
status: confirmed
evidence: >
The system log contains three controller resets within ten minutes.
assessment: >
The storage path is the leading cause and needs focused testing.
Use evidence for observations and assessment for interpretation. Keeping
them separate makes technical conclusions easier to review.
Free-form sections
Each item in sections has a title and a list of content blocks:
sections:
- title: "Investigation notes"
content:
- type: text
text: "A short paragraph."
- type: bullets
items:
- "First observation"
- "Second observation"
- type: steps
items:
- "Collect logs"
- "Reproduce the failure"
- type: callout
title: "Caution"
kind: warning
text: "Back up important data before destructive testing."
- type: code
text: "journalctl --since '30 minutes ago'"
- type: subsection
title: "Nested detail"
content:
- type: text
text: "Subsections can contain the same block types."
Supported block types are text, bullets, steps, callout, code, and
subsection. Unknown types render a warning instead of being silently discarded.
Actions
actions_title: "Next steps"
actions:
- title: "Collect system logs"
status: pending
text: "Export the relevant events and attach them to the ticket."
commands:
- "journalctl --since today > system.log"
- "dmesg > kernel.log"
commands is a list, so an action can contain zero, one, or several commands.
Authoring tips
- Use
>for prose that should wrap into one paragraph. - Quote Windows paths and values containing YAML punctuation.
- Keep evidence factual and put conclusions in
assessment. - Use metadata for short facts, not long explanations.
- Render after editing to catch malformed YAML and layout problems early.
For complete files, continue to Examples and boilerplate.