I18n Translate

---
name: i18n-translate
category: workflow
description: Copywriting-grade, context-aware localization for any managed app - a transcreation loop (draft -> typed MQM estimate -> gated refine) with an engineering guardrail. Portable across i18n stacks via a per-repo contract artifact; keeps a glossary, per-locale style guides, and gold exemplar pairs in the target repo so run N+1 stays consistent with run N. Invoke with /i18n-translate <mode> [locale] [scope].
argument-hint: <mode> [locale] [scope]
memory: project
contexts: tracked
listing: on
version: 1.6.3
---

# i18n-translate — copywriting-grade, context-aware localization

Translate an app's source-language catalog into its other locales the way a
bilingual copywriter on the product team would — not a machine. The job is to
make each non-source locale read as if it were written first in that language,
in the product's voice, using the right domain terms, and never breaking the
format contract the target repo's build enforces.

This is a **transcreation** loop with an engineering guardrail, not a
find-and-replace. Word-for-word is the failure mode.

This skill is **portable**: nothing repo-specific lives in this file. Every
repo-specific fact — where the catalogs are, what the placeholder syntax is,
which commands gate correctness — lives in the target repo's
`docs/i18n/contract.md`, which the first run bootstraps (Phase 0). The method
below is the same everywhere; the contract is not.

---

## When to use

- "Translate the app to X" / "add language X" (a new locale).
- "Review/improve the Czech (or any) translations."
- "The German is machine-y, make it read natively."
- A periodic sweep for strings that drifted out of parity, were added in the
  source language only, or sit in a locale file as verbatim source-language text.

## When NOT to use

- Adding/renaming **source-language** keys — that's normal feature work. This
  skill *consumes* the source catalog as truth; it doesn't invent source copy.
  If the source copy is wrong or ambiguous, flag it, don't silently rewrite it.
- Non-user-facing strings: backend logs, telemetry breadcrumbs, console output.
- Content owned by another subsystem (e.g. email/SMS template bodies living
  outside the catalog) unless the contract says they're in scope.

---

## Phase 0 — the repo contract (`docs/i18n/contract.md`)

**Read it first. If it doesn't exist, discover and write it before translating
anything.** The contract is the repo-specific half of this skill: what would be
hardcoded in a vendored copy. It must answer, with verified paths and commands:

1. **Catalog layout** — where locale files live, which locale is the source of
   truth, how keys are structured (nested vs flat, sections/namespaces).
2. **Format system** — ICU MessageFormat? A bare `{var}` regex interpolator?
   gettext? Suffixed plural keys (`_one`/`_other`) selected by the call site?
   Spell out exactly what a translator may and may not touch: placeholder
   names, plural/select keywords, rich-tag names, HTML, emoji, separators.
3. **Plural mechanism** — whether the translator *expands* plural branches to
   the target language's CLDR categories (ICU) or the key set is **frozen** and
   a missing category must be *flagged*, never faked (suffixed keys).
4. **Fallback behavior** — does a missing/untranslated key fall back to the
   source language *silently*? If yes, key parity proves nothing about
   translatedness, and the `gaps` mode + an untranslated-values check are
   load-bearing.
5. **The gates** — every command that must pass before finishing (parity/ICU
   checks, typecheck, untranslated-value scan), plus any **post-edit build
   step** without which the edit is a silent no-op (e.g. a chunk-splitting or
   codegen script the runtime actually loads from).
6. **Key classes** (`translation-pipeline-topology/non-translatable-value-classification`)
   — four, never one "do-not-translate" flag: **locked** (target carries the
   source verbatim: brands, product nouns, protocol keywords), **ignored** (no
   target entry at all — absent, not empty), **preserved** (human-owned: keep
   what is there, else source; no machine pass writes it), **allowlisted**
   (explicit opt-in that beats the classifier). Plus the **pre-prompt
   classifier**: a whole value that is empty, numeric, boolean, an ISO date, a
   system identifier or a URL is not sent to the engine — its target entry is
   written as the source verbatim. Whole values only, never substrings; short
   all-caps tokens (*OK*, *NEW*) are words. Name the CI assertion that every
   excluded value is identical between source and target. Note product-name vs
   common-noun traps ("Personas" the app vs the plural noun — judge by call site).
7. **Call-site lookup** — how to find where a key renders (the `t()` idiom to
   grep for).
8. **Operational notes** — worktree/parallel-safety rules, dead-key detection,
   anything "learned the hard way" in this repo.

To discover it: read the i18n runtime source (the `t()` implementation and the
interpolator tell you the real rules, whatever the docs claim), the check
scripts, `package.json` scripts, and any existing `docs/i18n/`. Verify each
claim against code before writing it down. When a later run finds the contract
wrong or stale, fix the contract in the same change — it is a doc like any
other.

---

## The five artifacts (create once, maintain forever)

The memory that makes run N+1 consistent with run N. All live in the target
repo under `docs/i18n/` — they are project truth, not skill-internal state:

1. **`contract.md`** — the engineering contract (Phase 0, above).
2. **`glossary.md`** — the termbase. *What to call things.* One canonical
   translation per domain term per locale, plus the Do-Not-Translate list.
   Seed it from the product's domain nouns on bootstrap; add a row whenever you
   make a term decision mid-run so it sticks. One decision per term, applied
   everywhere.
3. **`style-<locale>.md`** — the voice guide. *How to sound.* Register (a B2B
   or developer tool usually takes formal address: Czech *vykání*, German
   *Sie*, French *vous*, Japanese *です・ます*), sentence case vs Title Case
   (most non-English UIs use sentence case), punctuation/typography (Czech
   `„…"` quotes, French narrow NBSP before `;:!?` and `« »` guillemets, CJK
   full-width punctuation, real ellipsis `…`, NBSP conventions), tone, loanword
   policy (decide per term IN THE GLOSSARY, be consistent), grammar traps a
   mechanical translation gets wrong (number agreement, aspect, gender for
   unknown referents), and length discipline for UI chrome.
4. **`source-defects.md`** — the defects you found in the SOURCE catalog while
   translating, and did not fix. Concatenated sentences, flat strings that need
   plurals, hardcoded currency or dates, one value carrying four claims,
   ambiguous copy that forced three locales to guess three different ways. These
   cap quality for every locale and are the user's to fix, so they need a durable
   home rather than a line in a chat message that scrolls away. Append per run,
   grouped by defect class, each row naming the key and the problem. **Find
   them mechanically too** (`copy-quality-gates/source-defects-from-cross-language-agreement`):
   group the deterministic-check failures by source key; a key failing in **two
   or more locales** (counting only locales where the check applies, never a
   pseudo-locale) is a source row listing the failing check per locale — file it
   before fixing any target. A two-model divergence
   (`translation-quality-measurement/context-sufficiency-signals`) is the
   model-based cousin, pointed at what that leaves; classify each flag as a
   source gap, a termbase choice or an engine error before filing it, because on
   one measured catalog three flags in four were not the source's. A run that
   reports zero source defects over thousands of keys did not look.
5. **`exemplars-<locale>.md`** — the gold pairs. *Register by demonstration.*
   ~8 source→locale pairs harvested from the locale's best already-reviewed
   strings, one per string class: button/CTA, heading, tooltip, error/status,
   empty-state **transcreation** (the money example — show the rhythm, not the
   words), a correctly localized plural, a public/end-user-facing string, a
   legal/consent string. Each pair carries a one-line "why this is right" note.
   In-domain exemplars are the best-evidenced quality lever after the glossary —
   a style guide *describes* the voice, exemplars *demonstrate* it. Keep the
   file at ~8; replace a pair only when a better one ships.

Before translating anything, **read them all**. Bootstrap any that are missing
(for exemplars on a brand-new locale: translate the 8 class-examples first,
polish them hard, seed the file from those).

### The registry language subject — the sixth anchor source (when linked)

If the project's `.ai/manifest.yaml` declares the `localization` knowledge domain,
the registry carries a **language subject** for each supported locale
(`knowledge/localization/<category>/<language>/` in the registry checkout named by
`registry.local`): a golden path plus techniques holding **anchored rules with
stable IDs** (`CS-NOM`, `DE-FORMAL`, `AR-BIDI-ISOLATE`, `JA-COUNTER`, …) — register,
plural/count agreement, typography, de-anglicization constructions, terminology
policy, each with provenance from a published style authority.

Division of labor: the registry subject holds everything true of the LANGUAGE for
any product; the repo's `style-<locale>.md` shrinks to the HOUSE deltas — register
choice within the language's options, house rulings that overrule the authority
(recorded, per the bundle's laws), product-specific length budgets. Do not restate
registry rules in the repo style guide; cite their IDs. In Pass A, walk the
subject's techniques for the string class at hand; in Pass B, **cite rule IDs as
anchors** in error records (`key · span · category · severity · CS-NOM · fix`); a
native rejection no registry rule explains is a candidate NEW rule — propose it
upstream to the registry subject rather than minting a repo-local orphan, unless
it is genuinely house-specific. In a fan-out, feed each worker its locale's
technique files — that is what lets a smaller model review at expert quality: the
expertise is in the bundle; the worker recognizes and cites.

**How the rules reach an engine** (`translation-pipeline-topology/prompt-context-contract`):
as a per-language instruction map keyed by locale, resolved **exact → regional
fallback → base language** (`pt-BR`, else another `pt-*`, else `pt`) — without
the order, a regional variant silently gets no rules. The text is the subject's
anchors plus the house deltas, compressed to the engine's instruction budget
(one vendor caps it at ten instructions of 300 characters): quality judgment
travels here, never as request fields. Register can also ride as a synthetic
locale modifier (a formal/informal variant) where the engine supports one.

---

## Modes (dispatch on the argument)

- **`review <locale> [scope]`** — audit EXISTING translations and fix them.
  The default when a locale already exists. `review` = Pass B + Pass C only.
  Optional key-prefix scope (e.g. `pipeline.controlCenter`).
- **`check [locale|all] [scope]`** — read-only: the contract's gates, the
  deterministic checks, the cross-locale source-defect finder and Pass B, then
  a report. **Writes nothing** — no catalog, no `review-`/`source-defects`
  file; proposed rows go in the report. The mode CI runs, and the one to run
  before deciding a refine pass is worth spending. `review` is the mode that writes.
- **`gaps [locale|all]`** — translate values that are still verbatim source
  language. Only meaningful when the contract says fallback is silent — there,
  **run `gaps` before `review`**: a polished 76% under a raw-English 24% is the
  wrong order.
- **`full <locale>`** — (re)translate every key for one locale (Pass A → B → C).
- **`sync [locale|all]`** — the incremental heartbeat: keys missing from the
  locale, plus keys whose source value CHANGED since the locale was last
  touched (`git log -1 --format=%cI <locale file>`, then diff the source
  catalog over that window; when history is ambiguous, review the whole
  namespace the changed key sits in — siblings move together).
- **`new <locale>`** — adopt a language: bootstrap `style-<locale>.md` + the
  glossary column + exemplars, register the locale wherever the contract says
  locales are declared, then translate every key. Before the first real locale,
  a pseudo-locale is the cheapest readiness test — no engine, no key
  (`translation-pipeline-topology/pseudo-localization-readiness`).

If no locale is given, operate on every non-source locale. **Log what you
skip** — a capped run that doesn't say so reads as "fully synced". Order a
`gaps`/`sync` queue by **relative staleness**: a key untranslated far longer
than its namespace's own rate goes first, and to the source-defect register if
translators keep skipping it.

---

## The method — a three-pass loop per namespace batch

Single-pass translation is a ceiling. Run every batch through
**draft → estimate → refine**: translate it, audit it with a typed error
rubric, then rewrite ONLY what the audit flagged. The gate is the point —
unanchored "look again and improve" loops measurably *degrade* strings that
were already right.

### Pass A — Translate

Machine translation fails because it translates the *string*; you translate the
string **in its place in the product**. Batch by namespace/section so a whole
surface stays coherent. For each key:

1. **Locate the use.** Grep the call site (the contract says how) and read
   enough of the component to answer: **element type** → register + length (a
   button a short imperative, a heading a noun phrase, an `aria-label` a
   descriptive sentence, an error calm and actionable, a placeholder an
   example); **audience** → operator vs end-user pages (different warmth);
   **siblings** → keys in one object are one UI cluster, translated as a set;
   **length budget** → in a chip or narrow column prefer the shorter idiom
   (German and French run 20–35% longer than English).
2. **Classify → strategy.** *UI chrome*: concise, the target OS/app idiom.
   *Body/marketing/empty-state*: **transcreate** — carry feeling and rhythm, not
   words. *Legal/consent*: precise, sober. *Status/errors*: plain, actionable.
3. **Apply glossary + style guide + exemplars.** Canonical term for every
   domain word; the locale's register, casing, punctuation, plural rules; write
   *toward* the gold pairs' voice. Keep the frame terse — a one-line persona
   ("bilingual product copywriter for a <locale> B2B SaaS") beats a long brief,
   and chain-of-thought does not help the translate step.
4. **Preserve the format skeleton** exactly as the contract defines it: every
   placeholder byte-identical, plural branches expanded or frozen per the
   contract, tags/HTML/emoji kept. Move placeholders to where the target
   grammar wants them — that is usually a different position than English.
5. **Sanity-read as a native.** Would a native speaker write this on a real
   product, or does it smell of source-language word order? If unsure, mark it.

**The request contract.** When Pass A is delegated — to an engine or a worker
agent — each unit travels with a declared field set, not ad-hoc prose
(`translation-pipeline-topology/prompt-context-contract`): the unit text; its
key; the human-written context note; the surface; sibling units; memory
matches **with their scores** (a match without a score reads as "copy this";
a fuzzy match is a suggestion, never a write, and short strings reuse only at
near-identity — `translation-pipeline-topology/fuzzy-reuse-under-a-threshold`);
the glossary terms **occurring in this unit**, not the glossary; the target's
plural categories and selection rule; deterministic check findings already on
the unit; the placeholder map (name, type, example); and the action — fill,
review or align. Two rules: whatever is mechanically derivable (plural rule,
placeholder map, findings, occurring terms) is **attached by the pipeline,
never asked of the writer**; and exemplars ride as **prior turns**, not system
prose — reject any example whose placeholder multiset does not survive the
round trip, or it teaches the engine to break the skeleton.

### Pass B — Estimate (typed MQM audit)

Fresh eyes on the batch Pass A just wrote — or, in `review` mode, on the
existing catalog. Audit each key and emit **zero or more typed errors**, not a
holistic verdict — error spans with category+severity correlate with native
judgment; "rate this 1–10" does not.

Per error record: `key · quoted span · category · severity · anchor · fix`.

Categories (MQM-derived):
- **accuracy** — mistranslation, omission, addition; wrong meaning in context.
- **terminology** — glossary term ignored, or one concept rendered two ways
  across the app.
- **fluency** — grammar (case, aspect, agreement), calque/source word order,
  register break (informal where the tool needs formal; stiff where an
  end-user page should be warm).
- **style** — reads translated rather than written; misses the exemplars' voice.
- **locale-convention** — Title Case aped from the source, wrong quote glyphs,
  straight `...` for `…`, missing NBSP, wrong/missing plural handling per the
  contract.
- **format** — lost/renamed placeholder, brace imbalance, translated syntax
  keyword, changed tag name. Always **critical**.
- **length** — visibly longer than source in a tight control.
- **leftover-source** — untranslated source text or a wrongly-translated brand
  term.

Severity: **critical** (wrong meaning, format break, legal/consent distortion) ·
**major** (a native speaker would stumble or be confused) · **minor** (polish).

**Every finding must cite an anchor** — a glossary row, a style-guide rule, an
exemplar, the contract's placeholder rules, a call-site length budget. A
finding with no anchor is taste, not an error; drop it or queue it for a
native. For high-visibility surfaces (nav, landing, empty states), ask one
extra localizer question per string: *would a native product team ship this
wording on this control?* — a style finding if the answer is no.

### Pass C — Refine (gated)

- Rewrite **only** keys with ≥1 **critical/major** error, feeding the error
  records into the rewrite. Re-check what you changed.
- **Minor**-only keys: apply the fix if mechanical (typography, casing);
  otherwise leave and note.
- Clean keys: **do not touch.** No drive-by rephrasing — churn on already-good
  strings is regression, not improvement.
- For genuinely ambiguous strings (a pun, a domain term with no settled local
  equivalent, a legal phrase), **don't guess silently**: apply your best
  version AND record it in `docs/i18n/review-<locale>.md` with its error
  record and severity, so a native speaker can triage. The user is not a
  native reviewer by default — surface these.

---

## Working at scale

- **Batch by namespace/section, not by string.** Load one section's source
  values + call sites, run the three passes on the whole cluster, write, move
  on. Keeps sibling grammar consistent and dodges the "lost in the middle"
  failure of one giant prompt. ~60–90 keys per batch is a good ceiling.
- **Group near-identical sources before assigning batches** — edit distance
  under ~30% of the longer string — so related strings share one context
  window instead of diverging in two and waiting for the consolidation pass.
- Keep key order identical to the source catalog for reviewable diffs; edit
  namespace-block by namespace-block.
- **Skip dead keys** if the contract provides a dead-key check — never spend a
  token on a string no user can see.
- A **workflow / ultracode** fan-out is the natural shape for a full
  multi-locale sweep: one agent per (locale × section) chunk, each fed the
  artifacts + call sites. Don't spin it up unprompted — offer it for big jobs.
- Never machine-blast a whole file in one edit; that's how silent format breaks
  and terminology drift ship.

### The central writer (non-negotiable in a fan-out)

**Agents never edit a catalog.** Two agents writing one JSON file silently lose
keys. Each agent writes its own scratch file; one script merges them and is the
only writer. Prefer **sparse patches** (only the keys and locales that changed)
for review passes, so a clean value cannot be accidentally rewritten and the
merge stays reviewable.

That merge script is a **gate, not a pipe.** It refuses to write unless, for
every proposed value: the key exists in the source catalog; every locale is
present and a string; the value compiles under the project's real ICU parser;
its placeholder and rich-tag set is byte-identical to the SOURCE value's; every
requested item came back non-empty; and any house typography rule holds. Run it
dry first, read the problem list, and only then write. Nothing else in this
method catches a renamed placeholder before it ships.

- **Identity tokens, not positions.** Every item carries its id in request and
  response; never re-associate by array order — one damaged item re-keys every
  later value, each plausible on its own. Prefer a transport the target's
  quotation marks cannot terminate (`translation-pipeline-topology/serialization-transport-safety`).
- **Per-item failure memory.** When the gate rejects an item, re-request only
  that item with a targeted instruction naming what was wrong ("placeholder
  `{count}` missing"); without it the same error is made over and over again.

Before scripting a bulk edit, check that the catalog **round-trips
byte-exactly** through your writer (for JSON: `JSON.stringify(obj, null, 2)`
plus the trailing newline); if not, edit surgically. A reformatted catalog
buries the real change in noise, and some sibling files must not be reformatted.

### Finish a fan-out with a terminology consolidation pass

Agents on disjoint namespace batches cannot see each other, so **the same concept
reliably picks up two words in two namespaces**. This is not a risk; it is what
happens. Budget the pass, find the drift mechanically, let judgment rule on it:

1. For each glossary row, find keys whose SOURCE value uses the term and check
   the locale value for the canonical rendering, matched on a
   **diacritics-folded stem** (inflection and compounds drown whole-word matches).
2. Hand the misses to one agent per locale as **candidates, not violations**,
   and say so. Most are legitimate: another sense, a sanctioned verb/noun split,
   a restructured sentence. ~1,400 candidates once yielded ~75 real fixes; the
   most valuable output was the reasoned "no sweep" on term after term.
3. Never let a script rewrite from this signal — a wrong sweep destroys a
   correct distinction, and a half-sweep is worse than the split it replaces.

### Coverage is self-reported, so verify it

An agent asked to audit 190 keys may audit 130 and report honestly that it did.
Ask each batch for the number it actually reviewed, compare with the batch size,
and **re-run the short batches** with inputs regenerated from the CURRENT catalog
(an original snapshot reverts the first pass's fixes), telling the re-run its job
is completeness and finding little is a success. Report the honest coverage number.

---

## Guardrails (learned the hard way)

- **The source locale is the source of truth.** Don't edit source values to
  make a translation easier; file them in `source-defects.md` (artifact 4).
- **Don't clobber good human translations.** In `review`/`sync`/`gaps`, change
  only what is wrong or missing; a wholesale overwrite of a reviewed catalog
  needs the user's OK first.
- **File hygiene** — valid JSON/format, UTF-8, real diacritics (`č`, `ř`, `ž`,
  not ASCII folds), the file's existing indentation, no trailing commas.
- **Emoji/symbols** in a value are content — keep them.
- **Numbers/dates/currency** are formatted at runtime — never hardcode a
  localized number; keep the placeholder and let the formatter do it.
- **Verify, don't assume.** A catalog that "looks translated" can fail a gate on
  one plural or render 24% source-language. Run every gate the contract lists.
- **Read the gate's exit code, not its tail.** `npm test | tail -5` reports
  `tail`'s status, always 0. Redirect to a file and check `$?`.
- **The glossary can be the thing that is wrong.** A row can name a word found
  NOWHERE in a coherent catalog. Count a row's occurrences before sweeping to
  match it; if the catalog wins, fix the glossary and say so in the row.
- **Look for a catalog duplicated outside the catalog** (a scoring rubric or
  schema pinned byte-identical by a test). Grep a distinctive phrase before
  changing source copy; the contract should name any such file.
- **Some findings are the source's bug, not the translation's.** When a locale
  looks wrong, check the call site before rewriting: a value concatenated as
  `{name} {predicate}` will read as gibberish in any language whose translation
  supplied its own subject, and the fix is the predicate form, not the words.
- **Known non-levers — don't drift into these.** Back-translation as a quality
  gate (fluent mistranslations round-trip cleanly; use it only as an
  omission/placeholder sanity check). Holistic 1–10 scoring (use typed errors).
  Long translation briefs (measured worse than a one-line persona). Extra
  refine loops beyond Pass C without new anchors (churn, not quality).

---

## Exit checklist

In `check` mode only the gates, the report and the summary apply — nothing written.

- [ ] Every gate in `docs/i18n/contract.md` passes, including post-edit build
      steps (a missed chunk-split/codegen ships a no-op).
- [ ] Touched locale files valid, same key order as source, proper diacritics.
- [ ] `docs/i18n/glossary.md` + `style-<locale>.md` updated with any new
      term/voice decisions; `exemplars-<locale>.md` exists and still holds the
      locale's best ~8; `contract.md` corrected if a run proved it stale.
- [ ] `docs/i18n/review-<locale>.md` updated: the strings worth a native second
      look, each with its typed error record and severity; anything
      capped/deferred named explicitly.
- [ ] The source-defect list written to `docs/i18n/source-defects.md` AND
      surfaced to the user (flag only — never fixed silently).
- [ ] If the run fanned out: a terminology consolidation pass ran, and its
      rulings (including every "no sweep" and why) are recorded in the glossary.
- [ ] Coverage counted, not assumed: reviewed-vs-batch-size compared, short
      batches re-run, and the honest percentage stated in the summary.
- [ ] One-line summary: locale(s), keys audited/translated/fixed by severity,
      # queued for native review, and % of the catalog actually covered.

When every box is checked, the locale should read like it was written by a
person who uses the product every day — and the build stays green.

---

## Periodic operation

`sync` (plus `gaps`, where fallback is silent) is the heartbeat:
- **On change**: wire the contract's parity + untranslated checks — or
  `/i18n-translate check all` — into pre-commit/CI; any finding is the cue to
  run `/i18n-translate sync`.
- **Engine quality from corrections you already make**
  (`translation-quality-measurement/engine-quality-from-reviewer-corrections`):
  keep each machine suggestion beside the reviewer's final text; approved
  unchanged is the ceiling, a rejected one scores its overlap with the final.
  Track the approved-unchanged rate per locale over time, split by suggestion
  source (memory vs engine), beside the count reviewed — a sustained drop is the
  earliest regression signal. A locale nobody reviews reports nothing, not "steady".
- **On a schedule** (weekly / before a release): `/loop` or `/schedule` around
  `/i18n-translate sync all`.
- **New market**: `/i18n-translate new <locale>` once; it then joins the
  rotation automatically.

ARGUMENTS: `<mode> [locale] [scope]` — e.g. `review cs pipeline.controlCenter`,
`check all`, `gaps all`, `full de`, `sync all`, `new pl`. Default with no mode: `review`
every non-source locale (after `gaps`, where the contract makes it relevant).

---

<!-- clause: knowledge-sync v2 - stamped by scripts/apply-skill-clauses.mjs from docs/skill-clauses/knowledge-sync.md; edit the template, then re-stamp -->
## Knowledge sync

This skill proposes and executes backlog items. Every item it proposes is judged against the standard this repo subscribes to, so a run moves the codebase toward the registry's golden paths and sends back what it learned - not toward a private notion of "better" that the next skill will undo.

**Subscription** - read once at the start of the run; degrade honestly, never invent a standard:
- `.ai/manifest.yaml` -> `registry.local` (default `../ai-registry`; `$AI_REGISTRY_DIR` wins) and `knowledge.domains` (the bundles this repo consumes - `software-engineering` for code, plus whatever else it declares). No registry declared -> skip this section and say `registry: none` in the run header.
- `.ai/registry-map.json` - the join between this repo's contexts and the bundle's subjects, with a per-pair state (`unknown` / `conformant` / `deviation` / `not-applicable`) that `/conform` fills in over time. Missing while `context-map.json` exists -> build it once, `node <registry>/scripts/build-registry-map.mjs --project <slug>`, and commit it: the map is the repo's subscription to the paths, and it is how a path improved for another project reaches this one. Missing both -> resolve through `<registry>/knowledge/<domain>/index.json` and say `registry: declared, unmapped`.
- The always-on rules `.claude/rules/ai-registry-*.md` carry the subject map. They orient; they do not replace the read below.

**Read before you propose.** For each context in scope, take its subjects from the map and read the golden path (`subjects[<slug>].file`, verbatim from the index - never a path built from a slug; bundles are nested) plus the techniques whose `use_when` matches what you are about to decide. Then every backlog item you emit names the technique it serves or violates - `standard: <subject>/<technique>` - or `standard: none` when nothing governs it. A pair the map already marks `deviation` is a pre-approved item with its fix described; a pair marked `conformant` is a regression guard on anything you change there. A deviation is a finding: never lower the standard to fit the code, and never present a technique's number as a rule - the technique carries the rule, the application carries the measurement.

**Log the read** - one line per context, append-only, to `.ai/consults.jsonl` in the task's MAIN checkout (never a disposable worktree), written before the run's first commit - pre-commit consult checks read it: `{"ts":"<ISO>","bundle":"<domain>","subjects":["<slug>"],"techniques":["<slug>"],"deviations":<n>}`, where `deviations` counts the items this run raised that a technique explicitly names. Bare slugs, never paths. The registry's `signals-collect.mjs` folds these into `signals/` as counts only; it is the only way the corpus learns which paths are load-bearing and which are decoration.

**Send back what a LANDED fix taught.** When a change you made and verified generalizes past this repo - a rule that would transplant to an unrelated team, a case where a technique's rule broke against real code, or a place this repo does it BETTER than the golden path - append one line to `.ai/registry-leads.jsonl`: `{"ts":"<ISO>","bundle":"<domain>","nearest":"<subject-slug or null>","kind":"technique|application|subject","claim":"<when X, do Y, because Z - one sentence>","because":"<what this run measured or broke and fixed>","confidence":"low|medium|high","from":"i18n-translate@<version>"}`. Earned only: it came from code you changed, not from a fix you proposed. A lead ORIGINATES a finding and never authorizes one - nothing here edits a bundle; the registry's `leads-collect.mjs` -> `librarian/inbox.md` -> `/intake` decides what survives. Say in the report that you filed one, and say plainly when you filed none. Verdicts on a pair's state belong to `/conform`: close by naming the contexts you touched so it can re-judge them.
<!-- /clause: knowledge-sync -->

<!-- clause: skill-reflection v6 - stamped by scripts/apply-skill-clauses.mjs from docs/skill-clauses/skill-reflection.md; edit the template, then re-stamp -->
## Skill Reflection

After the work, record only useful observations supported by this run. No lesson is
a valid result. Reflection inherits the task's authorization; it grants no additional
permission to edit another repository, send data, commit, or publish.

**Run log.** Unlike a lesson, this is written on every run that started work - failed and
aborted runs included; skip read-only info modes and runs cancelled before any work. Append
ONE line to `.ai/skill-runs.local.jsonl` at the root of the task's MAIN checkout: local,
gitignored run output inside the task's own repository, never a write into the registry.
A run that worked in a linked worktree logs in the main checkout that worktree belongs to
(`git rev-parse --git-common-dir`, minus `/.git`) - a disposable worktree takes the line
with it when it is removed. `log-run.mjs` resolves this on its own.
The registry pulls it later (`/librarian skills` on the same machine). When a registry
checkout is reachable (`registry.local` in `.ai/manifest.yaml`), prefer its writer, which
stamps project, device and version for you:

```sh
node <registry>/scripts/log-run.mjs --skill i18n-translate --outcome <o> --difficulty <1-5> \
  --provider <claude|openai|xai|qwen|google|other> --model <your model id> [--effort <level>] \
  [--tokens-est <n>] --result "<one sentence>" --comment "<self-reflection>"
```

Otherwise write the line yourself: `{"ts":"<ISO, UTC Z>","skill":"i18n-translate","outcome":…,
"difficulty":…,"provider":…,"model":…,"effort":…|null,"tokensEst":…|null,"result":…,"comment":…}`.

- `outcome`: `shipped` (the goal landed) / `partial` / `no-op` (ran correctly, nothing to
  do) / `parked` (designed or staged, deliberately not landed) / `failed` / `aborted`.
- `difficulty` rates the task as this run met it: 1 trivial - mechanical; 2 routine - the
  method as written; 3 demanding - real judgment calls or one detour; 4 hard - dead ends,
  rework or an operator course-correction; 5 at the edge - partial or failed on the merits.
- `model`/`effort` as your harness states them (`null` effort when you cannot see it).
  `tokensEst` is the drop in the harness's remaining-token counter since this skill was
  invoked, or `null` (with `log-run.mjs`, omit `--tokens-est`); exact figures are measured
  later from transcripts - never guess one.
- `result` is one line (max 240 chars). `comment` (max 2000) is the self-reflection a
  reviewer reads: what worked, what the method made harder, where its instructions were
  wrong, missing or ignored. No filesystem paths or email addresses.
- Never read run logs during a run. They are evidence ABOUT this skill for its reviewer;
  an executor that reads its own diagnosis contaminates the next measurement.

**Project learning.** Only when this run produced an observation that would change how a
future run behaves. A run that went as the method describes writes nothing: an entry that
restates the procedure, records "no issues", or repeats the task is a defect, not a
deliverable. When there is such an observation and local edits are within scope, put one
dated line in the overlay this skill's `## Project overlay` section names, under
`## Skill improvement log`. **Write only into an overlay that already exists.** If the
project has none, put the observation in the response instead - creating a new tracked
file for a reflection is scope the task did not ask for, and a reader who never asked for
the skill has to review it. If the overlay is a structured config (YAML, TOML, JSON),
record the note as comments so the file keeps parsing, or use the response.
Use a supplied memory contract only when its destination and writes are authorized.
Keep project details out of the shared method.

**Method learning.** Identify the installation before editing anything. A local
`.ai/registry-installation.local.json` receipt can identify development versus release,
the registry revision, and selected skill versions. Verify any link's actual target;
do not assume a skill directory is a writable registry link.

- For a pinned release, marketplace cache, ordinary copy, or unknown installation,
  keep a proposal in the project overlay or response. Do not edit the installed method
  or silently relink it. Adoption and rollback are explicit installation operations.
- For a development link, edit the registry only when that checkout is already within
  the accepted task scope. Otherwise report a proposal. Authorized changes belong in
  the source checkout, followed by its gates; commit only when the task authorizes it.
- Record an actual lesson in `LESSONS.md` against the version **used**:
  `## <version-used> - <YYYY-MM-DD> - <project-name>` and concise bullets. A proposal
  must be labeled as such; structural checks are not evidence of field effectiveness.
- Applied skill changes require a version bump: patch for wording, minor for a step
  refinement, major for method redesign. A lesson alone needs no bump. Shared stamped
  clauses are edited in the registry's `docs/skill-clauses/` and regenerated with
  `scripts/apply-skill-clauses.mjs`, never patched in individual installed skills.

**Domain learning.** Follow `## Knowledge sync` when present, within the same scope
and privacy boundaries. A method lesson and a domain knowledge lead are different
artifacts; do not fabricate either to fill a reflection quota.
<!-- /clause: skill-reflection -->