record

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Record

Keep what the work produced while it is still in your hands: the source with its location, the rule rather than its result, the conclusion with what it rests on and what would make it wrong. It is a byproduct of the work, written when it exists and not at a ceremony. Run `kpop` or `kpopper` from the native runtime and prefer the canonical executable in `KPOPPER_AGENT_CONTEXT.command`. Pass its `environment` to write commands too: the supplied session identity attributes successful writes but grants no access or permission. Never invent an identity. Do not guess a path or silently fall back to PATH.

In ordinary conversation, name the product **kpopper** and describe the action in the user's language. Reserve the exact skill name `kpopper:record` for invocation instructions, technical documentation, debugging, or explaining this specific skill. Fold the product name into the explanation of the action; no extra announcement is needed.

**For a source report in an existing single-file record, use `kpop update --file -` where POSIX file locking is available.** Send one `updates` list with everything already known from that report; one item is enough. Record it while the context is fresh, without waiting for unrelated facts or session end. Read the returned state before relying on it. **On native Windows, use ordinary `add`/`set` instead;** verify each result, since separate writes are not an atomic batch. A locking error means the report was not retained. [INGESTION.md](../kpopper/INGESTION.md) gives the contract and layouts. Structured expressions and snapshots require compatible CLI/plugin/CI versions; check [reader compatibility](../kpopper/EXPRESSIONS.md#reader-compatibility) before writing. First writes, other layouts and deliberate judgment reviews retain their ordinary commands.

## The first write

New, unconfigured projects use private central Simple without a mode question or announcement. The first valid record-creating `add` binds a UUID location; read-only previews create no central state. Advanced requires explicit Experimental selection. Preserve legacy records and explicit paths until a validated transition; local storage grants no Board permission.

Simple shares one graph; Advanced keeps branch context and kpopper Board for feature-independent findings. Private or unclear sharing permission takes priority and retains a private draft. Keep exact source, scope and commit; unmerged measurements are scoped facts, not automatically hypotheses. Capture, proposal and acceptance differ; merge neither proves truth nor refreshes `seen`. See [project modes](../../docs/project-modes.md). **Route before writing:** an authorized shared report needs `shareability: "project"` and `scope: {"kind": "external", "environment": "service/account"}` (or project scope). Verify `project_captured` and its receipt. `applied` means local writing; an unannotated report does not feed the Board. Code/feature findings stay with the branch. Neither a remote nor confident wording grants sharing rights.

If hypotheses cause `needs_primary`, review the retained report. An independent complete finding can use primary `add --scope external --environment ENV --shareability project` with permitted portable evidence; verify `state: captured`. Do not fold unrelated hypotheses merely to collect it. `kpop board` shows publication configuration; its one-time offer owns setup.

Record the first useful finding within the user's authorization. Sources and facts are valid alone; `add` fills `seen` for actual judgments. After a semantic refusal, reconsider the representation, not just the value's format: follow [live representation evolution](../kpopper/EVOLUTION.md), then execute supported corrections within the task's authority. Installation creates no record, and a one-off can finish without one.

In automatic Simple storage, `kpop add` creates the bound `<slug>-<uuid>/GROUNDING.yaml` with the first entry; later adds extend it. Restore an unavailable registered record instead of starting another. The [shape reference](../kpopper/references/shape.md) describes sections, pointer records and external locations.

**Make a new record useful to its reader.** When creating or arranging a record, put sections devoted to sources, sessions or conversations last, after knowledge, judgments and open questions, whatever their names. Recommend `sources` for new records; preserve existing names and grouping. This is an authoring convention; update commands preserve the existing order. Link and briefly explain the finding when its explanation is due. Show the optional experimental hub only on an explicit request or standing preference.

## Record what the work calls for

"No schema changes" preserves format; it does not forbid authorized knowledge writes. Respect explicit
read-only or record-write bans; do not turn a restriction inferred in a draft plan into a user prohibition.

Before finishing the current request or handing off a PR, account for all material findings,
including research and external documents. Within existing authority, retain new knowledge and
run `check` and read back values, sources and scope. Reuse coverage; no filler when nothing is new.
Keep routine success and no-change checks quiet; report material unresolved capture with the answer.
Follow the [handoff contract](references/handoff.md); a changed file does not prove complete retention.

A selected mapping or investigation makes discovery the task: follow `kpopper _agent guide`
within its agreed scope and report its limits. More available material is not a reason to survey it.

### 1. Something you took from a source

Not only numbers. A date, a name, a deadline, a quoted clause, a definition, a term someone agreed to, a list you extracted, a position a person stated. In most domains this is mostly **text**.

Record where it came from, precisely enough to go back: the source *and the location within it*. "The contract" is not a location; "the contract, §4.1" is.

Record negative findings the same way. "Absent from all three registry files" is a result with a
source, and the next session should not have to look again.

**A session is a source when the evidence was made in it** — a measurement, a probe, a run
that produced the number. Record it as one: what was done, when, and in which session,
precisely enough to go back to the transcript. The judgments a session writes need no
session field; if two sessions ever disagree about one, that is the question that earns it,
and not before. A session is also a source when what it already knew is what a judgment rests
on — a `prior.*` claim whose value is the confidence; see *An agent's prior as a source* in [falsifiers.md](../kpopper/references/falsifiers.md).

**And record how faithful it is.** This matters far more for text than for numbers, because a number is either read correctly or not, while text degrades in stages:

| | what it is | how to treat it |
|---|---|---|
| **quoted** | the source's own words | the strongest thing you can hold; keep it verbatim |
| **paraphrase** | their substance, your words | fine, but say so — someone may need the original wording |
| **characterization** | your reading of what a source means or implies | **this is a judgment, not a reading** — see below |

**Give it a name.** One line per entry, in the record's own language, saying what the thing *is*:

```yaml
  date.rate_lock:
    name: Rate lock expiry in the pre-approval
    v: 2026-09-18
    from: ...
```

`name` (or `title`/`label`/`what`) is the only field this method asks for by name rather
than inferring by shape — a sentence has no distinctive shape. It costs one line at the
moment you already know what you are writing down, and without it every surface that is not
about keys has to fall back to `rate lock`, which is the system's name for the thing and not
the reader's. `kpop experimental hub --verify` reports how many entries are missing one. Sources
need one as much as entries do: `pr352: {url: …}` is a key, and `name: "the pull request"`
is what a reader sees in every hover that cites it.

That is the general rule for the whole page: **name things the way the reader would, never
the way the record is built.** A blocked line says *"the bank's position was never put in
writing"*, not *"blocked on mtg.clause7_reading"* — so a `blocked_on:` mapping should carry
its reason in prose, and the page shows the reason and keeps the key for the hover. Keys,
rules, predicates, state names: all of that is the machinery, and the machinery lives one
hover away. A derived entry says it was *worked out*; its formula is in the hover, never on
the surface.

### 2. Something you worked out

Record the rule, never the result. The same applies to non-numeric work: if you derive a list by filtering another, record the filter as a textual `rule`. Keep its inputs and limits explicit. For supported calculations, use `rule={expr: "order.price * order.quantity"}` and executable `wrong_if={expr: "order.total > order.limit"}`. `add` and `update` also store supported plain formula strings in this readable form; the local Lean core computes them. Keep `rests_on` explicit and historical snapshots intact. Inside `expr`, quoted text is literal; `ref("an opaque id")` names a reference. Read fallback diagnostics: text retained without Lean is not a calculated result. [EXPRESSIONS.md](../kpopper/EXPRESSIONS.md) covers syntax and migration; unsupported work needs its declared limit.

### 3. Something you concluded or composed

Recommendations, assessments, comparisons — **and summaries, overviews, and any passage you wrote from several sources.** A summary belongs here and not in category 1: it is not something you took, it is something you made, and what you left out is invisible to every later reader.

> **The test:** if everything it rests on is correct and it could still be wrong, it is a judgment.

"The annual cost is $90,720" is not — check the arithmetic and you are done. "Acme is the better choice" is, and no amount of checking settles it. "The agreement is restrictive about early termination" is one too, even though it sounds like a report of what a document says — which is exactly the trap.

### The trap worth naming

**A characterization of a source drifts into being treated as a reading of it.** Someone writes "the contract restricts resale", a later reader takes it as quoted fact, and by the third session it has hardened into something nobody traces and nobody re-checks — while the clause it came from may say something much narrower. If you are describing what a source *means* rather than reproducing what it *says*, that is a judgment and it needs `wrong_if` like any other.

## Never restate from memory what you recorded

The moment something is needed in a second place, reference the record instead of typing it again. A number retyped into prose goes quietly stale while the recorded one is updated — and a quotation restated from memory is worse, because it drifts *and* still looks like a quotation.

If the document is generated, that means a placeholder resolved at build time. If it is hand-written, it means re-reading the record before restating anything, every time.

Watch for the failure where a reference gets swallowed by surrounding text — a literal `~1` typed
in front of a reference to an `80,000` entry silently renders as `180,000` and then moves whenever
that unrelated entry does. If a rendered number is not exactly one reference, it is a bug.

## The sign that would make it wrong

Every judgment says what would make it wrong, and the reader evaluates it where it honestly can:
`wrong_if` is one comparison over entries the judgment rests on - `acme.seats < 150`,
`flue.clear == false`, or supported arithmetic operands. Compound comparisons are unsupported.
A predicate that cannot be evaluated says so with `blocked_on` and why; a decision taken on a
session's prior, or on taste, names the prose sign that would re-open it in `reopened_by`. Never
invent a threshold to make a predicate evaluable, and never write prose in a predicate field.

From ilanbm/kpopper, MIT.

More from ilanbm/kpopper