@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/i18n-localization/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: i18n-localization
+description: Internationalises an application so it can ship in more languages and regions, by moving user-facing text into message catalogs, writing ICU MessageFormat messages with plural and select rules, formatting dates, numbers, currency and lists through locale-aware APIs, making layouts work right-to-left, testing with pseudo-localisation, and keeping translation keys in sync across locales. Use when adding a second language or locale to an app, setting up i18next, react-intl, vue-i18n, gettext, Android or iOS string resources, fixing plurals or currency that read wrong in one language, or adding Arabic or Hebrew support.
+license: MIT
+compatibility: Any Agent Skills host. Examples use JavaScript Intl and ICU MessageFormat; the rules apply to any i18n library or platform.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# i18n and localisation
+
+Make the app translatable once, correctly, so each new locale is a translation job and not a code change. For library-specific syntax and setup, read `references/libraries.md`.
+
+## 0. Before you start
+
+1. Find what the project already uses: search for `i18next`, `react-intl`/`@formatjs`, `vue-i18n`, `next-intl`, `gettext`/`.po` files, `res/values*/strings.xml`, `Localizable.strings`/`.xcstrings`, Rails `config/locales`, or a hand-rolled `t()` helper. **Use the existing system.** Never add a second one.
+2. If there is none, recommend one that fits the stack (see `references/libraries.md`) and **stop and ask the user** before adding a dependency.
+3. Ask, if not stated: target locales, the source locale, who translates (people, a translation platform, machine translation with review), and whether locale comes from the URL, user profile or `Accept-Language`.
+
+## 1. Externalise strings
+
+- Every user-visible string goes into the catalog: labels, buttons, errors, empty states, emails, push notifications, `alt`, `title`, `aria-label`, `placeholder`, page titles, and validation messages from the server.
+- Not translated: log messages, identifiers, CSS class names, enum values stored in the database, analytics event names.
+- Key names describe meaning and place, not the English text: `checkout.summary.total`, not `total_colon`. Don't reuse one key for two contexts that look the same in English ("Open" as verb and as status).
+- Add a translator description to any key whose meaning isn't obvious from its text, including what each placeholder holds.
+- Server-side errors return a code plus parameters; the client turns the code into a message. Don't send English sentences over an API for display.
+
+## 2. Write whole messages, never concatenations
+
+- Never build a sentence from pieces: `t('hello') + ' ' + name + '!'` and `"You have " + n + " items"` break in languages with different word order. Use one message with named placeholders: `Hello, {name}!`.
+- Don't put formatted values together with `+` either; pass raw values as arguments and let the message format them.
+- Markup inside a sentence (a link, bold text) stays inside the message as a tag the library supports (`<link>terms</link>` in react-intl, `<0>…</0>` in react-i18next `Trans`), so translators can move it.
+- Gender or variant wording uses `select`: `{gender, select, female {She replied} male {He replied} other {They replied}}`.
+
+## 3. Plurals
+
+- Use the library's plural support; never `n === 1 ? 'item' : 'items'`. Languages use up to six CLDR plural categories: `zero`, `one`, `two`, `few`, `many`, `other`. English uses `one` and `other`; Arabic uses all six; Japanese uses only `other`.
+- ICU form: `{count, plural, =0 {No messages} one {# message} other {# messages}}`. `#` is the locale-formatted number. `other` is required.
+- `=0` is an exact-match override, not a category. `one` is not "exactly 1" in every language (for example, in Russian `one` also covers 21, 31...), so never use `one` to mean "singular" in logic.
+- Ordinals ("1st", "2nd") use `selectordinal`, or `Intl.PluralRules(locale, { type: 'ordinal' })`.
+- When a translator adds a category your source lacks (Polish `few`, `many`), the catalog must accept it. Check that your extraction and validation tooling does not strip unknown categories.
+
+## 4. Locale-aware formatting
+
+Use platform formatting with the active locale; never hand-format. In JavaScript:
+
+| Value | API |
+|---|---|
+| Number, percent | `new Intl.NumberFormat(locale).format(n)`, `{ style: 'percent' }` |
+| Currency | `new Intl.NumberFormat(locale, { style: 'currency', currency: 'EUR' })` |
+| Date and time | `new Intl.DateTimeFormat(locale, { dateStyle: 'medium', timeStyle: 'short', timeZone })` |
+| "3 days ago" | `new Intl.RelativeTimeFormat(locale, { numeric: 'auto' })` |
+| "A, B and C" | `new Intl.ListFormat(locale, { type: 'conjunction' })` |
+| Sorting | `new Intl.Collator(locale).compare` (never default `Array.prototype.sort` on display text) |
+| Plural category | `new Intl.PluralRules(locale).select(n)` |
+
+Rules:
+
+- **Currency is data, not locale.** Store amount and ISO 4217 code together; the locale only decides how it's displayed. Never derive the currency from the user's language.
+- Store timestamps in UTC; format in the user's time zone. Date-only values (birthdays) must not be shifted by time zone.
+- Don't parse user-typed numbers with `parseFloat`: `1.234,5` is valid German. Use a locale-aware input or a single agreed format.
+- Hard-coded patterns like `MM/DD/YYYY`, `toFixed(2)` for display, and `'$' + amount` are bugs.
+- Cache formatter instances; constructing `Intl.*` objects in a hot render loop is slow.
+
+## 5. Right-to-left (Arabic, Hebrew, Persian, Urdu)
+
+1. Set `lang` and `dir="rtl"` on `<html>` from the active locale (or `android:supportsRtl="true"` on Android; iOS mirrors automatically with leading/trailing constraints).
+2. Replace physical CSS with logical properties: `margin-inline-start` not `margin-left`, `padding-inline-end`, `inset-inline-start`, `border-inline-start`, `text-align: start`. In Tailwind use `ms-*`, `me-*`, `ps-*`, `pe-*`, `rtl:`/`ltr:` variants, and for insets `start-*`/`end-*` (v3.3 to v4.1) or `inset-s-*`/`inset-e-*` (v4.2+, where `start-*`/`end-*` are deprecated).
+3. Mirror direction-bearing icons (back/forward arrows, chevrons, progress) but not logos, media playback controls, clocks or checkmarks.
+4. User-generated or mixed-direction text: use `dir="auto"` on the element, or `<bdi>` around an interpolated name, so a Latin username doesn't scramble an Arabic sentence.
+5. Numbers, phone numbers and code stay left-to-right inside RTL text.
+6. Check flex `row` order, absolutely positioned elements, transforms (`translateX`), and canvas or SVG drawing, which logical properties don't flip.
+
+## 6. Pseudo-localisation
+
+Run the UI in a pseudo-locale before real translations exist. It exposes hard-coded strings (unchanged English), truncation (translations into German or Finnish often run a third longer than English, and short labels can double), concatenation and encoding bugs.
+
+- Generate an accented, padded locale: `Settings` → `[Šéţţîñĝš one two]`. FormatJS: `formatjs compile --ast --pseudo-locale en-XA` (also `en-XB`, `xx-LS`, `xx-AC`, `xx-HA`); Android: `pseudoLocalesEnabled true` in the build type gives `en-XA` and `ar-XB`.
+- Add a bidi pseudo-locale (or `ar-XB`) to test RTL with readable text.
+- Walk every changed screen at mobile width. Anything still plain English is a missed string.
+
+## 7. Translation workflow and keeping keys in sync
+
+1. The source locale is the only catalog developers edit by hand. Other locales come from translators or the translation platform.
+2. Extract keys from code with the library's extractor (`formatjs extract`, `i18next-cli` (the replacement for the deprecated `i18next-parser`), `xgettext`, Xcode string catalog sync) instead of maintaining them by hand.
+3. Add a check to CI that fails when:
+   - a key used in code is missing from the source catalog;
+   - a key exists in a locale catalog but not in the source (orphaned);
+   - a translation's placeholders differ from the source (`{name}` renamed or dropped);
+   - a message fails ICU syntax parsing.
+4. Missing translations fall back through a defined chain (`pt-BR` → `pt` → source locale) at runtime and are reported, never shown as raw keys.
+5. When English text changes meaning, change the key (or mark translations as needing review), so stale translations don't ship silently.
+6. Never machine-translate straight into production catalogs for legal, medical, financial or safety text; a fluent human reviewer must approve those.
+
+## Never
+
+- Never concatenate translated fragments or format values with string operations.
+- Never detect language from IP address or country alone; let users choose and remember their choice.
+- Never use flags to represent languages.
+- Never put translatable text in images, or truncate text with fixed-width containers.
+- Never lowercase or uppercase translated strings in code without the locale (`toLocaleUpperCase(locale)`: Turkish dotted i).
+
+## Report back
+
+End with:
+
+- **Strings externalised:** count and files touched.
+- **Formatting changed:** which values moved to locale-aware APIs.
+- **RTL:** done, partial or not in scope, and what was checked.
+- **Sync check:** the command added or run and its result.
+- **Open items:** strings not externalised, locales without translations, anything needing a translator or reviewer.

package/skills/i18n-localization/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "We need to launch our React dashboard in French and German, set up translations for it",
+    "Our plural messages say '1 items' and break in Polish, fix the pluralisation with ICU",
+    "Add Arabic support to the web app including right-to-left layout",
+    "Prices show as $ even for EUR customers, make currency and date formatting locale-aware",
+    "Set up pseudo-localisation and a CI check that our translation JSON files stay in sync with the source keys"
+  ],
+  "should_not_trigger": [
+    "Review this pull request for hard-coded strings and broken plurals before it merges",
+    "Audit the signup form for WCAG keyboard and screen reader problems",
+    "Write the README for our CLI tool in plain English",
+    "Rewrite our marketing copy so it sounds consistent with our brand voice",
+    "Convert all timestamps in the orders table from local time to UTC in a database migration"
+  ]
+}

package/skills/i18n-localization/references/libraries.md

@@ -0,0 +1,52 @@
+# i18n libraries: syntax and setup notes
+
+Read the section for the library the project already uses. Check the installed version's docs before relying on a detail here.
+
+## FormatJS / react-intl (ICU MessageFormat)
+
+- Messages are ICU: `{count, plural, one {# file} other {# files}}`, `{role, select, admin {...} other {...}}`, `{rank, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}`.
+- Components: `<FormattedMessage id="..." defaultMessage="..." description="..." values={{ name }} />`; hooks: `useIntl().formatMessage(...)`, `formatNumber`, `formatDate`, `formatList`.
+- Rich text: `values={{ link: (chunks) => <a href="/terms">{chunks}</a> }}` with `<link>terms</link>` in the message.
+- Extract: `formatjs extract 'src/**/*.{ts,tsx}' --out-file lang/en.json`. Compile: `formatjs compile lang/fr.json --out-file compiled/fr.json` (add `--ast` for pre-parsed messages; `--ast --pseudo-locale en-XA` for pseudo-localisation).
+- `eslint-plugin-formatjs` can enforce `description`, placeholder use and no literal strings in JSX.
+
+## i18next / react-i18next / next-i18next
+
+- Not ICU by default. Interpolation is `{{name}}`. Use `i18next-icu` only if you want ICU syntax.
+- Plurals use key suffixes from `Intl.PluralRules`: `item_one`, `item_other` (plus `_two`, `_few`, `_many` where the language has them). Call `t('item', { count })`; the option must be named `count`. A `_zero` key, if present, is used for 0.
+- Ordinals: `t('place', { count, ordinal: true })` with `place_ordinal_one`, `place_ordinal_two`, `place_ordinal_few`, `place_ordinal_other`.
+- Context (gender etc.): `t('friend', { context: 'female' })` → `friend_female`.
+- Markup: `<Trans i18nKey="terms">Read the <0>terms</0></Trans>`.
+- Extraction: `i18next-cli` (`npx i18next-cli extract`), configured with the project's locales and namespaces. `i18next-parser` is deprecated and unmaintained since September 2025; `npx i18next-cli migrate-config` converts its config.
+- Set `fallbackLng`; enable `saveMissing` or a `missingKeyHandler` in development to report missing keys.
+
+## vue-i18n
+
+- `$t('key', { name })`, plurals with `$t('car', n)` and pipe-separated forms `no cars | one car | {n} cars`. `{n}` or `{count}` inserts the number. For languages whose forms don't fit the default order (Russian, Polish), supply a rule function per locale in `createI18n`: `pluralRules` with the Composition API, `pluralizationRules` with the legacy Options API.
+- `$d(date, 'short')` and `$n(amount, 'currency')` with `datetimeFormats` and `numberFormats` per locale.
+- Composition API: `const { t, d, n } = useI18n()`.
+
+## gettext (Python, PHP, C, many others)
+
+- `_("Text")`, `ngettext("%(n)d file", "%(n)d files", n)`, `pgettext("context", "Open")` for disambiguation.
+- Extract with `xgettext` (or Babel `pybabel extract`, Django `makemessages`), update with `msgmerge`, compile with `msgfmt`.
+- Plural forms are defined per language in the `.po` header `Plural-Forms:`.
+- Use named placeholders (`%(name)s`) so translators can reorder them.
+
+## Android
+
+- `res/values/strings.xml` for the source, `res/values-fr/strings.xml` etc. for others. Plurals: `<plurals name="files"><item quantity="one">%d file</item><item quantity="other">%d files</item></plurals>`, read with `getQuantityString(R.plurals.files, n, n)`.
+- Use positional args (`%1$s`) so translators can reorder.
+- RTL: `android:supportsRtl="true"`, `start`/`end` instead of `left`/`right`.
+- Pseudo-locales: `pseudoLocalesEnabled true` in a debug build type gives `en-XA` (accented) and `ar-XB` (bidi).
+
+## iOS / macOS
+
+- String Catalogs (`.xcstrings`, Xcode 15+) or `Localizable.strings` with `.stringsdict` for plurals. SwiftUI `Text("key")` looks up `LocalizedStringKey`; elsewhere `String(localized:)`.
+- Format with `FormatStyle` (`.formatted(.currency(code: "EUR"))`, `Date.FormatStyle`) or `NumberFormatter`/`DateFormatter` with the user's locale.
+- Use leading/trailing constraints for automatic RTL mirroring. Xcode scheme options include pseudo-languages such as double-length and right-to-left.
+
+## Rails
+
+- `config/locales/*.yml`, `t('.title')` with lazy lookup, plurals under `one:`/`other:` keys with `count:`. `l(date, format: :short)` and `number_to_currency` with the locale.
+- `i18n-tasks missing` and `i18n-tasks unused` (gem) check sync.

package/skills/incident-postmortem/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: incident-postmortem
+description: Blameless post-incident review writing that rebuilds a timestamped timeline from alerts, chat and deploy logs, quantifies customer and business impact, separates the trigger from root causes and contributing factors, records what went well and where the team got lucky, and turns findings into a short list of owned, dated action items with a follow-up review. Use when an outage, data loss, security event or near miss is over and someone needs the postmortem, incident report or retrospective written, reviewed or its action items tracked.
+license: MIT
+compatibility: Any Agent Skills host. Reads logs, chat exports or git history when the user provides them; git optional.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: docs
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Incident postmortem
+
+A postmortem explains what happened and changes the system so it does not happen the same way again. It is written after the incident is resolved. If the incident is still live, **stop**: the job is mitigation, not writing. Say so and help with diagnosis or the relevant runbook instead.
+
+## Blameless rules (apply to every sentence)
+
+- Describe actions and the information people had at the time, not character. "The deploy ran against prod because the target defaulted to prod" not "Sam deployed to prod by mistake".
+- Use roles ("on-call engineer", "incident commander") instead of names in the narrative. Names belong only in the action-item owner column.
+- Ask "why did this make sense at the time?" Human error is a starting point for analysis, never a root cause.
+- Do not write "should have", "failed to" or "carelessly". Rewrite as a gap in tooling, process, alerting or knowledge.
+
+## 0. Gather inputs
+
+1. Ask for or locate: alert history, the incident channel or chat export, deploy and config change history (`git log` around the window), dashboards or graphs, support tickets, status page updates.
+2. Confirm severity and who the audience is (engineering only, whole company, customers). A customer-facing summary is a separate, shorter document; offer it, do not mix the two.
+3. If any input contains customer personal data, secrets or tokens, leave them out of the document and tell the user.
+
+## 1. Summary
+
+Three to five sentences anyone in the company can read: what users saw, for how long, the cause in plain words, and whether it is fixed.
+
+## 2. Impact
+
+Quantify with sources. Use what you can measure; mark estimates as estimates.
+
+- Duration: start of impact, detection, mitigation, full resolution (UTC).
+- Who and how many: users, accounts, regions, requests failed, error rate.
+- Business: orders lost, SLA or SLO budget burned, refunds or credits, data lost or exposed.
+- If data was lost or exposed, or a contract SLA may be breached, flag that legal, security or account teams must review before publishing.
+
+## 3. Timeline
+
+UTC timestamps, one event per line, facts only. Include the trigger, first symptom, detection, every key decision, each mitigation attempt (including ones that did not work) and resolution.
+
+```
+2026-03-04 14:02 UTC  Config change merged raising pool size (trigger)
+14:09  p99 latency on checkout-api rises above 2 s
+14:21  Alert "checkout 5xx > 2%" pages on-call (detection: 12 min after impact)
+14:30  Incident declared SEV2, commander assigned
+14:38  Rollback of config attempted; no effect (pods not restarted)
+14:51  Pods restarted, error rate back to baseline (mitigated)
+15:30  Monitoring confirms steady state (resolved)
+```
+
+Compute and state, all measured from the start of impact (first symptom, not the trigger): time to detect, time to mitigate, time to resolve. In the example: 12, 42 and 81 minutes. If the team measures from another point, say which.
+
+## 4. Root causes and contributing factors
+
+- Separate the **trigger** (the change or event that set it off) from **root causes** (conditions that let the trigger cause harm) and **contributing factors** (things that made it worse or slower to fix).
+- Work backwards with repeated "why" questions, but follow every branch, not one chain. Most incidents have several causes. Stop a branch when you reach something the team can change.
+- Check each category: change management, testing, alerting and detection, capacity, dependencies, documentation and runbooks, access and tooling, communication.
+- Each cause must be supported by evidence in the timeline. If it is a hypothesis, label it as one and add an action item to confirm it.
+
+## 5. What went well, what went poorly, where we got lucky
+
+Short bullets for each. "Lucky" items are real risks that did not bite this time; they usually deserve action items too.
+
+## 6. Action items
+
+Each item fixes a cause or contributing factor, and the table must show which.
+
+```
+| # | Action | Type | Addresses | Owner | Due | Ticket |
+|---|--------|------|-----------|-------|-----|--------|
+| 1 | Alert on checkout p99 > 1 s for 5 min | Detect | CF2 | <person> | 2026-03-18 | OPS-412 |
+| 2 | Config changes to pool size trigger rolling restart | Prevent | RC1 | <person> | 2026-03-31 | PLAT-88 |
+```
+
+Rules:
+
+- Types: Prevent, Detect, Mitigate, Process. Prefer system changes over "be more careful" or "add a reminder to the wiki".
+- Every item has one named owner, a due date and a ticket. "Team" is not an owner.
+- Keep it short: five to ten items that will actually be done beat thirty that will not. Mark each as must-do or nice-to-have.
+- If an item has no owner, list it under "Unowned" and **ask the user** who takes it.
+
+## 7. Follow-up
+
+- Schedule a review date (often two to four weeks out) to check action items are closed.
+- Note whether the runbook used during the incident needs updating; the `runbook-writing` skill covers that.
+- Record where the postmortem is published and who must sign off before it goes wider.
+
+## Output format
+
+```
+# Postmortem: <short title> (<date>, <severity>)
+Status: Draft | In review | Final   Authors: <roles or names>   Incident commander: <role>
+## Summary
+## Impact
+## Timeline (UTC)
+## Root causes and contributing factors   (RC1.., CF1.., trigger)
+## What went well / What went poorly / Where we got lucky
+## Action items   (table)
+## Follow-up      (review date, sign-off, related docs)
+## Appendix       (graphs, log excerpts, links)
+```
+
+## Reviewing a draft postmortem
+
+Report problems most serious first: blame language, missing impact numbers, timeline gaps (no detection time), a single "root cause" that is really the trigger or human error, action items without owner, date or link to a cause, and missing follow-up date.
+
+## Never
+
+- Never name an individual as the cause.
+- Never invent timestamps, impact numbers or log lines. Leave a `TODO: confirm` where data is missing.
+- Never publish customer data, credentials or internal hostnames in a customer-facing version.
+- Never close the postmortem with action items still unowned.

package/skills/incident-postmortem/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "Yesterday's checkout outage is resolved. Write the blameless postmortem from this Slack export and the deploy log",
+    "Turn our incident channel notes into a timeline with time to detect and time to mitigate, plus root causes",
+    "Review this incident report draft, I think it blames the on-call engineer and the action items have no owners",
+    "We had a near miss where a migration almost dropped the users table; write it up as a post-incident review"
+  ],
+  "should_not_trigger": [
+    "The API is returning 500s right now, help me figure out what's wrong",
+    "Write a runbook for what on-call should do when the disk-full alert fires",
+    "Plan a canary rollout with automatic rollback for the new payment service",
+    "Write a handoff note so tomorrow's session can continue this refactor"
+  ]
+}

package/skills/inventory-demand-planning/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: inventory-demand-planning
+description: Inventory and demand planning for stocked SKUs, from cleaning sales history and picking a simple forecast to sizing safety stock for a target service level, setting reorder points and order quantities from lead times, ranking items with ABC analysis, and weighing stockout cost against overstock cost, built as a spreadsheet or a small script. Use when deciding how much stock to hold or when to reorder, building a replenishment model or reorder report, or explaining why a SKU keeps running out or piling up.
+license: MIT
+compatibility: Any Agent Skills host. Works with a spreadsheet, CSV exports or a short script in the project's language; no external services.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: business
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Inventory and demand planning
+
+Answer two questions per SKU and location: **when to reorder** (reorder point) and **how much** (order quantity), with a safety stock that matches a stated service level. Keep the model simple enough that the planner can audit every cell.
+
+Formulas, z-values and a worked example are in `references/formulas.md`. Read it before writing any formula.
+
+## 0. Gather inputs, or stop and ask
+
+For each SKU (and each warehouse if stock is not shared) you need:
+
+1. Demand history at a fixed grain (daily or weekly units), ideally 12+ months to see seasonality.
+2. Lead time from order to available-to-sell, in the same time unit, with its variability if the supplier is unreliable.
+3. Unit cost, holding cost rate (typically quoted as a % of unit cost per year), and ordering cost per purchase order.
+4. Constraints: MOQ, case pack, pallet or container quantity, shelf life, budget or space caps.
+5. The service-level target and who owns it.
+
+If lead time, MOQ or the service-level target is missing, **stop and ask the user**. Do not invent supplier terms.
+
+## 1. Clean demand before forecasting
+
+- Use **demand, not sales**. Days with zero stock show zero sales but not zero demand; flag them and either exclude them or estimate lost sales.
+- Remove or tag one-offs: bulk B2B orders, promotions, data errors, returns booked as negative sales.
+- Keep units consistent (eaches vs cases). Note any SKU replacements and join their history.
+
+## 2. Forecast with the simplest method that works
+
+| Pattern | Method |
+|---|---|
+| Stable, no trend | Moving average (4 to 12 periods) or simple exponential smoothing |
+| Trend | Holt (double) exponential smoothing |
+| Clear seasonality, 2+ years of data | Seasonal index on top of a baseline, or Holt-Winters |
+| Intermittent (many zero periods) | Croston-style or just a min/max rule; do not fit a smooth curve |
+| New item, no history | Analogue SKU scaled by the user's launch estimate; mark it as a judgement |
+
+Backtest on a holdout (the last 8 to 13 weeks): report MAE and bias per SKU. A forecast with persistent bias is worse than a noisy one; fix bias first. Do not pick a complex model unless it beats the moving average on the holdout.
+
+## 3. ABC (and XYZ) classification
+
+1. Rank SKUs by annual consumption value (annual units x unit cost).
+2. A = top ~80% of value, B = next ~15%, C = rest. These cut-offs are conventions; confirm them with the user.
+3. Optional XYZ by demand variability (coefficient of variation) so A-X items get tight control and C-Z items get simple rules.
+4. Use classes to set service levels and review frequency, for example A 98%, B 95%, C 90%, and review A items weekly.
+
+## 4. Safety stock, reorder point, order quantity
+
+1. Pick the service-level type and say which: **cycle service level** (probability of no stockout per cycle) is what the z-score formula gives. Fill rate is different and needs the loss function.
+2. Safety stock from the formula in `references/formulas.md`, including lead-time variability when the supplier is late often.
+3. Reorder point = expected demand over lead time + safety stock (add the review period for periodic review).
+4. Order quantity: EOQ as a starting point, then round up to MOQ and case pack, and cap by shelf life and budget.
+5. Compare **inventory position** (on hand + on order - backorders - allocated), not on-hand, with the reorder point.
+
+## 5. Stockout vs overstock trade-off
+
+- State both costs per SKU: stockout = lost margin + expediting + customer churn; overstock = holding + obsolescence + markdown.
+- For seasonal or perishable one-shot buys use the newsvendor critical ratio: underage cost / (underage + overage cost).
+- Show the user a table of service level vs average inventory value; let them choose. Going from 95% to 99% usually costs far more stock than 90% to 95%.
+
+## 6. Build the model
+
+Spreadsheet layout: one inputs sheet (per SKU parameters), one demand sheet (history, cleaned flags), one calc sheet (forecast, sigma, SS, ROP, EOQ), one output sheet (reorder report). No hard-coded numbers inside formulas; reference input cells.
+
+In code: read CSV exports, compute per SKU, write a reorder report CSV. Add a test on one hand-checked SKU (the worked example in `references/formulas.md`).
+
+## Rules
+
+- Never place or change purchase orders, or write to an ERP or store inventory system, without the user's explicit go-ahead.
+- Never treat stockout periods as zero demand.
+- Never mix time units: demand per week with lead time in days is the most common bug.
+- Do not promise a service level the data cannot support; say when history is too short.
+
+## Report
+
+```
+SKU | class | avg demand/period | sigma | lead time | service level | safety stock | reorder point | order qty | on hand | position | action
+```
+
+Then: method used and holdout MAE/bias, assumptions the user must confirm, SKUs with too little data, and the stock-value impact of the chosen service levels.

package/skills/inventory-demand-planning/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Work out safety stock and reorder points for our 400 SKUs from this weekly sales CSV",
+    "Build me a replenishment spreadsheet that tells the buyer when to reorder and how many cases",
+    "Do an ABC analysis of our product range and suggest service levels per class",
+    "Our best seller keeps stocking out even though the supplier lead time is only three weeks, what is wrong with our reorder rule?",
+    "How much extra stock does going from 95% to 99% service level cost us on the A items?"
+  ],
+  "should_not_trigger": [
+    "A pallet of our goods arrived damaged, help me file a claim with the freight carrier",
+    "Sequence next week's jobs across our three CNC machines to cut changeovers",
+    "Set up grading rules for returned items so we know what to restock and what to scrap",
+    "Find the right HS code for our stainless steel water bottles before we ship to Canada",
+    "Build a revenue dashboard with weekly active customers and churn"
+  ]
+}

package/skills/inventory-demand-planning/references/formulas.md

@@ -0,0 +1,62 @@
+# Inventory formulas
+
+Use one time unit (days or weeks) for every term.
+
+## Symbols
+
+- `d` average demand per period, `sigma_d` standard deviation of demand per period
+- `L` average lead time in periods, `sigma_L` standard deviation of lead time
+- `R` review period (periodic review only)
+- `z` standard normal quantile for the cycle service level
+- `D` annual demand, `S` cost per order, `H` holding cost per unit per year (= unit cost x holding rate)
+
+## z for cycle service level
+
+| CSL | z |
+|---|---|
+| 90% | 1.28 |
+| 95% | 1.645 |
+| 97.5% | 1.96 |
+| 98% | 2.05 |
+| 99% | 2.33 |
+| 99.5% | 2.58 |
+
+Spreadsheet: `=NORM.S.INV(0.95)`. Python: `scipy.stats.norm.ppf(0.95)` or `statistics.NormalDist().inv_cdf(0.95)` (standard library).
+
+## Safety stock
+
+- Demand varies, lead time fixed: `SS = z * sigma_d * sqrt(L)`
+- Both vary (independent): `SS = z * sqrt(L * sigma_d^2 + d^2 * sigma_L^2)`
+- Periodic review: replace `L` with `L + R`.
+
+These assume roughly normal demand. For intermittent or very skewed demand, use an empirical percentile of lead-time demand from history instead.
+
+## Reorder point
+
+- Continuous review: `ROP = d * L + SS`
+- Periodic review order-up-to level: `S_max = d * (L + R) + SS`; order `S_max - inventory position`.
+
+## Economic order quantity
+
+`EOQ = sqrt(2 * D * S / H)`
+
+Round up to MOQ and case pack. EOQ is flat near its optimum, so rounding costs little.
+
+## Newsvendor (single buy)
+
+Critical ratio `CR = Cu / (Cu + Co)`, where `Cu` = margin lost per unit short and `Co` = cost per unit left over (cost minus salvage). Order the demand quantile at `CR`: `Q = mean + z(CR) * sigma` for normal demand.
+
+## Forecast accuracy
+
+- `MAE = mean(|actual - forecast|)`
+- `Bias = sum(forecast - actual) / sum(actual)`; positive means over-forecasting.
+- Avoid MAPE on low-volume SKUs; zero actuals make it undefined.
+
+## Worked example (use as a test case)
+
+Weekly demand `d = 100`, `sigma_d = 20`, lead time `L = 4` weeks fixed, CSL 95% (`z = 1.645`).
+
+- `SS = 1.645 * 20 * sqrt(4) = 65.8`, round up to 66
+- `ROP = 100 * 4 + 66 = 466`
+
+With `D = 5200`, `S = 50`, unit cost 10, holding rate 25% (`H = 2.5`): `EOQ = sqrt(2 * 5200 * 50 / 2.5) = sqrt(208000) = 456.1`, so about 456 before rounding to case pack.

package/skills/investor-materials/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: investor-materials
+description: Drafts startup fundraising documents, namely a pitch deck outline, a one-page investor summary and the recurring investor update, built around a clear narrative, the few metrics investors judge a company on, a specific ask and use of funds. Use when a founder is preparing to raise a seed or Series A round, writing to existing investors about progress, or wants a deck or one-pager reviewed for gaps and common fundraising mistakes.
+license: MIT
+compatibility: Any Agent Skills host. No tools required; uses the metrics and documents the founder provides.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: business
+  kete-loom/risk: read-only
+  kete-loom/owner: "Kete-org"
+---
+
+# Investor materials
+
+Help a founder tell a true, specific story that makes an investor want the next meeting. You draft structure and words; the founder owns every number and claim.
+
+## 0. Pick the document and collect facts
+
+Ask which of these is needed (often several):
+
+| Document | Purpose | Length |
+|---|---|---|
+| Pitch deck | Get and run the meeting | 10-15 slides plus appendix |
+| One-pager | Cold or warm intro, forwardable | One page |
+| Investor update | Keep current investors informed and helpful | One screen of email, sent on a fixed cadence |
+
+Collect before writing, and ask for anything missing:
+
+1. What the company does in one sentence, for whom, and why now.
+2. Stage, amount raised so far, the round being raised (amount, instrument such as a SAFE or priced round), and any committed investors.
+3. Real metrics with dates: revenue or MRR, growth rate, customers or users, retention, gross margin, burn and runway.
+4. Team: founders and why they are the right people.
+5. Target investors (stage, sector, geography).
+
+**Stop and ask** rather than fill a gap with an invented or rounded-up number. If a metric is weak, the narrative must deal with it honestly, not hide it.
+
+## 1. Narrative first
+
+Write the story in five sentences before any slide:
+
+1. The problem, for a specific customer, with evidence it hurts.
+2. The solution and what is different about it.
+3. Proof it is working (traction, the best single metric).
+4. Why this becomes big (market and business model).
+5. Why this team, and what this money achieves.
+
+Every slide must support one of these sentences. Cut slides that do not.
+
+## 2. Pitch deck outline
+
+Use this order unless the founder's strongest point should come earlier (often traction):
+
+1. **Title**: company, one-line description, contact.
+2. **Problem**: who has it, how they cope today, what it costs them.
+3. **Solution**: the product and the key insight. Show it (screenshot or demo flow).
+4. **Why now**: what changed (technology, regulation, behaviour, cost).
+5. **Traction**: one chart of the best metric over time, plus two or three supporting numbers.
+6. **Market**: bottom-up size (number of customers times price), not only a top-down headline figure. See the `market-research` skill for sizing.
+7. **Business model**: how you charge, price points, unit economics if known.
+8. **Competition**: honest map of alternatives, including "do nothing" and spreadsheets, and why customers pick you.
+9. **Go-to-market**: how customers are acquired today and how that scales.
+10. **Team**: relevant experience, not job-title lists.
+11. **The ask**: amount, instrument, what it funds, milestones it reaches and how many months of runway.
+12. **Appendix**: detailed financials, cohort data, product detail, for questions.
+
+Slide-writing rules: one message per slide, written as the slide headline ("Revenue grew 3x in 6 months", not "Traction"); numbers with dates and definitions; readable at a glance.
+
+Detailed slide prompts and a one-pager and update template are in `references/templates.md`. Read it when drafting the document itself.
+
+## 3. Metrics that matter
+
+Choose the ones that fit the business model and define each one:
+
+- **SaaS / subscription**: MRR or ARR, month-on-month growth, net revenue retention, logo churn, CAC payback, gross margin.
+- **Marketplace**: GMV, take rate, net revenue, repeat purchase rate, liquidity on both sides.
+- **Consumer**: active users (define active), retention cohorts, engagement frequency, organic share of acquisition.
+- **Fintech / payments**: total payment volume, revenue as a share of volume, loss and fraud rates, licences held.
+- **All**: burn, runway in months, revenue or usage concentration in top customers.
+
+Say "revenue" only for recognised revenue. Label bookings, pilots, letters of intent and GMV as what they are.
+
+## 4. The ask
+
+- State an exact amount or a narrow range, the instrument and the terms already agreed (for example a valuation cap on a SAFE).
+- Use of funds as three to five buckets with percentages that sum to 100.
+- Tie the money to milestones that make the next round possible, and the runway it buys.
+
+## 5. Investor update
+
+Send on a fixed cadence (monthly or quarterly), short, same structure every time:
+
+1. Headline: one-line summary of the period.
+2. Key metrics table, same metrics each time, with change versus last period.
+3. Wins.
+4. Challenges, stated plainly, with what you are doing about them.
+5. Asks: specific introductions, hires or advice.
+6. Cash and runway.
+
+Never skip bad months; consistency builds trust.
+
+## Common mistakes to flag when reviewing
+
+- No clear ask, or an ask with no milestones.
+- Top-down market size only ("1% of a $50B market").
+- Vanity metrics (downloads, sign-ups) without retention or revenue.
+- Undefined or cherry-picked metrics, or charts without axes and dates.
+- "No competitors".
+- Too much text; slides that need the founder to explain them.
+- Financial projections presented as facts.
+- Inconsistent numbers between deck, one-pager and data room.
+
+## Rules
+
+- Never invent, inflate or round up traction, revenue, customers, logos or committed investors. Misrepresenting facts to investors can be fraud.
+- Do not give legal, tax or securities advice; for instruments, terms and fundraising rules in the founder's jurisdiction, tell them to confirm with a lawyer.
+- Keep confidential figures out of anything the founder says will be shared publicly.
+
+## Output
+
+Deliver the requested document(s) in Markdown, followed by:
+
+```
+## Gaps and questions
+- <missing metric or claim that needs a source>
+## Review notes
+- <mistakes from the list above that apply, with the fix>
+```

package/skills/investor-materials/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "We're raising a $1.5M seed round. Help me outline the pitch deck.",
+    "Write our monthly update to investors: MRR is up 12%, we lost a big customer and runway is 14 months",
+    "Turn these notes into a one-page summary I can send to angel investors",
+    "Review my Series A deck and tell me what VCs will push back on",
+    "What metrics should a B2B SaaS startup put on the traction slide, and how do I phrase the ask?"
+  ],
+  "should_not_trigger": [
+    "Estimate TAM, SAM and SOM for a pharmacy inventory app in Nigeria with sources",
+    "Plan a launch campaign with a budget split across paid social and email",
+    "Write a long-form blog post on lessons from our first year as a startup",
+    "Define the voice and tone guidelines for our company's website copy",
+    "Prepare release notes for version 2.0 of our CLI"
+  ]
+}