What does research-log do?
Documents research the way engineers retell it afterwards: a story of measurements, a spec precise enough to re-implement from, a verification record with numbers, and an honest list of what is still unknown — delivered as one self-contained HTML file (CSS and images embedded, no external assets).
The core commitment: every claim is either backed by a measurement, marked as unproven, or listed as open. The guiding sentence, if you need one: reading the artifacts tells you what someone wrote; only the real system tells you what it means.
Workflow
1. Inventory the evidence first
Collect, before writing anything, from the conversation, repo, logs and the user:
- the chronology: dates, what was tried, what failed, what surprised
- every measurement with exact numbers and how it was obtained
- verification runs: what was compared against what, and the error figures
- the tools, file paths and commands someone needs to repeat the work
- unresolved questions and pure hypotheses
Do not invent measurements, dates or numbers. If a number is missing, ask or mark it OPEN. A writeup with invented data is worse than no writeup — gaps in the record are part of the record.
2. Learn the conventions
Read references/style-guide.md before writing — the style lives in its details (captions that prove a point, failures kept in the narrative, numbers exact, no marketing). Read references/content-format.md when ready to write the content module.
3. Pick the skeleton
Six core sections, numbered, in this order. Omit one only for a stated reason; insert case-study sections between the spec and tools when there is a "building the real thing" arc.
| # | section | must contain |
|---|---|---|
| 1 | The story | day-by-day timeline; every step attributed to a measurement; dead ends and surprises included |
| 2 | Method | one epistemology sentence + the table: test artifact → question → answer |
| 3+ | The spec | byte/protocol/format tables precise enough to re-implement from, with confidence tags; the maths as code blocks |
| −2 | Tools & how-to | real commands and paths that work when copied verbatim |
| −1 | Verification record | every measurement run with quantitative errors + a Bottom line callout |
| −0 | Open questions | honest unknowns, each tagged OPEN or HYP |
4. Write and build
Write the content as a Python module defining DOC (format in references/content-format.md), keep it in the project so the doc can be regenerated, then:
python3 <skill-dir>/scripts/build_doc.py content.py out.html
Open the output and check it renders before showing the user.
5. Self-audit
- every factual claim carries a tag or sits in the verification record
- the story includes at least one surprise, failure or correction — if the work had none, say so plainly instead of manufacturing drama
- numbers are exact and carry units (0.445 s, not "fast"; 64,779 pixels, not "many")
- every figure caption states what the image proves, not what it shows
- how-to commands were actually run, or are clearly labelled as untested
- open questions exist (there are always open questions)
- the bottom line is one sentence someone could repeat from memory
The tags
Four confidence tags, placed inline at the end of the claim they qualify:
- HW (green) — measured on the real system under test. For non-device work this still applies: measured in a live run, on the bench, in production.
- FILE (blue) — true in every artifact examined (files, captures, logs).
- HYP (purple) — consistent with all evidence, but unproven.
- OPEN (grey) — unknown; no evidence either way.
Facts carry tags; commentary does not. If the domain has better names for these, rename them once at the top of the doc and use them consistently — but keep exactly this four-level split.
Voice
Peer engineer, first person plural, zero marketing. Numbers exact with units. Sentences short. Humor dry and rare. Failures and corrections belong in the story, not in a footnote. Colleagues are credited by role ("a colleague delivered two PNG sequences…").
Origin
Distilled from the TriCaster DVE research log (waldobjekt.org, 1–3 Nov 2026, authored with Claude) — the origin doc ships its own build_doc.py; this skill generalizes that setup.