feat(framework): add create-notes skill, slim note-authoring content out of heartbeats

[BobbyZhouZijian]

Summary

Centralizes all note-authoring guidance in a single new skill (coral/template/skills/create-notes/SKILL.md) and trims the duplicated content out of the 3 heartbeats that produce notes (reflect, consolidate, pivot). The prompts become slim triggers that point to the skill.

Why

The 3 note-producing heartbeats each duplicated substantial guidance: section templates, the creator: frontmatter rule, filename conventions, and the shell-escaping gotcha. The ~135 lines of consolidated content was hard to keep in sync — drift was already visible (e.g. consolidate.md listed one filename convention, reflect.md listed another). Adding a new note variant required editing 3 places.

Centralizing fixes both: one place for the canonical content, prompts carry only the trigger + which skill section to load.

What's in the new skill

• 4 note variants with full templates:
  • A — Experiment (reflect, 7-section: Context / Result / Mechanism / What did not work / Surprises / Next / References)
  • B — Infra (grader / build / runtime issue, 7-section framed for diagnosis + workaround)
  • C — Focus (pivot, Posture / Lane / Budget / Abandon-if / Why this has positive EV)
  • D — Synthesis / Connections / Open-questions (consolidate, 3 sub-formats)
• Filename conventions table (path patterns + kebab-case rules)
• Frontmatter discipline — explains why creator: matters: team-level processes (consolidate team-audit, librarian attribution, migration) silently skip notes without it
• Self-audit checklist split by variant (the 8 things every note must satisfy before saving, e.g. "every magic number has a source: measured / cited / estimated")
• File-writing gotcha — the python3 -c "..." + backtick-stripping bug that produced empty-skeleton notes
• Worked example: before and after — the same grader-infra issue rendered as the kind of empty shell that shows up too often, then as a proper Variant B note

The 7-section experiment template was extracted from observed failures in examples/vector_db_bench (island 1): notes had concrete numbers but no record of rejected alternatives, no cross-links, unsourced magic numbers (50 GB/s memory bandwidth appeared in two notes without citation), and quantitative predictions that were never backfilled.

What changed in the prompts

File	Before	After	Delta
coral/hub/prompts/reflect.md	60	45	6 detailed note-authoring sections → 2-line skill pointer + 3-question "What to reflect on" guide. Role-evolution section preserved (it's CORAL mechanism, not note-authoring).
coral/hub/prompts/consolidate.md	135	47	3 full example formats + 7-step process → 4-line skill pointer + 6-step overview. Step 7 (team-audit of roles / lanes / postures) preserved.
coral/hub/prompts/pivot.md	66	68	Step 4 (focus note structure) → 1-line skill pointer + 3 key constraints (Posture / Abandon-if / Why-EV).
coral/template/agents/librarian.md	89	89	No change on main (the duplicated "Frontmatter discipline" section only exists on the multi-island branch — out of scope here).
coral/hub/prompts/lint_wiki.md	16	16	No change (already a one-liner spawning librarian).
coral/hub/prompts/warmstart_research.md	7	7	No change (already points to deep-research skill).

Net: +461 lines in skill, -101 across the 3 prompts.

Deferred (not in this PR)

• Trigger eval optimization (skill-creator step 6) — 20-query eval loop that refines the frontmatter description for triggering accuracy. The current description is already pushy ("Trigger this skill whenever you are about to Write a file under notes/ — even if the prompt didn't say 'write a note'"), but a proper run would let the team validate it.
• Full with-skill / without-skill benchmark loop (skill-creator steps 3-5) — would require spawning subagents in a run to compare note quality with and without the skill. Better as a follow-up once the skill is in the wild and an evaluator can grade against real production notes.
• Cross-island migration — the multi-island branch's librarian.md has its own "Frontmatter discipline" duplication. Out of scope for this PR; will handle when multi-island merges.

Test plan

• Render in a fresh run: spawn an agent, fire reflect heartbeat, verify it loads the create-notes skill and writes a 7-section note with all 8 self-audit items satisfied
• Render infra path: simulate a grader build failure, verify the agent writes a Variant B note with a code citation and ≥ 2 "What did not work" entries
• Render pivot path: verify the agent writes a Variant C focus note with a concrete abandon-if gate
• Render consolidate path: verify the agent writes a Variant D.1 synthesis with ≥ 3 cited attempt hashes and a confidence statement
• Run uv run ruff check . (no Python changes, should pass clean)

Co-Authored-By

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
coral	Ready	Preview, Comment	Jun 5, 2026 7:12am