Concepts

Learnings and issues, weights, scopes, and the git-native store.

The base skill is the architecture; Whetstone is the weights

A skill is the architecture — shared, tested, canonical, the same for everyone. Whetstone is the weights — everything learned about your preferences, layered on at runtime and never baked into the skill.

Whetstone never modifies the skill. It keeps a separate, per-skill memory and applies it at the start of each run, so your taste can evolve — and even run against the skill’s defaults — without mutating something everyone shares.

Learnings vs. issues

Every entry Whetstone stores has a polarity:

≈

Learning

A soft, weighted, decaying preference — what you like. "Negatives in parentheses", "warm palette, not green", "square corners." Retrieved by relevance and applied as taste.

Issue

A hard, mandatory rule the skill must never repeat — an explicit "always / never." Not subject to decay; treated as a constraint, not a suggestion.

A correction becomes a learning when it’s taste, and an issue when it’s an “always/never” or a mistake to never repeat. capture classifies and words it; revise can promote a preference into a rule or demote a rule back to a preference later.

Weight, decay, and recurrence

Learnings carry a weight that captures how strongly a preference is held. Repeating a correction (revise … reinforce) raises it; contradicting one (weaken) lowers it; unused learnings decay over time so stale taste fades instead of accumulating forever. This trajectory is exactly what the Metrics → value-over-time view plots. Issues are mandatory and don’t decay.

Scopes

Entries are grouped by scope — a short slug describing what the preference is about (e.g. currency-formatting, color-palette). Scoping is what makes retrieval precise: recall matches your elaborated intent against scopes, so a table-styling task surfaces table-styling preferences and nothing else. It’s also why passing a rich, elaborated intent to recall matters so much.

The learned global layer

Some preferences aren’t about one skill — “muted palettes, never neon” is taste you hold whether you’re making a table, a slide, or a web page. Whetstone keeps a reserved, cross-skill store (the global layer) for exactly these.

It changes recall by orchestration only, never by rewriting retrieval: recall runs the same scope-matching it already does against your skill’s store, and then runs it a second time against the global store, and returns the union. Every entry is tagged with an origin — "skill" or "global" — so when a broad global preference and a specific skill preference disagree, the model has what it needs to prefer the specific one. Turn the layer off entirely with consult_global = false in config, and recall returns a byte-identical per-skill result.

Preferences reach the global layer only by an explicit, human-enacted step — promotion always asks, regardless of supervision mode: whetstone promote <skill> <id> lifts one entry by hand, and whetstone promote <skill> <id> --cluster enacts a whole cross-skill cluster. whetstone compact --all never writes to the global store itself; it only detects preferences that recur across enough distinct skills and reports each as an advisory candidate (naming the exact --cluster command to run), leaving the per-skill copies untouched until a human enacts it. Whetstone cannot write your host’s memory (CLAUDE.md, Cursor rules, …) — it is host-agnostic — so this learned, weighted, relevance-retrieved layer is its honest home for cross-skill taste. It coexists with authored host memory rather than replacing it.

Maintenance: compaction & behavioral mining

Stores stay healthy on their own, but whetstone compact <skill> is the periodic tidy-up — run it by hand or on a schedule, never mid-task. It has two passes:

A structural pass (auto-applied): collapse near-duplicate entries, merge overlapping scopes, and retire learnings whose weight has decayed below threshold. Issues are never auto-retired.
A behavioral mining pass (advisory only): reading the event log, it flags learnings that have earned promotion (harden), scopes with capture churn (bad_capture), learnings that have gone unused (stale), and unresolved conflicts (conflict_residue). These are reported — printed and written to a git-ignored compact-report.md — and never applied automatically; you enact one with a revise. See Tools → compact.

The split is the whole point: only safe, mechanical cleanup mutates on its own; anything that changes the meaning of your store (promoting a preference to a rule, retiring one you still use) stays your call.

Preference packs

Because a store is just markdown, your taste is portable. whetstone export <skill> writes a preference pack — a .tar.gz of the learnings/ + issues/ markdown and a pack.toml manifest (private telemetry, the derived index, and git history are left out) — and whetstone import <skill> <pack> folds it into a store. Import is dedup- and conflict-aware (it reuses the exact capture logic) and always re-mints ids, so importing a teammate’s pack can never collide with your own entries. It’s the friendly, safe path for sharing a house style; because each store is already a git repo, power users can also just git remote and pull.

Storage & config

Each skill’s learned layer is its own git repository under the XDG data dir (default ~/.local/share/whetstone/<skill-slug>/; override with WHETSTONE_STORE_ROOT or store_root in config):

<store-root>/<skill-slug>/
  learnings/<scope-slug>.md   your preferences, grouped by scope (source of truth)
  issues/<scope-slug>.md      hard rules, grouped by scope (source of truth)
  next_ids.json               per-store id counters (git-tracked; prevents id reuse)
  index.sqlite                derived embedding cache (rebuildable, git-ignored)
  events.jsonl                per-run telemetry for metrics (git-ignored)
  compact-report.md           latest advisory mining findings (git-ignored)
  .git/                       full version history of the markdown
<store-root>/__global__/      the cross-skill learned layer — same structure, its own git repo

The markdown is the source of truth — read it, edit it, git revert it. The SQLite index, the event log, and the compaction report are derived and git-ignored. The reserved __global__ store holds the cross-skill learned global layer; it is a normal store you can read and edit like any other. Nothing leaves your machine.

Configuration is read from ~/.config/whetstone/config.toml, and every key also has a WHETSTONE_* environment override. The most common one is the recall backend:

# ~/.config/whetstone/config.toml
embedding_backend = "sentence-transformers"   # default: "hashing" (deterministic, dependency-free)
consult_global    = true                       # default true; false = pure per-skill recall

The default hashing backend needs no extra dependencies and no network. The sentence-transformers backend (install the embeddings extra — see Install) gives higher-quality, intent-aware retrieval; it’s the backend this site’s showcase runs on.

Note

For the full design rationale, see LEARNING_SKILLS_DESIGN.md in the repository.

--- title: "Concepts" subtitle: "Learnings and issues, weights, scopes, and the git-native store." --- ## The base skill is the architecture; Whetstone is the weights > A skill is the **architecture** — shared, tested, canonical, the same for everyone. Whetstone is > the **weights** — everything learned about *your* preferences, layered on at runtime and never > baked into the skill. Whetstone never modifies the skill. It keeps a separate, per-skill memory and applies it at the start of each run, so your taste can evolve — and even run against the skill's defaults — without mutating something everyone shares. ## Learnings vs. issues Every entry Whetstone stores has a **polarity**: ```{=html} <div class="ws-cards" style="margin-top:1.25rem;"> <div class="ws-card"> <div class="ws-card-icon">≈</div> <h3 class="ws-card-title">Learning</h3> <p class="ws-card-body">A soft, weighted, decaying <strong>preference</strong> — what you like. "Negatives in parentheses", "warm palette, not green", "square corners." Retrieved by relevance and applied as taste.</p> </div> <div class="ws-card"> <div class="ws-card-icon">!</div> <h3 class="ws-card-title">Issue</h3> <p class="ws-card-body">A hard, mandatory <strong>rule</strong> the skill must never repeat — an explicit "always / never." Not subject to decay; treated as a constraint, not a suggestion.</p> </div> </div> ``` A correction becomes a *learning* when it's taste, and an *issue* when it's an "always/never" or a mistake to never repeat. `capture` classifies and words it; `revise` can `promote` a preference into a rule or `demote` a rule back to a preference later. ## Weight, decay, and recurrence Learnings carry a **weight** that captures how strongly a preference is held. Repeating a correction (`revise … reinforce`) raises it; contradicting one (`weaken`) lowers it; unused learnings **decay** over time so stale taste fades instead of accumulating forever. This trajectory is exactly what the **[Metrics → value-over-time](metrics.qmd)** view plots. Issues are mandatory and don't decay. ## Scopes Entries are grouped by **scope** — a short slug describing *what* the preference is about (e.g. `currency-formatting`, `color-palette`). Scoping is what makes retrieval precise: `recall` matches your elaborated intent against scopes, so a table-styling task surfaces table-styling preferences and nothing else. It's also why passing a rich, elaborated `intent` to `recall` matters so much. ## The learned global layer {#global-layer} Some preferences aren't about one skill — *"muted palettes, never neon"* is taste you hold whether you're making a table, a slide, or a web page. Whetstone keeps a reserved, cross-skill store (the **global layer**) for exactly these. It changes `recall` by **orchestration only, never by rewriting retrieval**: `recall` runs the *same* scope-matching it already does against your skill's store, and then runs it a second time against the global store, and returns the union. Every entry is tagged with an `origin` — `"skill"` or `"global"` — so when a broad global preference and a specific skill preference disagree, the model has what it needs to prefer the specific one. Turn the layer off entirely with `consult_global = false` in config, and `recall` returns a byte-identical per-skill result. Preferences reach the global layer only by an explicit, human-enacted step — promotion always asks, regardless of supervision mode: `whetstone promote <skill> <id>` lifts one entry by hand, and `whetstone promote <skill> <id> --cluster` enacts a whole cross-skill cluster. `whetstone compact --all` never writes to the global store itself; it only *detects* preferences that recur across enough distinct skills and reports each as an advisory candidate (naming the exact `--cluster` command to run), leaving the per-skill copies untouched until a human enacts it. Whetstone **cannot** write your host's memory (CLAUDE.md, Cursor rules, …) — it is host-agnostic — so this learned, weighted, relevance-retrieved layer is its honest home for cross-skill taste. It coexists with authored host memory rather than replacing it. ## Maintenance: compaction & behavioral mining {#maintenance} Stores stay healthy on their own, but `whetstone compact <skill>` is the periodic tidy-up — run it by hand or on a schedule, never mid-task. It has two passes: - A **structural** pass (auto-applied): collapse near-duplicate entries, merge overlapping scopes, and retire learnings whose weight has decayed below threshold. Issues are never auto-retired. - A **behavioral mining** pass (**advisory only**): reading the event log, it flags learnings that have earned promotion (`harden`), scopes with capture churn (`bad_capture`), learnings that have gone unused (`stale`), and unresolved conflicts (`conflict_residue`). These are *reported* — printed and written to a git-ignored `compact-report.md` — and **never applied automatically**; you enact one with a `revise`. See **[Tools → compact](tools.qmd#the-out-of-band-cli-not-tools)**. The split is the whole point: only safe, mechanical cleanup mutates on its own; anything that changes the *meaning* of your store (promoting a preference to a rule, retiring one you still use) stays your call. ## Preference packs {#packs} Because a store is just markdown, your taste is portable. `whetstone export <skill>` writes a **preference pack** — a `.tar.gz` of the `learnings/` + `issues/` markdown and a `pack.toml` manifest (private telemetry, the derived index, and git history are left out) — and `whetstone import <skill> <pack>` folds it into a store. Import is dedup- and conflict-aware (it reuses the exact `capture` logic) and always **re-mints ids**, so importing a teammate's pack can never collide with your own entries. It's the friendly, safe path for sharing a house style; because each store is already a git repo, power users can also just `git remote` and pull. ## Storage & config {#storage-config} Each skill's learned layer is its **own git repository** under the XDG data dir (default `~/.local/share/whetstone/<skill-slug>/`; override with `WHETSTONE_STORE_ROOT` or `store_root` in config): ```default <store-root>/<skill-slug>/ learnings/<scope-slug>.md your preferences, grouped by scope (source of truth) issues/<scope-slug>.md hard rules, grouped by scope (source of truth) next_ids.json per-store id counters (git-tracked; prevents id reuse) index.sqlite derived embedding cache (rebuildable, git-ignored) events.jsonl per-run telemetry for metrics (git-ignored) compact-report.md latest advisory mining findings (git-ignored) .git/ full version history of the markdown <store-root>/__global__/ the cross-skill learned layer — same structure, its own git repo ``` The markdown is the **source of truth** — read it, edit it, `git revert` it. The SQLite index, the event log, and the compaction report are derived and git-ignored. The reserved `__global__` store holds the cross-skill [learned global layer](#global-layer); it is a normal store you can read and edit like any other. Nothing leaves your machine. Configuration is read from `~/.config/whetstone/config.toml`, and every key also has a `WHETSTONE_*` environment override. The most common one is the recall backend: ```toml # ~/.config/whetstone/config.toml embedding_backend = "sentence-transformers" # default: "hashing" (deterministic, dependency-free) consult_global = true # default true; false = pure per-skill recall ``` The default `hashing` backend needs no extra dependencies and no network. The `sentence-transformers` backend (install the `embeddings` extra — see **[Install](install.qmd)**) gives higher-quality, intent-aware retrieval; it's the backend this site's showcase runs on. ::: {.callout-note} For the full design rationale, see [`LEARNING_SKILLS_DESIGN.md`](https://github.com/HrudithL/whetstone/blob/main/LEARNING_SKILLS_DESIGN.md) in the repository. :::