Experiment Reports Organization

This note is the canonical layout and authoring contract for experiment-reports/. It applies to both humans maintaining the area and agents editing notes under it. Read it before creating or restructuring any experiment-report content.

Experiment reports are the knowledge base's narrative layer for a "collection" — a set of related runs (sweep, ablation, comparison) that share a design. Repo-side analysis artifacts (notebooks, aggregates, exploratory figures) live under path:experiments/<experiment>/analysis/collections/<collection>/ and are produced by the collection-analysis skill. The knowledge base holds the distilled human narrative, linked back to those artifacts.

Directory Layout

experiment-reports/
  <experiment-group>/                   e.g. synthetic_sequences/, gaussian_mixture/
    _<experiment-group>.index.md
    <experiment-subgroup>/              optional; e.g. disentangled/, entangled/
      _<experiment-subgroup>.index.md   only when the subgroup layer exists
      <collection-name>/
        _<collection-name>.index.md     hub (see below)
        design.md
        results.md
        analysis.md
        figures/                        curated figures cited by results.md

Subgroups are optional. Introduce them when a group contains several collections that naturally partition along one axis (method family, regime, etc.). A subgroup may be created by the user or recommended by an agent; either way, add an _<subgroup>.index.md when one exists.

Hub Note

The hub _<collection-name>.index.md is a content-bearing index — it carries real content (status, abstract, links), not just navigation. Required contents:

• frontmatter type: index, status: planned|running|partial|complete|superseded
• a one-line state summary next to the status (e.g., "3/12 runs complete, design stable")
• a one-paragraph abstract describing what the collection tests and, once known, the headline finding
• ordered links to [[design]], [[results]], [[analysis]]
• an Artifacts block with path:-prefixed backticked paths to repo-side analysis outputs (notebook, aggregates dir, exploratory figures dir)
• a Context block linking to prior collections this depends on or responds to, and forward-links to successors once known
• a Runs block naming the slurmkit collection (if any), run count, and date range

Register every hub in its enclosing area or subgroup index.

File Contracts

design.md — written before or early in the collection lifecycle. Captures motivation, research questions, falsifiable hypotheses, sweep axes and coverage rationale, primary and secondary metrics, success criteria, known risks and confounders, and links to methodology/theory notes and prior collections the design depends on. Keep it decision-oriented; omit sections that add no information.

results.md — written after runs, observational only. One section per research question or swept parameter, each citing curated figures from the local figures/ directory with short descriptive prose. Include top and bottom run tables (config + headline metrics) and a completeness summary. No interpretation in this file — that belongs in analysis.md. Frame observations using callout conventions from path:.agents/skills/knowledge-base/references/callouts.md.

analysis.md — interpretive and forward-looking. Contains interpretation of each result set with explicit epistemic markers (observation vs interpretation vs speculation), cross-links back into methodology or theory notes that the results support or contradict, limitations and confounders, next-step recommendations, and open questions.

Authoring Guard on analysis.md

Interpretive content in analysis.md is human-owned. Agents may draft interpretation, but every agent-drafted interpretive section must be wrapped in an Obsidian callout of the form:

> [!warning] Agent-drafted interpretation, pending human review
> …draft content…

The user removes the callout when they have reviewed and endorsed the content. Any interpretive section without such a callout is implicitly human-authored. This rule applies only to analysis.md; results.md may be fully agent-drafted.

Figures Policy

Figures in .knowledge/ are a curated subset, not a dump. The collection-analysis skill produces many exploratory figures under path:experiments/.../analysis/collections/<coll>/exploratory_figures/; only the figures that are editorially chosen for the narrative are promoted into .knowledge/.../<collection>/figures/. Promotion is an explicit copy, not a symlink, so the knowledge base stays self-contained and portable. Use standard Markdown image syntax in results.md.

Repo Artifact Linkage

Never copy notebooks, aggregates, or machine-readable findings into the knowledge base. Link to them from the hub using `path:experiments/...` backticked paths. The knowledge base is the narrative; the repo is the reproducibility surface.