---
name: notes-tiers
description: >
  Where an agent-created document belongs: scratch `notes/` that dies with the
  worktree, or durable `~/notes/<owner>/<repo>/` that outlives the branch.
  Covers naming, frontmatter, collisions, repo hygiene, and HTML artifacts.
  TRIGGER when creating, naming, or moving any agent-authored document —
  research notes, findings, design docs, postmortems, scratchpads, rendered
  HTML views.
  DO NOT TRIGGER for source files, or for documents the repo itself owns
  (README, CLAUDE.md, committed `docs/`).
---

# Notes: Scratch vs Durable

Agent-created `.md` docs go to one of two tiers.

**Scratch** — `notes/` at the repo or worktree root (create it if missing;
globally gitignored). Command dumps, iteration drafts, raw scratchpads. It dies
with the worktree, and that is intentional.

**Durable** — `~/notes/<owner>/<repo>/YYYY-MM-DD-<slug>.md`, a plain directory
that is not git-tracked. Decisions and their rationale, design docs,
investigation findings, postmortems — anything that still matters after the
branch merges.

## Choosing a tier

Litmus test at write time: "will this matter after the branch merges?" If
clearly yes, write it to `~/notes/...` directly at creation rather than parking
it in scratch and relying on cleanup.

Research splits the same way: in-progress in scratch `notes/`, finished in
`~/notes/<owner>/<repo>/`, or a dedicated committed directory (`poc/`, `docs/`)
when it ships with the repo.

## Durable note shape

- The filename carries the date; the title is the H1.
- Minimal frontmatter: `branch`, `commit` (the stable anchor once the branch is
  deleted), and a `session` link when available.
- Branch and worktree names live in frontmatter, never in the directory
  structure.
- On filename collision append `-2`, `-3`. An existing durable note is never
  overwritten.

## Repo hygiene

Loose `.md` files do not belong in the repo root — only `CLAUDE.md`,
`README.md`, and other standard project files live there.

## HTML artifacts

Markdown stays canonical; HTML is a view or a tool. Scratch HTML lives in
worktree `notes/*.html` and dies with it, so export findings to md before
cleanup. Durable HTML follows `~/notes/CLAUDE.md`: same-slug canonical md note,
`snapshot|tool` kind, self-contained with no secrets, data in sidecars.
Repo-committed docs stay markdown.