Document type: investigation

Table of Contents

This page defines the investigation document type — one entry in the document types taxonomy. The general contract every document follows (frontmatter, state, linking, tags) lives on the taxonomy page; this page carries only what is specific to investigation.

1. Contract

Implements
loading. See Regulatory Functions.
Folder
the folder of the story that commissioned it, as investigation_<slug>.org. An investigation answers a question one story asked, so it is that story's record and lives beside its story.org and task_*.org files.
Level
s1, like a task — one story's artifact, not a cross-cutting statement.
Title
Investigation: <human readable title>. The Investigation: = prefix is added by the codegen automatically when the type is =investigation.
(no term)
Not stateful — no TODO, no * Status table. An investigation report is a point-in-time record.
Point in time
say when it was written and that it is a snapshot. Most investigations find things that are later fixed, so a reader arriving a month later must not mistake the record for a description of the system. The body carries the finding and the story links it.
Where the durable half goes
an investigation's conclusions frequently outlive it — a rule the code must keep following, a contract, a grid. Promote that half to the durable page that owns the subject (a knowledge doc, a component overview, a design page) and cite that from code, recipes and models. A durable page must not link into a story's folder: the lint flags it, and a reader who follows the link gets a snapshot where they expected the rule.
How to create
see New investigation report in the codegen recipe. compass add investigation requires --parent-dir and takes the story's folder.
Required sections
  • * Context — one or two paragraphs: what was the original problem or research question.
  • * Methodology — how the investigation was conducted (tools, reproducibility steps).
  • * Paths taken — detailed log of approaches tried, including those that were unsuccessful. Link to related PRs, branches, or commits.
  • * Conclusions — the ultimate findings of the investigation.
  • * Recommendations — suggested next steps or new approaches, avoiding implementation-level detail.
  • * See also — related knowledge docs, tasks, or external references.

Emacs 29.3 (Org mode 9.6.15)