Ck Notes

---
name: ck-notes
description: >-
  cad-khana's delta on the shared notes machinery — which `_notes/` file plays
  which role in the demand-driven loop (worklist, field-notes, slice briefs,
  two-way handoffs, adoption inventory), the bookkeeping a session owes when a
  slice closes, and the traps that have actually bitten (stale commit SHAs after
  a history rewrite, consolidating shipped `ideas.md` rows, deleting a
  field-note that still backs an open row, promoting at f×1 on a rationale the
  policy doesn't name). Invoke before updating the worklist, triaging
  field-notes, closing a shipped `ideas.md` row, or writing/closing a slice
  brief or cross-repo handoff.
---

# cad-khana working notes — the delta

Two shared skills already cover most of this and are **not** repeated here:

- **`working-notes`** — the `_notes/` symlink mechanism, why `Grep`/`Glob`
  find nothing, the `rg` forms, the leave-it-uncommitted cadence.
- **`repo-research`** — signal doctrine, the promotion policy and its two
  exemptions, dispositions, the closing-a-shipped-idea workflow, filing
  formats.

Load whichever applies; this file is only what those two don't say about
this corpus. `CLAUDE.md` §"Working notes" lists the files; §"Field-notes
promotion policy" maps a promoted fix to its code/doc surface.

## The loop these notes serve

cad-khana is demand-driven: a feature starts from an observed consumer need
and **closes only when the consumer actually converts its sites**. The notes
are the two halves of that loop.

| File | Role in the loop |
|---|---|
| `field-notes.md` | Consumer-written friction, unfiltered. The demand side's raw input. |
| `adoption-inventory.md` | The *stock* of friction already priced into the consumer's code — workaround sites mapped to the call shape they wish they could write. Each section is a feature's ready-made exercise slice. |
| `worklist.md` | **Continuing-state file.** Sequencing and status for the cad-khana side only. |
| `research/ideas.md` | Authoritative for provenance and scoring. The worklist points at it, never duplicates it. |
| `implementation-log.md` | Why each thing shipped; the durable record when a source note is deleted. |
| `sorted-studs-<slice>.md` | A one-way **slice brief**: cad-khana ships, the consumer exercises, the row closes on results. |
| `sorted-studs/<topic>.md` | A two-way **handoff**: both repos edit the same file in place. Gate block at the top, Results filled by the consumer, Close-out filled here. |

**A row is not closed when the code ships.** It is closed when the slice
brief comes back with results and the sites are converted. Write the
outcome into the `ideas.md` row, the log entry and the worklist row in the
same pass — a row that says "code shipped, slice open" for two sessions is
how the loop silently stops being demand-driven.

## Slice briefs and handoffs

- A slice brief is **spent** the moment its results land. Mark it spent at
  the top with the outcome in a paragraph, keep the original brief below
  under *"kept for the record"*, and don't move or delete the file — the
  briefs are how a later session reconstructs why a feature landed in the
  shape it did.
- A two-way handoff is closed by **filling its Close-out from this side**,
  even when the consumer already wrote "DONE" throughout. The Close-out is
  where cross-repo consequences get named: a caveat the consumer's work
  retired, a field-note that came back, a decision now gated.
- **Re-verify an inventory before trusting it.** Every handoff that carried
  a per-file inventory has had it drift between authoring and execution —
  files already fixed by an earlier item, sites the grep shape couldn't see.
  Anchor inventories to a commit and say so.

## Bookkeeping traps that have actually bitten

- **A history rewrite orphans every SHA in these notes.** 2026-07-26: the
  day's last three commits were rewritten to fix co-author trailers, and
  `944e37c` — already written into the log and into a handoff's gate block
  — stopped resolving. After any amend/rebase/filter-branch, `rg` the notes
  for the old SHAs and correct them *with a parenthetical saying they were
  rewritten*, so a reader who saw the old value isn't left doubting.
- **Don't leave `*(pending)*` / `*(this slice)*` in a log entry.** Both are
  written before the commit exists and nothing prompts you to come back.
  Fill the SHA in the same session, or the entry silently loses the link
  `git log` was supposed to provide. (Nine entries had gone stale this way.)
- **Don't consolidate several shipped `ideas.md` rows into one.** It reads
  better and defeats the table's only job: an idea whose row title no longer
  appears verbatim can be re-proposed by the next rescrape. Move each row
  separately, even when one commit shipped all of them; the shared log
  pointer is what ties them together.
- **A field-note may back more than one row.** Delete-on-promotion fires per
  *note*, not per row — check every row the note sources before deleting.
  The 2026-05-21 arc-math note sources both the shipped sampling substrate
  and the still-open union-bbox row, so it stays.
- **Say which exemption you are using when you promote at f×1** — and if
  it is neither of the two the policy names (field-note resonance with an
  existing row; the bug exception), name it as what it is: an
  **owner-discretion override**. The owner may override any threshold; the
  point of the record is that overrides stay *visible as overrides* instead
  of accreting into doctrine, so a growing pile of them is legible as
  overreach rather than as precedent. Practically: write the rationale into
  the row, label it an override, date the ratification, and never
  generalize one into a new standing rule — the next f×1 needs its own
  override, not a citation of this one. (First use: 2026-07-26, the two
  SKILL.md doc rows. If a *kind* of override recurs often enough to earn
  standing status, that belongs in the shared `repo-research` policy, not
  here.)
- **Parked ≠ waiting for a decision.** A parked note unparks on another
  occurrence, not on someone choosing. When two notes turn out to be the
  same question from different directions, that is the second occurrence —
  unpark them as one row and state the question at the level both share,
  rather than building the first shape either note suggested.

## What "update the notes" owes

When a session ends with work that changed the loop's state, the sweep is:

1. `worklist.md` — the state that changed, and the *next-session* pointer
   rewritten (a stale one is worse than none; it sends the next session at a
   slice that already closed).
2. `ideas.md` — rows moved to ✅ (row per idea, reduced columns), new rows
   for anything the slice opened, backlog sections left holding open work
   only.
3. `implementation-log.md` — one entry, newest at the top, with both-way
   provenance pointers.
4. `field-notes.md` — a triage verdict inline on each new entry; deletion
   only when every row a note backs has shipped.
5. Slice briefs and handoffs — spent / Close-out filled.
6. Anything the work *falsified* — a spec caveat the consumer's refactor
   retired, a row that named a CLI verb the surface no longer supports.

Leave it all uncommitted; the housekeeping sweep picks it up.