rsc-universal 0.1.1

package/skills/context-budget/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: context-budget
+description: "Use when a long-horizon task is filling the context window and you must decide what to keep, offload, drop, or hand off — large refactors and migrations that won't fit one window, multi-hour research/agent runs, planning a harness that survives across fresh sessions, or deciding when to compact and whether to spawn a subagent. Triggers: 'we're 80% through context, compact before it breaks', 'context is 80% full', 'make this survive a fresh window', 'this conversation is getting huge', 'should I spawn a subagent for this huge log read or just inline it', 'the agent keeps re-reading the same files and forgetting decisions it made earlier', 'se está llenando el contexto, ¿qué guardo y qué tiro?', 'compacta abans que peti'. NOT dollar spend or budget caps (that is cost-tracking), NOT fetching context via embeddings (that is rag)."
+tags: ["context-window", "token-budget", "compaction", "context-rot", "long-running-agents", "handoff", "subagents"]
+recommends: ["cost-tracking", "rag", "parallel", "building-agents", "harness"]
+origin: risco
+---
+
+# Context budget
+
+The context window is RAM, not a hard drive. Full ≠ free: a window stuffed to 95% does not just cost more money, it *reasons worse*. Model performance degrades as input tokens grow — even well inside the stated limit, every token added depletes a finite attention budget (Chroma "Context Rot" research, accessed 2026-06-02). Your job on a long task is to keep the *live* window lean and externalise everything else, so the work can run for hours across many fresh windows without losing the thread.
+
+> **The one rule:** if you can reconstruct a thing from a file or from git, it does not belong resident in the window. Keep load-bearing-right-now; evict the rest. The cost of forgetting is one re-read; the cost of hoarding is silent quality rot on every turn that follows.
+
+## When to use this
+
+- A task is plainly bigger than one window: a large refactor, a multi-file migration, "build the whole app", a multi-hour research or agent run.
+- You feel degradation before the gauge confirms it: repeating yourself, re-reading files you already read, drifting from the plan, contradicting an earlier decision.
+- You are setting up a harness that must survive across many sessions and fresh windows.
+- You are deciding *when* to compact, *what* to preserve, or *whether* to spawn a subagent vs. inline a big read.
+
+## When NOT to use (and where to go)
+
+- Pricing tokens, ledgering spend, firing a budget alert or a hard `$` cap → `../cost-tracking/SKILL.md`. That skill owns *money*; this one owns *working-memory quality*. Same words ("token budget"), different unit: dollars vs. attention.
+- Finding the *right* context to inject via embeddings/chunking → `../rag/SKILL.md`. RAG is *how you find* context; this is *how much* you let live and *when to evict*.
+- Crafting the prompt text, few-shot, or output format → `../prompt-engineering/SKILL.md`.
+- Designing the agent loop, tool schemas, or provider adapter → `../building-agents/SKILL.md`.
+- Fanning out genuinely independent work → `../parallel/SKILL.md`. This skill *uses* subagents as a context-isolation tactic and points there, but does not own the partition-then-gather discipline.
+- The 01-TOOLS / 02-DOCS control plane of a whole workspace → `../harness/SKILL.md`.
+
+## Read the gauge first
+
+Before you do anything, estimate utilisation: live input tokens ÷ the model's window limit. You cannot manage a budget you are not watching.
+
+- **Compact early — around ~60% utilisation, not 80–95%.** Most people only act when quality already broke at 80–95%; by then the rot already happened. Treat 60% as the line where you start reducing, not panicking (practitioner guidance on Claude Code `/compact`, accessed 2026-06-02).
+- **Trust the symptoms as an *earlier* trigger than the number.** You can feel rot before the gauge confirms it:
+  - You re-read a file you already read this session.
+  - You restate the plan or a decision you already made.
+  - You contradict an earlier choice.
+  - Tool results from ten turns ago are still sitting verbatim in the window.
+
+Any one of those is a signal to act now, regardless of the percentage.
+
+## The four moves
+
+Every context-engineering action is one of four moves (context-engineering surveys, accessed 2026-06-02). Pick by *what is eating the window*.
+
+**1. Offload** — summarise a tool output or large read; store the full thing in a file or reference, keep only the distilled fact + a path. *Why: raw bytes you might need later don't have to be resident now.*
+
+```text
+Bad:  <pastes the entire 4,000-line config file into the window to "have it">
+Good: read it, keep the 30 relevant lines, leave a note:
+      "full config at src/app/config.ts:1-4012; the load-bearing keys are X, Y, Z (lines 88-120)"
+```
+
+**2. Reduce** — compact or summarise stale history so the window carries the *conclusions*, not the journey. *Why: the dead-end exploration that got you to a decision is not the decision.*
+
+```text
+Bad:  carry 2,000 lines of trial-and-error debugging transcript forward unchanged.
+Good: compact to "tried A (failed: race condition), B (failed: types); C works — see commit a1b2c3d."
+```
+
+**3. Retrieve** — fetch a fact at runtime instead of pre-loading it. *Why: most of what you might need, you won't; pull it when you actually need it.* This is RAG's job — see `../rag/SKILL.md`.
+
+```text
+Bad:  load all 40 design-doc sections up front in case one is relevant.
+Good: keep an index; fetch section 7 the moment the task touches auth.
+```
+
+**4. Isolate** — hand a read-heavy or independent subtask to a subagent with its own fresh window; take back only the answer. *Why: a big read in a child window never pollutes the parent's.* Subagents are the single most effective anti-rot pattern (Anthropic context-engineering guidance, accessed 2026-06-02).
+
+```text
+Bad:  read 12 files into the main window to answer "which module owns retries?"
+Good: spawn a subagent to scan them; it returns "retries live in lib/http/retry.ts:44" — that one line lands in the parent.
+```
+
+## Decision table: the window is filling — what do I do?
+
+| What is eating the window | Move | Concrete action |
+|---|---|---|
+| Bloated tool output / a giant pasted file or log | **Offload** | Distil to the load-bearing lines, write the full thing to a file, keep a `path:line` note. |
+| Stale early history, dead-end exploration | **Reduce** | `/compact` now (you're at ~60%, not 95%) with preserve instructions; keep decisions, drop the journey. |
+| A fact you need is simply not in the window | **Retrieve** | Fetch it on demand via `../rag/SKILL.md`; don't pre-load "just in case". |
+| A read-heavy or independent subtask | **Isolate** | Spawn a subagent (fresh window) via `../parallel/SKILL.md`; take back only the answer, never the transcript. |
+| The whole task won't fit any single window | **Hand off** | Write a progress file (below) so a fresh window resumes in one read. |
+
+## Compaction, concretely
+
+**Manual (`/compact`).** Do it early and tell it what to keep. A bare `/compact` will happily drop the file paths and decisions you needed.
+
+```text
+/compact keep: the migration plan, every file path touched, the three decisions
+(use Drizzle, keep the legacy table read-only, cut over Friday), and the open TODOs.
+drop: the exploratory diffs and the debugging transcript.
+```
+
+**Server-side (beta).** The API can compact for you: beta header `compact-2026-01-12`, edit type `compact_20260112`, default trigger at `input_tokens` = **150,000** (min 50,000), `pause_after_compaction` defaults `false`. The API drops all blocks before the compaction block and continues from the `<summary>` — and you must append the *whole* response (including the compaction block) to subsequent requests (Claude API "Compaction" docs, accessed 2026-06-02). The exact contract and the append rule are version-specific and rot fastest, so they live in `references/handoff-and-compaction.md` — read it before you wire this up.
+
+**A good summary preserves** decisions, file paths, open TODOs, and gotchas/constraints. **A good summary drops** raw logs, dead-end exploration, and redundant restatements. If the summary can't resume the task, it failed.
+
+## Surviving a fresh window (handoff discipline)
+
+When the task is bigger than one window, the win is making a *fresh* window resume the work in a single read. The long-running harness pattern (Anthropic, "Effective harnesses for long-running agents", published 2025-11-26, accessed 2026-06-02) is: an initializer session sets up the work, then each coding session works **one unit at a time** and leaves a structured update — a progress log (e.g. `claude-progress.txt`) plus git history plus a structured feature list — so the next window reconstructs state without you re-explaining it.
+
+Write the handoff *before* you run out of room, not after quality already cratered. The template (Goal / Done / In-progress / Next / Gotchas / Key paths) is in `references/handoff-and-compaction.md`.
+
+## Budget allocation heuristic
+
+A starting split for a production agent's window — a **heuristic, not a law** (context-engineering production guidance, accessed 2026-06-02). Tune to your task; the point is to leave headroom and trigger reduction well before 100%.
+
+| Slice | Rough share |
+|---|---|
+| System / instructions | ~10–15% |
+| Tool definitions & results | ~15–20% |
+| Knowledge / RAG injections | ~30–40% |
+| Working headroom (kept clear) | the rest — defend it |
+
+## Anti-patterns
+
+| Anti-pattern | Why it rots | Do instead |
+|---|---|---|
+| Read the whole repo into context "to be safe" | Thousands of irrelevant tokens degrade every later turn | Read the files the task touches; leave path notes for the rest |
+| Compact only at 95% when things break | The rot already happened; you're summarising damaged reasoning | Compact at ~60%, before quality drops |
+| Let tool results pile up verbatim | Stale outputs from 10 turns ago still taxing attention | Offload to a file, keep the distilled fact + path |
+| Re-explain the plan every turn | Burns the same tokens repeatedly and invites drift | State it once; keep it in the progress file, reference it |
+| Paste a subagent's full transcript back into the parent | Defeats the entire point of isolation — the child's bloat lands in the parent | Take back only the answer/artifact, never the transcript |
+| Treat the window as infinite because the model "has 1M" | Context rot scales with tokens regardless of the limit | Budget against attention, not the advertised ceiling |
+| Carry dead-end exploration forward | The journey isn't the decision; it's pure noise | Reduce to the conclusion + the commit that proves it |
+
+## Reference
+
+`references/handoff-and-compaction.md` — the server-side compaction API contract (exact header, edit type, trigger defaults/min, `pause_after_compaction`, the append-the-block rule, default summary prompt), a copy-paste progress-file template, and a good-vs-bad summary checklist. Offloaded here because it's API-version-specific and rots fastest.

package/skills/context-budget/evals/README.md

@@ -0,0 +1,11 @@
+# Evals: context-budget
+
+`cases.yaml` is read by the repo's eval runner. The `should_trigger` and `should_not_trigger`
+sets check routing: each `should_trigger` prompt should select this skill, and each
+`should_not_trigger` near-miss should route to the named sibling (`route_to`) instead — those
+boundaries against `cost-tracking`, `rag`, `parallel`, and `prompt-engineering` are the ones
+that actually get confused. The single `capability` case is a rubric-graded scenario: an agent
+facing an ~85%-full window must pick the right moves (offload + compact early), write a resumable
+handoff, and isolate the read-heavy step to a subagent; grade its response against `must_include`
+with an LLM judge or a human. This is a process skill, so there is no `verify.sh` to run — the
+rigor lives in the capability rubric, not a script.

package/skills/context-budget/evals/cases.yaml

@@ -0,0 +1,40 @@
+skill: context-budget
+
+should_trigger:
+  - prompt: "We're 80% through context, compact before it breaks."
+    why: Explicit utilisation trigger — the core ask is when/how to reduce a filling window.
+  - prompt: "This refactor will span days — make it survive across fresh sessions."
+    why: Harness/handoff trigger; the task is bigger than one window and needs resumable state.
+  - prompt: "The agent keeps re-reading the same files and forgetting decisions it made earlier."
+    why: Non-obvious symptom phrasing — context rot described with zero token vocabulary.
+  - prompt: "Se está llenando el contexto, ¿qué guardo y qué tiro?"
+    why: Spanish, what-to-keep-vs-drop framing — the keep/offload/drop decision is exactly this skill.
+  - prompt: "Should I spawn a subagent for this huge log read or just inline it?"
+    why: Isolation decision — whether to keep a read-heavy subtask out of the live window.
+
+should_not_trigger:
+  - prompt: "Cap our Claude API spend at $200/month and alert me at 80%."
+    route_to: cost-tracking
+    why: This is money — pricing and budget caps in dollars, not working-memory quality.
+  - prompt: "Pull the right design-doc sections into context with embeddings."
+    route_to: rag
+    why: Retrieval is how you find context to inject, not how much you let live or when to evict.
+  - prompt: "Split these 4 independent modules across agents and reconcile the results."
+    route_to: parallel
+    why: Fan-out/partition-then-gather discipline, not single-window budgeting.
+  - prompt: "Rewrite this prompt so the model returns cleaner JSON."
+    route_to: prompt-engineering
+    why: Prompt text and output format, not the context budget.
+
+capability:
+  - scenario: >
+      Mid-task in a long refactor. The window is ~85% full, someone pasted a 3,000-line build
+      log into the conversation, and the plan has visibly drifted (you've restated it twice and
+      contradicted an earlier decision). The next step is to read 8 more files to find where
+      retries are configured. Decide what to do.
+    must_include:
+      - Names the right moves explicitly — offload the build log to a file/summary and compact early.
+      - Writes a resumable handoff note covering goal, decisions, current state, next step, and key paths.
+      - Isolates the next read-heavy step (the 8-file scan) to a subagent instead of inlining it into the live window.
+      - Does NOT advise "the window is big, just keep going."
+      - References the ~60% compact-early discipline rather than waiting for 95%.

package/skills/context-budget/references/handoff-and-compaction.md

@@ -0,0 +1,96 @@
+# Handoff and compaction (the version-specific detail)
+
+This file holds the material that rots fastest — the exact server-side compaction API
+contract and the concrete templates. Re-verify the numbers against the live docs before you
+quote them; they are dated, not eternal.
+
+## Server-side compaction API contract
+
+Source: Claude API "Compaction" docs, accessed 2026-06-02.
+
+- **Beta header:** `compact-2026-01-12`
+- **Edit type:** `compact_20260112`
+- **Default trigger:** `trigger.type = "input_tokens"`, `trigger.value = 150000` (minimum allowed: `50000`)
+- **`pause_after_compaction`:** defaults `false` (the model continues straight from the summary)
+
+### Behaviour you must account for
+
+1. When the trigger fires, the API emits a **compaction block** and **drops all blocks before it**, continuing from the `<summary>` it produced.
+2. You must **append the whole response — including the compaction block — to subsequent requests.** If you strip the compaction block, the next request loses the summarised state. This is the easiest thing to get wrong.
+3. The summary is generated by a default prompt that distils the prior turns into a `<summary>`; you can steer what it preserves the same way you steer a manual `/compact` (keep decisions, paths, TODOs).
+
+### Minimal request shape (illustrative)
+
+```json
+{
+  "betas": ["compact-2026-01-12"],
+  "context_management": {
+    "edits": [
+      {
+        "type": "compact_20260112",
+        "trigger": { "type": "input_tokens", "value": 150000 },
+        "pause_after_compaction": false
+      }
+    ]
+  }
+}
+```
+
+Treat the field names as version-stamped: the `compact_20260112` suffix *is* the version. When
+the beta graduates or revs, this block changes — do not assume it.
+
+## Progress-file template
+
+Drop this in the workspace (e.g. `claude-progress.txt` or `PROGRESS.md`) and rewrite it before
+you run low on window. A fresh session should resume from this in a single read.
+
+```markdown
+# Progress: <task name>
+
+## Goal
+<one or two sentences — what "done" looks like>
+
+## Done
+- <unit completed> — proof: <commit hash / file path / test name>
+- ...
+
+## In progress
+- <the one unit currently open> — current state: <where it stands>
+
+## Next
+1. <the very next concrete step>
+2. <then this>
+
+## Gotchas / constraints
+- <non-obvious thing that will bite a fresh window>
+- <decision that must not be relitigated, and why>
+
+## Key paths
+- <path:line> — <what lives there>
+- ...
+```
+
+Rules:
+
+- **One unit at a time.** Close a unit, record its proof (a commit hash beats a paragraph), then open the next.
+- **Proof over prose.** "Done: auth migration — commit a1b2c3d, tests in auth/migrate.test.ts" beats three paragraphs describing it.
+- **Write it before you need it.** A handoff written at 60% is calm and complete; one scrambled at 97% is missing the gotchas.
+
+## Good vs. bad summary checklist
+
+A summary (manual `/compact`, server-side, or a handoff note) is judged by one question:
+**can a fresh window resume the task from it alone?**
+
+**Keep (load-bearing):**
+
+- Decisions made, and the one-line reason for each.
+- Every file path touched, with `path:line` where it matters.
+- Open TODOs and the next concrete step.
+- Constraints and gotchas a fresh window can't re-derive.
+
+**Drop (noise):**
+
+- Raw tool logs and full command output.
+- Dead-end exploration ("tried X, didn't work" collapses to one line, not the transcript).
+- Redundant restatements of things already captured.
+- Pleasantries and meta-commentary about the process.

package/skills/continuous-learning/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: continuous-learning
+description: "Use when something went wrong, got corrected, surprised you, or otherwise taught the workspace something and you want it to stick — a retro or postmortem after an incident or sprint, the same agent mistake corrected 2+ times, a wrong assumption that just surfaced, a resolved bug worth never repeating, or scattered notes-to-self that need a durable home. Triggers: 'run a retro', 'capture this lesson', 'write this down so we don't repeat it', 'you keep doing X — make it stop for good', 'harvest the corrections and notes-to-self into wherever they belong', 'guarda esta lección para que no vuelva a pasar', 'apúntalo para no repetir el error'. NOT capturing a forward design choice with alternatives (that is decision-records)."
+tags: [learning, retro, postmortem, feedback-loop, knowledge, meta]
+recommends: [decision-records, author-skill, debug, harness, knowledge-ops]
+origin: risco
+---
+
+# Continuous learning — the feedback loop of the harness
+
+This is the engine that makes the system get better every time it is wrong. When something broke, got corrected, surprised you, or simply taught the workspace something, your job is to **catch that lesson and route it back into the durable apparatus so the same mistake cannot recur**.
+
+One premise is load-bearing: **a lesson that lives only in chat is gone at the next compaction.** Verbal reflection only changes future behaviour when it is persisted to memory the agent actually reads next time (this is the Reflexion mechanism — self-reflection written to durable memory, not held in the conversation). In this harness, "memory" is a concrete set of surfaces: a `SKILL.md` body, `02-DOCS/wiki/harness/decisions.md`, `02-DOCS/wiki/harness/user-profile.md`, a root `CLAUDE.md` rule, or a `verify.sh` check. **Chat is not memory.** A lesson is "captured" only when it has landed in one of those.
+
+You sit between three siblings. `harness` self-improves the *wiki*. `decision-records` captures *forward* choices (we will do X, here is why). You capture *backward* lessons — what we now know that we didn't, and the cheapest durable place to keep it from biting again. You do not own the craft of editing skills (that is `author-skill`) and you do not diagnose bugs in the moment (that is `debug`); you run *after* debug resolves and harvest the root cause.
+
+## Read the user profile first
+
+Before you narrate anything, read `02-DOCS/wiki/harness/user-profile.md` for the **accompaniment dial**, same convention as every harness skill:
+
+- **L0** — capture the lesson silently, land the durable write, move on. No play-by-play.
+- **L1–L2** — state the root cause and the home in a line or two.
+- **L3** — walk the root-cause reasoning out loud and confirm the durable home with the user before writing.
+
+The dial governs narration only. The capture loop runs at every level — the difference is how much you say while doing it.
+
+## When to use
+
+- A retro / postmortem: "what did we learn from this incident or this sprint".
+- A recurring correction — the user has fixed the same agent mistake 2+ times ("you keep doing X — stop").
+- A surprise: an assumption was wrong, a command failed in a non-obvious way, a provider behaved unexpectedly, an eval missed a real bug.
+- After `debug` resolves: distil the non-obvious root cause into a durable note before it evaporates.
+- A periodic sweep: harvest scattered corrections / TODOs / notes-to-self into their right durable homes.
+
+## When NOT to use
+
+- **A forward decision with alternatives** (we chose X over Y, here is why) → `../decision-records/SKILL.md`. A choice is not a lesson from a mistake.
+- **Authoring/editing a skill's body, description, or evals** as the task → `../author-skill/SKILL.md`. You *decide* a lesson belongs in skill Z and hand the edit over; you do not own SKILL.md craft.
+- **Diagnosing the bug right now** → `../debug/SKILL.md`. You come after.
+- **Generic doc/wiki consolidation or inbox sweep** → `../harness/SKILL.md` 02-DOCS engine. You produce the occasional wiki article *via* that protocol; your trigger is "we learned something the hard way", not "organise these docs".
+- **Scheduling a recurring task** → `loop` / `schedule` harness CLI. You may *recommend* a cadence; you are not a scheduler.
+- **Curating reference knowledge / "what do I know about X"** → `../knowledge-ops/SKILL.md`. That is reference knowledge; you handle experiential, mistake-derived knowledge.
+
+| Situation | Owner | Why |
+|---|---|---|
+| "We chose Postgres over Mongo, here's the why + the rejected options" | `decision-records` | forward choice with alternatives |
+| "The migration failed because Postgres rejects NULL on the PK — never assume that again" | `continuous-learning` | backward lesson from a mistake |
+| "Find the bug causing the 500" | `debug` | in-the-moment diagnosis |
+| "Now that debug found it, make sure we never ship that pattern again" | `continuous-learning` | post-resolution capture |
+| "Write the SKILL.md and evals for pr-describe" | `author-skill` | skill craft |
+| "This lesson means the deploy skill needs a new guardrail" | `continuous-learning` → hands edit to `author-skill` | decides home, delegates craft |
+
+## The capture loop
+
+Five steps. Run them in order; do not stop before step 5.
+
+1. **Harvest** — pull the lesson out of chat *now*, while it is still in context. *Why:* the next compaction deletes it for free.
+2. **Root-cause, blameless** — name the *system* gap: a missing rule, a wrong assumption, an under-specified skill, an absent guardrail. Never "the agent is careless" or "the user keeps forgetting". *Why:* blame indicts a person and the loop stops running; blameless framing focuses on contributing causes and keeps the retro honest (Google SRE / Atlassian blameless postmortem practice).
+3. **Route to a durable home** — pick the *cheapest surface that will fire next time* (table below). Prefer the **preventative** write that kills the whole class of failure over a one-off note that just records it. *Why:* good postmortems split mitigative-vs-preventative action items, and the preventative one is what stops recurrence.
+4. **Write it** — land the entry in that surface in the lesson format below. If the home is a skill body, a description, or an eval, **delegate the edit to `author-skill`** — you decide the home, it does the craft.
+5. **Verify it fires** — prove the lesson is live (see "Verify it fires next time"). *Why:* learning loops do not fail at the retro, they fail *after* it — at action-tracking and trend analysis (incident.io / Rootly 2025 SRE best-practice consensus). If you cannot point to where it fires, you have not captured it.
+
+## Routing decision table
+
+The single most important artifact in this skill. Pick the row, write to that exact home, hand off to that writer.
+
+| Lesson type | Durable home (exact path) | Who writes it |
+|---|---|---|
+| About the user (prefers X, hates Y, works this way) | `02-DOCS/wiki/harness/user-profile.md` | this skill |
+| A rule we keep breaking | root `CLAUDE.md` rule, or the relevant `SKILL.md` body | `author-skill` for the skill body; this skill for `CLAUDE.md` |
+| A pattern to ban | a `verify.sh` banlist/check on the owning skill | `author-skill` |
+| A missed-trigger insight (skill fired wrong / didn't fire) | a `should_not_trigger` (or `should_trigger`) eval case | `author-skill` |
+| A surprising fact / how a provider actually behaves | wiki article via the harness ingest protocol | `harness` |
+| A forward choice that surfaced mid-retro | punt to `decisions.md` | `decision-records` |
+| A one-off, low-stakes note | `02-DOCS/wiki/harness/decisions.md` append, or a topic note | this skill |
+
+Full catalogue with hand-off recipes and a worked end-to-end example is in `references/lesson-routing.md`. The body table is enough for routine cases; read the reference when the home or the hand-off is unobvious.
+
+## The "2+ recurrences ⇒ structural fix" rule
+
+First sighting of a lesson: a note is fine. **Second sighting of the same class: stop noting and build a guardrail** — a `CLAUDE.md` rule, a `verify.sh` check, or a `should_not_trigger` eval. A third note proves the second note did nothing.
+
+*Why:* this is exactly where learning loops die. Teams nail the postmortem and then fumble trend analysis — the recurring class never gets a structural fix, so it keeps recurring. The recurrence is the signal that prose has failed; answer it with a check, not another apology.
+
+## Lesson entry format
+
+Copy-pasteable and **situation-tagged**, so it retrieves on the trigger that matters — not as a vague blob nobody can act on (experiential memory works when entries are actionable and situation-tagged, not when they are similarity soup):
+
+```md
+## <date> — <short lesson title>
+- **Situation:** <when this fires / the trigger phrasing>
+- **We believed:** <the wrong assumption>
+- **Actually:** <what is true>
+- **Durable home:** <path + surface that now holds it>
+- **Fires next time via:** <rule / eval / verify.sh / Knowledge-map entry>
+```
+
+The last two lines are not optional. An entry with no durable home and no "fires next time" is a chat message with a date on it.
+
+## Verify it fires next time
+
+This is the rigor of this process skill, and it stands in for a `verify.sh` (this skill emits no checkable artifact of its own — see below). **Acceptance: you can point to a concrete place where the lesson now changes behaviour:**
+
+- a rule the agent reads on its next pass (`CLAUDE.md` or a skill body), or
+- an eval case (`should_not_trigger` / `should_trigger`) that would have caught the miss, or
+- a `verify.sh` check on the owning skill that fails on the banned pattern, or
+- a `## Knowledge map` entry pointing at the new wiki article.
+
+If you cannot name one of those, the lesson is not captured — keep going. Prefer a surface a human can review (a rule, an eval, a profile line) over an opaque store: a single agent reflecting alone can talk itself into a local optimum, so the durable write should be legible enough for a human to sanity-check.
+
+**This skill has no `scripts/verify.sh`.** Its output is a *routing decision plus a durable write into another surface*. The check that the lesson fires lives in *that target surface* — a `verify.sh` on the deploy skill, a `should_not_trigger` eval, a `CLAUDE.md` rule — not here. Its rigor is the capability eval, same as `decision-records`, `author-skill`, and `harness`.
+
+## Periodic retro sweep
+
+To harvest scattered corrections and notes-to-self on a cadence, do not reimplement a scheduler — recommend the `loop` / `schedule` harness CLI to run the sweep weekly. For pulling raw notes through `02-DOCS/inbox/` into the wiki, route the consolidation itself through `../harness/SKILL.md`; you only own the lessons that came from a mistake, not the general filing.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Lesson captured only in chat | lost at the next compaction | write it to a durable surface from the table |
+| "The agent/user is bad at X" | blame indicts a person; the loop stops running | name the *system* gap (missing rule, wrong assumption) |
+| Note added but it never fires | prose nobody reads next time is not a capture | attach a rule / eval / check, then verify it fires |
+| Re-noting the same class a 3rd time | the 2nd note already proved prose failed | build a guardrail on the 2nd sighting |
+| Hand-editing the SKILL.md yourself | you do not own skill craft | hand the edit to `author-skill` |
+| Capturing a forward choice here | that is a decision, not a lesson | route to `decision-records` |
+| A vague vector-blob note | won't retrieve, can't be acted on | situation-tag it in the entry format |
+| Starting to diagnose the bug | that is `debug`'s job | come here *after* it resolves, with the root cause |
+
+## Cross-references
+
+- `../decision-records/SKILL.md` — forward choices with alternatives.
+- `../author-skill/SKILL.md` — the writer for any lesson whose home is a skill body, description, or eval.
+- `../debug/SKILL.md` — in-the-moment diagnosis; you run after it.
+- `../harness/SKILL.md` — the wiki ingest/sweep engine and the durable surfaces you route into.
+- `../knowledge-ops/SKILL.md` — reference knowledge, as opposed to mistake-derived experiential knowledge.

package/skills/continuous-learning/evals/README.md

@@ -0,0 +1,16 @@
+# Evals — continuous-learning
+
+These cases are eyeballed against the SKILL.md description and body, not run by a
+harness. Two axes. **Triggering:** read each `should_trigger` prompt and confirm
+the description's "Use when …" / "Triggers:" clauses would route it here, and
+read each `should_not_trigger` prompt and confirm it routes to its `route_to`
+sibling instead (the `NOT … (that is decision-records)` boundary plus the
+when-NOT list should make every one of those a clean miss). **Capability:** walk
+the scenario through the body and check every `must_include` rubric item is
+satisfied — the blameless root cause, the 2+-recurrences structural fix, the
+routing to an exact durable path, the hand-off to `author-skill` for craft, the
+situation-tagged entry, and the "prove it fires next time" surface.
+
+There is no `scripts/verify.sh`: this is a process skill whose only output is a
+durable write into *another* surface, which is checked there (a rule, an eval, a
+verify.sh on the owning skill). Its rigor is the capability eval above.

package/skills/continuous-learning/evals/cases.yaml

@@ -0,0 +1,39 @@
+skill: continuous-learning
+
+should_trigger:
+  - prompt: "We just resolved that nasty outage. Run a quick retro so we actually learn from it."
+    why: "Canonical retro/postmortem moment — harvest the lesson into a durable home, not just talk about it."
+  - prompt: "You keep stripping the YAML frontmatter when you edit skills — I've fixed it three times now. Make it stop for good."
+    why: "Recurring correction past the 2+ threshold; 'make it stop for good' demands a structural guardrail, not another apology."
+  - prompt: "Apúntate esta lección para que no volvamos a cometer el mismo error con las migraciones."
+    why: "Spanish verbatim 'save this lesson so we don't repeat the migration mistake' — explicit backward-lesson capture."
+  - prompt: "Now that debug found the root cause, make sure we never ship this pattern again."
+    why: "Non-obvious post-debug capture; the teaching point is the boundary with debug — capture runs after diagnosis."
+  - prompt: "Sweep all the little 'note to self' corrections from this week into wherever they actually belong."
+    why: "Non-obvious harvest/route phrasing with no 'lesson' keyword; this is the periodic-sweep entry point."
+
+should_not_trigger:
+  - prompt: "Document why we chose Postgres over Mongo, with the options we rejected."
+    route_to: decision-records
+    why: "Forward choice with alternatives, not a backward lesson from a mistake."
+  - prompt: "Write the SKILL.md and the evals for a new pr-describe skill."
+    route_to: author-skill
+    why: "Skill craft; continuous-learning only decides a lesson belongs in a skill and hands the edit over."
+  - prompt: "Find why the checkout endpoint is returning 500."
+    route_to: debug
+    why: "In-the-moment diagnosis; capture comes after the root cause is found."
+  - prompt: "Set up a recurring weekly job that runs our retro automatically."
+    route_to: harness
+    why: "Scheduling cadence is the harness/loop CLI; this skill is not a scheduler, it only recommends a cadence."
+
+capability:
+  - scenario: "A user says: 'You've now twice deleted my .env when scaffolding a tool. I'm tired of catching it. Make sure this never happens again.' Show how continuous-learning captures it."
+    must_include:
+      - "Reads 02-DOCS/wiki/harness/user-profile.md for the accompaniment dial and adapts narration to L0–L3."
+      - "States the root cause blamelessly as a system gap (a missing guardrail), not 'I was careless'."
+      - "Applies the 2+-recurrences rule: this is the 2nd time, so a structural fix is required — not another apology or note."
+      - "Routes to the right durable home via the table: a root CLAUDE.md rule and/or a verify.sh check on the scaffolding skill, naming the exact path."
+      - "Delegates the actual SKILL.md / eval / verify.sh edit to author-skill where skill craft is required, rather than hand-editing it."
+      - "Writes the lesson in the situation-tagged entry format (situation, we believed, actually, durable home, fires next time)."
+      - "Proves it fires next time by pointing to the concrete surface (rule / should_not_trigger eval / verify.sh check) that catches the regression, and notes this skill emits no artifact of its own — the check lives there."
+      - "Keeps prose original in rsc voice; no copied signature artifacts."

package/skills/continuous-learning/references/lesson-routing.md

@@ -0,0 +1,106 @@
+# Lesson routing catalogue
+
+The body table covers routine cases. This is the exhaustive catalogue: every
+lesson archetype, its canonical durable home, the exact path, and the hand-off
+recipe (who edits, what the verify is). Read it when the home or the hand-off
+is unobvious.
+
+## Archetype → home → hand-off
+
+### About the user
+- **Looks like:** "I prefer X", "I always want Y", "stop asking me Z", a working
+  style you inferred from repeated corrections.
+- **Home:** `02-DOCS/wiki/harness/user-profile.md` (the living portrait).
+- **Who writes:** this skill, directly.
+- **Verify:** the next pass reads the profile and the behaviour changes. Confirm
+  the line is in the profile, not just the chat.
+
+### A rule we keep breaking (workspace-wide)
+- **Looks like:** "never commit to main", "always use absolute paths", "don't
+  touch `.env`".
+- **Home:** a rule under the relevant heading in the root `CLAUDE.md`.
+- **Who writes:** this skill (CLAUDE.md is harness-owned plain text, not skill
+  craft).
+- **Verify:** the rule is phrased as an imperative the agent can act on, and a
+  later pass that reads `CLAUDE.md` would catch the regression.
+
+### A rule that belongs to one skill
+- **Looks like:** "the deploy skill should always run a smoke check first".
+- **Home:** the owning skill's `SKILL.md` body (a rule line) and, if it bans a
+  pattern, a `should_not_trigger` or a `verify.sh` check.
+- **Who writes:** **`author-skill`** — you decide the rule belongs there and
+  hand over the edit. Do not edit the body yourself.
+- **Verify:** the rule appears in the body *and* an eval/check exists that fails
+  on the old behaviour.
+
+### A pattern to ban (code/config/copy)
+- **Looks like:** "never use `cd` in compound bash commands", "no `console.log`
+  in committed code", "ban the phrase 'leverage synergies'".
+- **Home:** a banlist/grep check in the owning skill's `scripts/verify.sh`.
+- **Who writes:** `author-skill`.
+- **Verify:** `verify.sh` exits non-zero on a file containing the banned
+  pattern, and exits 0 on a clean target.
+
+### A missed-trigger insight
+- **Looks like:** "the skill fired on a prompt it should have routed elsewhere",
+  "it failed to fire on this obvious phrasing".
+- **Home:** a `should_not_trigger` (with `route_to`) or `should_trigger` case in
+  the skill's `evals/cases.yaml`.
+- **Who writes:** `author-skill`.
+- **Verify:** the new case encodes the exact prompt that misfired.
+
+### A surprising fact / how a provider behaves
+- **Looks like:** "Stripe webhooks retry with exponential backoff for 3 days",
+  "this API rate-limits per-IP not per-key".
+- **Home:** a wiki article via the harness ingest protocol, linked from the
+  `## Knowledge map`.
+- **Who writes:** `harness`.
+- **Verify:** the article exists and the Knowledge map links it, so the next
+  skill working in that area reads it.
+
+### A forward choice that surfaced mid-retro
+- **Looks like:** the retro reveals you now need to *choose* something going
+  forward (architecture, vendor, approach).
+- **Home:** `02-DOCS/wiki/harness/decisions.md` as a decision record.
+- **Who writes:** `decision-records`. Punt cleanly — do not log a choice as a
+  lesson.
+
+### A one-off, low-stakes note
+- **Looks like:** a small observation with no recurrence risk and no class to
+  kill.
+- **Home:** an append to `02-DOCS/wiki/harness/decisions.md`, or a topic note in
+  the wiki.
+- **Who writes:** this skill.
+- **Verify:** lightweight — the note is durable and dated. If the same note
+  recurs, escalate it via the 2+-recurrences rule to a guardrail.
+
+## Worked example — the recurring `cd` mistake
+
+Trigger: "You keep running `cd somedir && cmd` in bash and it triggers a
+permission prompt every time. I've corrected this three times."
+
+1. **Harvest** — the lesson: compound `cd` in bash breaks the sandbox; use
+   absolute paths instead.
+2. **Root-cause, blameless** — *system* gap: no workspace rule forbids `cd` in
+   compound commands. Not "the agent is sloppy".
+3. **Route** — three sightings ⇒ structural fix, not a note. Two homes:
+   - a rule in root `CLAUDE.md`: "Never `cd` in a compound bash command; use
+     absolute paths." → written by this skill.
+   - optionally, a grep check in the owning tooling skill's `verify.sh` that
+     flags `cd .* &&` in committed scripts. → handed to `author-skill`.
+4. **Write** — land both, in the lesson entry format, with the durable home and
+   the "fires next time" line filled.
+5. **Verify it fires** — the `CLAUDE.md` rule is read on the next pass; the
+   `verify.sh` grep fails on a script containing `cd foo && bar` and passes on a
+   clean one. Now it is captured.
+
+Lesson entry that results:
+
+```md
+## 2026-06-02 — No `cd` in compound bash commands
+- **Situation:** writing or running bash that changes directory then runs a command
+- **We believed:** `cd dir && cmd` is harmless shorthand
+- **Actually:** it trips the sandbox permission prompt every time; absolute paths don't
+- **Durable home:** root `CLAUDE.md` rule + grep check in the tooling skill's verify.sh
+- **Fires next time via:** CLAUDE.md rule read each pass; verify.sh fails on `cd .* &&`
+```