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.
- **A suggested conversion goes over unprobed.** When a handoff suggests
  the consumer convert sites to shipped API, don't build and run the
  conversion on their tree first: their run is the exercise, so a pre-run
  duplicates a long check on a shared machine (owner, 2026-10-04: "why
  would you run the conversion twice. let them run it and report"). The
  probe-before-claiming rule binds what cad-khana ships. Say in the
  handoff what is unprobed and what they should watch go red.
- **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.)
- **Sightings from one consumer count — then confirm them.** cad-khana has
  one active client site, so most sightings come from the same repo,
  often on the same day. Owner ruling (2026-09-27): take them seriously
  rather than discounting them to f×1. The triage owes two more things:
  **confirmation from the other sources** (thattuvaasal's tree, the
  survey rows in `research/ideas.md`, older notes from a different
  slice), and **how likely the need is to repeat**, judged once the
  shape of the need is understood (is it a property of mechanisms in
  general, or of this one part?). Write both into the verdict. A count
  with no confirmation and a one-part shape stays parked.
- **Parked ≠ waiting for a decision.** A parked note unparks on another
  occurrence, not on someone choosing. **So write the unpark condition as
  an observation only** — "a second occurrence in a separate context",
  "the same problem for a different assertion kind" — and never as
  "…*or* a decision on which of the N forms we want". A decision about
  *shape* answers a different question from whether the need is real, and
  one is always available on request, so that phrasing converts the gate
  into a formality the promoter can discharge at will. It happened: the
  `inspect()`-SystemExit note carried exactly that clause (2026-07-25),
  the consumer supplied a well-argued shape, it shipped at f×1, and the
  owner accepted it "this one time" while flagging it as no precedent
  (ruling recorded on `implementation-log.md` "Diagnostics evolution 5").
  When a design decision arrives while a row is still f×1, record it
  against the row and keep waiting — it will be free when the second
  occurrence lands. If shipping early still looks right, say plainly that
  the gate is being waived and whose call it is, rather than routing
  around it through the parking note's own wording. 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.