/create-notes

name: create-notes
description: "Write a note to {shared_dir}/notes/ that future agents can actually act on. Use after every coral eval, when a heartbeat (reflect / consolidate / pivot) asks for a note, or when you discover a grader / build / runtime issue that future agents will hit. Covers 4 note variants (experiment / infra / focus / synthesis), the required frontmatter with the team-level `creator:` filter, the structured-trace schema (`type` / `claim` / `status` / `confidence` / `based_on` / `evidence` / `supersedes` / `refutes` / `touched`) that populates the dashboard knowledge graph, the self-audit checklist (backfilled predictions, abandoned paths, sourced magic numbers, cross-links), the bundled `scripts/{stamp,lint,unattributed}.py` helpers, and the shell-escaping gotchas that silently strip markdown content. Trigger this skill whenever you are about to Write a file under notes/ — even if the prompt didn't say 'write a note'."

Create Notes

A good note answers three questions a future agent will actually ask:

1. **What did you do, and what happened?** (concrete numbers, not adjectives) 2. **Why did it happen that way?** (the mechanism, not just the result) 3. **What should I do — or not do — given this?** (ordered next steps + things you tried that failed)

A bad note is a wall of headings with empty bodies, or a final-design pitch with no record of the alternatives you rejected. The bad pattern shows up enough that this skill exists to prevent it.

When to Use

Each heartbeat that produces a note corresponds to one variant. The skill is one document, but you only need the variant your current trigger asks for.

| Triggered by | Variant | File location | |---|---|---| | `reflect` heartbeat after each eval | **Experiment note** (Variant A) | `notes/experiments/eval-<N>-<slug>.md` | | `pivot` plateau detection | **Focus note** (Variant C) | `notes/focus/focus-<topic>.md` | | `consolidate` synthesis / connections / open-questions | **Synthesis + map + gaps** (Variant D) | `notes/_synthesis/<topic>.md`, `notes/_connections.md`, `notes/_open-questions.md` | | First time a grader / build / runtime issue is hit | **Infra note** (Variant B) | `notes/infra/<slug>.md` (or `notes/<slug>.md`) | | `deep-research` warm-start phase | **Research note** | Per `deep-research/SKILL.md` (not duplicated here) |

If you are about to `Write` any file under `notes/`, stop and use this skill first — even if the prompt did not say "write a note."

Notes Directory Layout

The directory structure is owned by `organize-files`. Do not invent new top-level subdirectories; place new content in the right existing one:

notes/
├── index.md              ← table of contents; you update this for any new note
├── raw/                  ← immutable sources (do not write here directly)
├── research/             ← deep-research findings (link back to raw/)
├── experiments/          ← per-eval reflections, written by the reflect heartbeat
├── infra/                ← grader / build / runtime issues + workarounds (recommended)
├── focus/                ← per-agent focus declarations (owned by the pivot heartbeat)
├── migrations/           ← island-arrival notes (written by the framework)
├── _synthesis/           ← owned by consolidate; do not write here unless consolidating
├── _connections.md       ← owned by consolidate
├── _open-questions.md    ← owned by consolidate
└── _organization-log.md  ← append-only audit log; only organize-files writes here

**Always update `index.md`** with a one-line entry when you create a new note. The next agent's first move is to read it.

Bundled Helpers — use these instead of writing from scratch

The skill ships three small Python scripts and two reference documents. They mechanize the boring parts so you spend attention on the content, not the format.

{shared_dir}/skills/create-notes/
├── scripts/
│   ├── stamp.py          Generate a frontmatter-populated skeleton for a variant
│   ├── lint.py           Check a note against the self-audit checklist
│   └── unattributed.py   List notes missing a creator: field
└── references/
    ├── worked-example.md   A realistic before/after for an infra note (Variant B)
    └── frontmatter-spec.md Full structured-trace field reference + vocabularies

The usual flow for a new note:

# 1. Stamp the skeleton — fills creator/created/type, leaves the rest as <placeholders>
python {shared_dir}/skills/create-notes/scripts/stamp.py experiment \
    --out {shared_dir}/notes/experiments/eval-12-my-slug.md

# 2. Fill in the placeholders (claim, status, evidence, body sections), then lint
python {shared_dir}/skills/create-notes/scripts/lint.py \
    {shared_dir}/notes/experiments/eval-12-my-slug.md

`stamp.py` reads `.coral_agent_id` in the cwd for `creator:`. `lint.py` is advisory by default — pass `--strict` if you want a non-zero exit on warnings.

---

Note Variants

Variant A — Experiment note (reflect heartbeat, 7 sections)

The default for per-eval reflection. Use for any note describing what you tried in a single attempt or a small set of related attempts.

`scripts/stamp.py experiment` produces this frontmatter and section skeleton:

---
creator: <your agent_id, from .coral_agent_id>
created: <ISO-8601 timestamp>
commit: <the coral eval commit hash this note describes, or "n/a">
type: experiment
claim: "<one testable sentence — e.g. 'u8 SIMD widening doubles QPS at recall ≥ 0.97'>"
status: <confirmed | refuted | untested>
confidence: <low | medium | high>
evidence:
  attempt: <commit hash>
  score_delta: <baseline → this; signed number>
  verified: <true | false>
based_on: [<prior hash>, <another hash if applicable>]   # YAML list — one is fine, more is better
touched: [<files you changed>]
tags: [<topic tags>]
---

# <Verbed noun phrase>: <one-line top-line result>

Section guidance:

• **Title** — name what happened with a number. Good: "V2 IVF real-mode: 1M SIFT1M, 1,251 QPS