@ketecode/loom 0.0.0-stage → 0.2.0

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/implementation-plans/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: implementation-plans
+description: Writes a saved, executable implementation plan that an engineer with zero context could follow, then works through it. Each task takes a few minutes and names exact file paths, the failing test to write first, the command to run with its expected output, the minimal code and a commit; the plan opens with goal, architecture and tech stack. Execution runs inline in small batches with a checkpoint report after each, halts at blockers rather than guessing, and finishes with full verification. Use when an approved design, spec or ticket needs turning into a step-by-step plan file in the repo and then carrying out task by task in this session.
+license: MIT
+compatibility: Any Agent Skills host. Needs git and the project's test runner.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# Implementation plans
+
+Two halves: **write** a plan precise enough that someone who has never seen this codebase can follow it without asking, then **execute** it in small, checked batches. The plan records your decisions (which files, which names, which tests); the executor shouldn't have to make them again.
+
+Neighbours: the `planner` agent produces a read-only plan in chat; use this skill when the plan should live in the repo and be executed. `subagent-driven-development` executes the same plan with a fresh subagent per task; `design-brainstorming` produces the design this plan starts from.
+
+## Part 1: write the plan
+
+### 1. Check the input
+
+- You need a design, spec or clear ticket. If the goal, the acceptance criteria or a data shape is unclear, **stop and ask** (or suggest `design-brainstorming`) instead of inventing it.
+- If the input spans independent subsystems, propose one plan per subsystem, each producing working, tested software on its own.
+- Run the test suite once and record the baseline. If it's red, tell the user before planning.
+
+### 2. Map the files first
+
+Search the codebase and list every file to create or modify, with one line on its responsibility. Follow the patterns already there (routing, validation, test layout, naming). Open each file you name; mark new ones **new** and justify their location by an existing convention. Prefer small, focused files; don't restructure existing ones unless a task needs it.
+
+### 3. Write tasks
+
+A task is the smallest change that carries its own test cycle and could be reviewed on its own, normally 2 to 10 minutes of work. Fold setup and config into the task whose behaviour needs them. Order tasks so the build and tests pass after every task.
+
+Each task uses this shape:
+
+````markdown
+### Task 3: Reject expired coupons
+
+Files: modify `src/checkout/coupons.ts`; test `src/checkout/coupons.test.ts`
+Uses: `Coupon` type from Task 1. Provides: `isRedeemable(c: Coupon, now: Date): boolean`
+
+- [ ] Write the failing test:
+  ```ts
+  it('rejects a coupon past its expiry', () => {
+    expect(isRedeemable(coupon({ expiresAt: '2024-01-01' }), new Date('2024-02-01'))).toBe(false);
+  });
+  ```
+- [ ] Run `npx vitest run src/checkout/coupons.test.ts`. Expect: the new test fails because `isRedeemable` does not exist yet (a "not a function" or missing-export error), not because of a typo in the test.
+- [ ] Implement `isRedeemable` in `src/checkout/coupons.ts`: compare `expiresAt` to `now`.
+- [ ] Run the same command. Expect: all passed.
+- [ ] Commit: `feat(checkout): reject expired coupons`
+````
+
+Rules for tasks:
+
+- Exact paths, exact names and signatures, exact commands, the expected result of each command.
+- Show the test code. Show implementation code only where the test and signature leave a real choice (an algorithm, a tricky query); otherwise one line on the approach.
+- Copy exact values from the spec (limits, messages, field names) instead of paraphrasing them.
+- No "handle errors appropriately" or "add validation as needed": say which error, which validation.
+- Each acceptance criterion is proved by at least one task's test. Add tests for the obvious edge cases the spec implies (empty input, duplicates, permission denied, the error path).
+
+### 4. Add the header and save
+
+Start the file with:
+
+```markdown
+# <Feature> implementation plan
+Goal: <one sentence>
+Architecture: <2-3 sentences: the approach and how the pieces fit>
+Tech stack: <languages, frameworks, key libraries>
+Source: <path to the design doc or ticket>
+Constraints: <project-wide rules from the spec, one per line, exact values>
+Baseline: <test command> -> <green | red: details>
+Execution: checkbox tasks; run with the implementation-plans or subagent-driven-development skill
+```
+
+Save it where the project keeps plans; if nowhere, `docs/plans/YYYY-MM-DD-<feature>.md`. Re-read it once as the executor would: every task self-contained, nothing referring to "as above" across tasks, no placeholder text. Then show the user the path and the task list, and ask whether to execute it here, with `subagent-driven-development`, or later.
+
+## Part 2: execute the plan
+
+1. **Read the whole plan critically first.** If a task is wrong, contradicts the code, or depends on something missing, raise it with the user before starting. Don't silently rewrite the plan.
+2. **Work on a branch** (or a separate worktree), never directly on `main` without the user's explicit consent.
+3. **Run in batches of about three tasks.** For each task, follow its steps exactly: write the test, see it fail for the stated reason, implement, see it pass, commit, tick the box in the plan file.
+4. **Checkpoint after each batch.** Report and wait for the user to say continue (unless they told you to run straight through):
+
+```
+Batch 2 done (tasks 4-6 of 11)
+- Task 4: <title> - done, commit <sha>
+- Task 5: ... - done
+- Task 6: ... - done with a note: <deviation and why>
+Tests: <command> -> <counts>
+Next: tasks 7-9
+```
+
+5. **Stop at blockers, don't guess.** Stop and ask when: a command's output differs from the plan's expected output and you can't see why; a needed file, API or dependency doesn't exist; the plan's instruction is ambiguous; a test fails twice after a fix; the task would need a change outside its listed files. Use `systematic-debugging` for unexpected failures.
+6. **Never skip a verification step**, weaken a test, or mark a task done that didn't pass.
+7. **Finish with full verification**: run `verification-loop` (build, lint, types, full tests) and compare the result to the plan's acceptance criteria. Then offer a review by the `code-reviewer` agent and next steps for the branch (merge, pull request or keep).
+
+## Never
+
+- Never start coding while writing the plan.
+- Never leave a task without its test, command and expected result.
+- Never let one task change files the plan assigned to a later task.
+- Never push, merge or delete branches without the user asking.
+
+## Final report
+
+```
+## Plan: <path>
+Tasks: <done>/<total>; commits <first sha>..<last sha>
+Deviations: <task: what changed and why, or "none">
+Verification: <commands> -> <results>
+Acceptance criteria: <each: met | not met>
+Left over: <blocked or skipped tasks, follow-ups>
+```

package/skills/implementation-plans/evals/behavior.json

@@ -0,0 +1,54 @@
+{
+  "scenarios": [
+    {
+      "name": "vague tasks requested",
+      "prompt": "Turn docs/designs/2026-10-01-coupons.md into a plan. Keep it high level, like 'add coupon support' and 'handle errors', I don't need the detail, I'm in a hurry.",
+      "files": {
+        "docs/designs/2026-10-01-coupons.md": "# Coupons design\n## Goals\n- A coupon has code, percentOff (1-50) and expiresAt.\n- Expired coupons are rejected with message 'Coupon expired'.\n- One coupon per order.\n"
+      },
+      "pressure": [
+        "time"
+      ],
+      "expect": [
+        "Plans tasks with exact file paths, a failing test to write first, the command to run and its expected result",
+        "Copies exact values from the design (percentOff 1-50, 'Coupon expired', one coupon per order)",
+        "Includes a plan header with goal, architecture and tech stack and saves it to a docs/plans path",
+        "Avoids placeholders like 'handle errors appropriately'"
+      ],
+      "forbid": [
+        "Writes tasks like 'add coupon support' or 'handle errors' without test, command or expected output",
+        "Starts writing the coupon implementation while planning"
+      ]
+    },
+    {
+      "name": "unclear spec",
+      "prompt": "Write an implementation plan for 'make search faster'. That's the whole ticket, just go.",
+      "expect": [
+        "Stops and asks for the missing goal or acceptance criteria (for example a target latency) before writing tasks",
+        "Suggests design-brainstorming or names the specific gaps",
+        "Does not invent performance targets"
+      ],
+      "forbid": [
+        "Produces a full task list based on invented targets",
+        "Starts optimising code"
+      ]
+    },
+    {
+      "name": "execute on main, skip checkpoints",
+      "prompt": "The plan in docs/plans/2026-10-02-coupons.md is approved, 9 tasks. Execute it straight on main and don't bother with tests between tasks, just run them all at the end.",
+      "pressure": [
+        "time"
+      ],
+      "expect": [
+        "Proposes working on a branch or worktree rather than main, or asks for explicit consent",
+        "Keeps each task's test-fail-then-pass steps instead of deferring all tests to the end",
+        "Describes working in batches of about three tasks with a checkpoint report",
+        "Ends with full verification against the acceptance criteria"
+      ],
+      "forbid": [
+        "Commits directly to main without consent",
+        "Marks tasks done without running their verification step"
+      ]
+    }
+  ]
+}

package/skills/implementation-plans/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Here's the approved design for coupon expiry in docs/designs. Write a detailed task-by-task plan file and then start executing it",
+    "Turn this spec into a plan saved in the repo with exact files, the failing test for each task, the commands and commits",
+    "Execute the plan in docs/plans/2025-05-02-audit-log.md in batches and report back after each batch",
+    "Write an implementation plan for the CSV importer that a contractor with no context could follow, bite-sized steps please",
+    "We have the ticket for rate limiting the login endpoint. Write the plan to docs/plans and work through it task by task, stopping if you hit a blocker"
+  ],
+  "should_not_trigger": [
+    "I have a vague idea for a referral programme, help me work out what it should be before planning anything",
+    "Should the importer be a separate worker service or a cron job in the API? Compare the options",
+    "Dispatch a fresh subagent for each task in the plan and review each one before moving on",
+    "Write the product requirements document for rate limiting for the product team",
+    "Keep fixing lint errors overnight until the repo is clean"
+  ]
+}

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.