Report types
Structures, evidence, and reusable starters for activity, feature, technical, audit, benchmark, decision, and investor reports.
On this page
Daily commit report
What shipped today, and what can the crew do now?
- Reporting window and scope
- Outcomes at a glance
- Changes by theme
- Risks and follow-up
- Linked commit log
A concise outcome summary, daily activity bars, and one diagram per material change.
Evidence: The exact UTC window, repository and branch, linked commit hashes, and verification. Commit totals describe activity, not productivity.
Destination: periodic/daily-commits/YYYY-MM-DD.mdx
A report answers one reader's question. Its type defines the order of the argument and the evidence it needs; its audience determines where it belongs. A product story, a capability record, and a subsystem explanation can cover the same subject, but each has a different purpose and should link to the others.
Audience and placement
| Audience | Collection | The reader's question |
|---|---|---|
| Crew, owner, customer | Product | What do I get? No code or package paths. |
| Evaluator, product manager, new engineer | Features | What does this capability do, and where is its implementation? |
| Working engineer | Systems, grouped by subsystem | How does this work, including its failure behavior? |
| Team and stakeholders | Activity, grouped by period | What shipped, what changed, and what comes next? |
| Reviewer and engineering owner | Dated audits | What was verified at this revision, and what remains uncertain? |
| Shareholder or prospective investor | Private investor draft | How is the company progressing, and where can I help? |
Report metadata
Every report starts with a consistent header. The metadata is part of the document, not just a filename or a sidebar label. Keep it visible in the page, exports, and any version distributed to a reader.
| Field | Requirement | Meaning |
|---|---|---|
| Title | Required | The subject and useful conclusion, without promotional wording |
| Description | Required | One sentence explaining what the report covers |
| Audience | Required | The intended reader and the decision the report supports |
| Date | Required | The publication or reporting date in ISO form; explicitly unknown for an undated historical source |
| Category | Required | Product, feature, technical, daily activity, weekly, audit, benchmark, plan, investor, or reference |
| Tags | Required list | A small set of searchable subjects, such as audio, navigation, or performance |
| Confidentiality | Required | Public, Internal, Confidential, or Unreviewed while classification is pending |
| Status | Required | Draft, Published, Historical, or Superseded |
| Author or owner | When known | Who is accountable for the document |
| Updated | When revised | The revision date; it does not replace the original reporting date |
| Source revision and links | When relevant | The code or evidence the claims were checked against |
Use Unreviewed when classification is unknown; do not infer Public from a file's presence in a repository. A confidentiality label describes handling, not access control. The hosting service and distribution process must restrict non-public documents. A page marked Published needs a date and reviewed classification. A reporting period, if different from the publication date, belongs in the opening scope statement.
kind: report
title: "[Subject]"
description: "[What the reader will learn]"
audience: "Working engineers"
date: null
category: technical
tags: [audio, architecture]
confidentiality: unreviewed
status: draftAn undated migration retains date: null and displays “Not recorded.” Never use the migration date to imply that
an old report has been freshly verified. Mark missing authors and source revisions honestly rather than inventing them.
Daily commit reports
Lead with the day's user outcomes, then group changes by theme. Include the UTC reporting window, repository and branch, linked commits, relevant verification, and follow-up. Give a substantial change a concise diagram when it helps explain the result. A quiet day can be one short page; an empty day says so without padding.
An activity bar chart can show when changes landed. Commit counts and lines changed are supporting context, never proxies for quality, productivity, or value delivered. Keep daily reports in dated order and link adjacent dates.
Weekly progress reports
Summarize outcomes over a stated week, compare like periods, and separate shipped work from next priorities. Use a small number of metrics whose meaning is stable across weeks. Explain changes in measurement or scope.
Delivery and service quality
Illustrative data, not Bosun operating results. All trends cover Monday through Sunday.
Read the value and its definition first, then the trend. Each metric has its own labeled scale.
Feature reports
Define one capability, its status, added and updated dates, and what the crew gets. Show a concrete scenario and a short explanation of how it works. Include limitations, verification, and a curated table of GitHub entry points. Use commit-pinned code links when line references matter. Link the associated systems explanation and product story.
Technical deep dives
Explain responsibilities, interfaces, and the critical runtime path. Start with an architecture overview and a sequence diagram. Add a state diagram when lifecycle matters, or an entity diagram when persistence is central. Place a paragraph explaining each diagram before it. Cover failures, recovery, operational limits, and verification.
Keep composition diagrams and hop traces distinct when both exist. Composition answers who owns what; a trace follows a concrete scenario through the system. Avoid exhaustive struct dumps and file lists that do not help the reader understand behavior. State the revision that supports the report.
Audits and readiness reports
Give a dated verdict with explicit scope and exclusions. Each finding has evidence, impact, a recommended action, and a way to verify the resolution. Separate observed failures, missing evidence, and proposed improvements. Do not convert an unknown into a pass or a missing measurement into zero. Historical audits remain dated records.
Benchmarks and experiments
State the question before the chart. Record hardware, software revisions, workload, commands, repetitions, units, and variability. Compare equivalent baselines and candidates. Preserve raw measurements and explain exclusions. Use paired comparisons, distributions, or intervals; a single average can hide a tail-latency regression.
A benchmark conclusion says what the evidence supports under those conditions. It does not imply a wider speedup, capacity claim, or production outcome without a corresponding experiment.
Plans and decisions
State PROPOSED, IN PROGRESS, BUILT, or SUPERSEDED in the header. Record constraints, alternatives, tradeoffs, the chosen approach, milestones, acceptance criteria, and rollback where relevant. Once built, link an as-built explanation. Keep the plan's decision record distinct from the description of the implemented system.
Investor updates
Use the investor communications templates for quarterly reports, shareholder emails, fundraising briefs, and outreach. Open personally, compare verified periods, explain results, cover product and customers, disclose material risks, and make a specific request. Keep completed drafts and financial data in a private destination until publication is authorized.
Page anatomy and visual grammar
A native report has a title, one-sentence description, scope or date where needed, an opening conclusion, supported sections, and related reports. Use the reading roles for prose, tabular figures for comparable values, and a wider figure only when the information needs it. The contents list follows real headings; Previous and Next follow the collection's reading order.
Use sparklines beside defined values, aligned trend tables for comparable quantities, and combination charts only when their marks answer distinct questions. The data visualization page shows live report examples, scales, missing-data treatment, legends, and source tables.
Related
- Reports and docs: site adoption and reading layout.
- Data visualization: report charts and combinations of sparklines.
- Investor communications: report and email templates.
- Presentations: layouts for presenting the same evidence in a room.