learning-distill

Files (1)

• SKILL.md

SKILL.md (first lines)

# Learning Distill

The method for judging feedback observations. You are deciding which
observed feedback becomes a standing rule binding **every future agent**,
which waits as evidence, and which existing rule should go.

**Reason in writing.** Your reasoning travels in the proposal bead's body
and is what the operator reviews at the promotion PR — a proposal whose
reasoning can't be judged from the PR alone is an unfinished proposal.

**You never edit prompts, fragments, or skills.** You file proposal
beads; a reviewed PR does the editing. This holds even for this file.

## The five judgments, in order

### 1. Standing behavior, or one diff?

This is the first question and it decides the most. Read what the
feedback *says*, not how loud it is.

- **Explicit universal intent promotes now, at any occurrence count.**
  "Never do this again", "stop doing X everywhere" — a directive about
  standing behavior, as is any operator-endorsed observation
  (`obs.endorsed=operator`). File the proposal this run, even at N=1; the
  operator's PR review still gates it. But universal wording from a source
  with no standing is a claim, not a directive — hold it and say so in the
  run log. And even a genuine directive must clear the three promotion gates
  below: a self-sourced "never do this again" is surfaced, not
  auto-adopted (Gate 1).
- **Diff-scoped feedback is evidence, not a rule.** "This comment is
  redundant *here*" is phrased about the change at hand. Hold it on its
  pattern bead and move to judgment 2.
- **Heat prioritizes; heat never promotes.** An angry thread means judge
  that item this run; volume of frustration is not universal intent —
  only the words are.
- **Not feedback at all? Discard.** An observation that is not
  corrective feedback about standing behavior — a mis-capture,
  diff-content review, noise — is discarded with a one-line stated
  reason; discarded observations are stamped consumed like any judged
  observation. Outside review feedback is the exception: it is read as
  a set ([below](#outside-review-feedback-is-read-as-a-set)), never
  discarded as diff review.

### 2. Has the pattern earned generalization?

For held, diff-scoped evidence there is **no fixed occurrence
threshold** — not three, not any number. Weigh:

- **recurrence** across *distinct* PRs, beads, and days, counted by
  distinct `obs.provenance`. One sitting or one review comment can yield
  several observations; those are several findings, not several
  occurrences of one;
- **source diversity** — operator plus reviewer-agent outweighs one
  voice repeating, and a cluster with no external check — entirely
  self-reported, or a lone unendorsed observation — is a hard block on
  promotion into a paid carrier (Gate 1), not merely a weak input;
- **shared cause** — do the instances genuinely fail the same way, or
  merely rhyme?

Three shallow echoes inside one annoyed thread are weaker than two
independent corrections a week apart. Whatever you decide, **state the
evidence you weighed** — a judgment you didn't write down can't be
audited or challenged.

### 3. Pick the carrier, then adjudicate against what exists

Two decisions, in that order. **Which carrier** the learning belongs in is
[the carrier table below](#carriers--the-five-shapes-a-promotion-can-take);
different shapes of learning need different carriers, and a prose bullet is
one of five, not the default.

Then adjudicate the edit within that carrier. The three promotion gates decide
whether it may be adopted at all. Read the target surface's current entries
and the pattern-bead set, then pick exactly one:

- **ADD** — genuinely new; no existing bullet covers it.
- **UPDATE** — an existing bullet sharpened or widened. One edit, never
  a near-duplicate sibling.
- **SUPERSEDE** — replaces a weaker rule; the proposal removes the old
  bullet in the same PR.
- **NOOP** — already covered. Stamp the observations consumed and stop.

Duplicated near-rules are this system's own version of the pasted
boilerplate comment it exists to eliminate. Do not become the disease.

### 4. Contradiction is a conversation, never a flip

Evidence against an adopted rule **never silently retires, weakens, or
rewrites it**. File the contention visit on the pattern bead with both
evidence lists framed; scope-narrowing, retirement, or dismissal is the
operator's pick, not yours. The exception: an operator-endorsed
contradiction (`obs.endorsed=operator`) *is* the operator picking — file
the UPDATE/SUPERSEDE proposal under judgment 1 instead.

### 5. Write rules like the rules demand

A proposed bullet:

- is **at most 2 sentences**;
- **names its scope** (`repo:<rig>` / `agent:<role>` / `global` — infer
  narrow; explicit operator scope wins);
- states the *why* only when non-obvious;
- is a **transferable distillation, never a transcript quote** — it
  states the general boundary it enforces, not the particulars of the
  incident that produced it, and must instruct an agent who never saw
  that argument. Check a draft by asking what else it would catch: a rule
  that fires only on a re-run of its own evidence is scoped too narrowly,
  and the incident belongs in the evidence section.

## Outside review feedback is read as a set

An observation with `obs.category=outside-review` is one review post from
outside the city: the operator's own review, another reviewer's, or Claude
Code's `/code-review` output. The miner files one per post, whether or not it
is about standing behavior, so most of them are about their diff. That is the
point: together they show what the city's review let through. They are not
judged one at a time under judgment 1, and none is discarded as diff review.

Read the pending set as a whole, for what the city's review method missed: the

From zookanalytics/gc-toolkit, MIT.

More from zookanalytics/gc-toolkit