@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/release-management/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: release-management
+description: Ships a software release end to end - deciding the next semantic version from what changed, updating the changelog, tagging, writing release notes for users, cutting alpha/beta/rc pre-releases, patching an old version from a hotfix branch, and wiring up release tooling such as release-please, semantic-release or Changesets. Use when preparing or publishing a release, picking a version number, turning merged work into release notes, shipping a hotfix to an already-released line, or automating versioning and changelogs.
+license: MIT
+compatibility: Any Agent Skills host. Needs git. Publishing steps need the project's package manager and, for GitHub releases, the gh CLI.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# Release management
+
+A release is a promise: this exact commit, with this version number, does what the notes say. Work through the steps in order and stop at each checkpoint marked **ask**.
+
+## 0. Find the existing process
+
+1. Look for release tooling and docs: `RELEASING.md`, `CONTRIBUTING.md`, `release-please-config.json`, `.release-please-manifest.json`, `.releaserc*`, `release.config.*` or a `release` key in `package.json` (semantic-release), `.changeset/` (Changesets), `cliff.toml` (git-cliff), `.goreleaser.yaml`, and release workflows in `.github/workflows/`.
+2. If a tool owns versioning, **use the tool**. Don't hand-edit versions or changelogs it generates; that causes drift or a double bump.
+3. Find every place the version lives: `package.json`, `pyproject.toml`, `Cargo.toml`, `*.csproj`, `build.gradle*`, `pubspec.yaml`, plugin manifests, a `VERSION` file, constants in code. Search the codebase for the current version string to catch the rest.
+4. Find the last release: `git describe --tags --abbrev=0` and `git tag --sort=-v:refname | head`.
+
+## 1. Check the release is ready
+
+- `git fetch --tags --prune`, and confirm you are on the release branch (usually the default branch) with a clean tree and nothing unpushed.
+- CI is green for the exact commit you will tag. Run the project's full check command locally as well.
+- If anything fails, **stop**. Never tag a red build.
+
+## 2. Decide the version (Semantic Versioning 2.0.0)
+
+List what changed since the last tag: `git log --oneline <last-tag>..HEAD`. If commits follow Conventional Commits, the type and `!`/`BREAKING CHANGE` footers tell you directly.
+
+| Since last release | Bump | Example |
+|---|---|---|
+| Any incompatible change to the public API, config, CLI, data format or supported runtimes | MAJOR | 2.4.1 → 3.0.0 |
+| New backward-compatible functionality, or a deprecation | MINOR | 2.4.1 → 2.5.0 |
+| Only backward-compatible bug fixes | PATCH | 2.4.1 → 2.4.2 |
+| Nothing user-facing (docs, tests, CI) | No release needed | |
+
+Rules:
+
+- First decide what the **public API** is (exported functions, HTTP endpoints, CLI flags, config keys, file formats). Only changes to it count.
+- Under `0.y.z`, the public API is not stable and anything may change. Most projects bump MINOR for breaking changes and PATCH for everything else; follow the project's history.
+- `1.0.0` is a deliberate decision that the API is stable. **Ask** before making it.
+- A MAJOR bump, or any case where you are unsure whether something is breaking: **ask** the user, with the specific change that makes you think so.
+- Never reuse or move a published version or tag. A bad release gets a new version.
+
+## 3. Update the changelog
+
+If no tool generates it, keep `CHANGELOG.md` in the Keep a Changelog style:
+
+```
+## [2.5.0] - 2026-03-14
+
+### Added
+- CSV export from the reports page (#512)
+
+### Fixed
+- Totals no longer go negative when a refund exceeds the line amount (#498)
+```
+
+- Sections: Added, Changed, Deprecated, Removed, Fixed, Security. Omit empty ones.
+- Write each entry for the user of the software, not the developer: what they can now do or what stopped going wrong. Link the PR or issue.
+- Move entries out of `## [Unreleased]` into the new version heading; date in ISO format.
+- Breaking changes go first under **Changed** or **Removed**, each with the migration step.
+
+## 4. Bump, commit and tag
+
+1. Update every version location from step 0. Use the ecosystem's command where one exists (for example `npm version <x.y.z> --no-git-tag-version`) so lockfiles follow.
+2. Commit: `git commit -am "chore(release): <x.y.z>"` (or the project's convention).
+3. Tag with an **annotated** tag: `git tag -a v<x.y.z> -m "v<x.y.z>"`. Use `-s` instead of `-a` if the project signs tags. Match the existing tag prefix (`v1.2.3` or `1.2.3`, or `pkg@1.2.3` in monorepos).
+4. **Ask** before pushing: pushing a tag usually triggers publishing. Then `git push origin <branch>` and `git push origin v<x.y.z>`. Don't use `git push --tags`, which can push stray local tags.
+
+## 5. Release notes
+
+Release notes are the changelog entry rewritten for a reader skimming the release page.
+
+```
+## Highlights
+<1-3 sentences on why someone should upgrade>
+
+## Breaking changes
+- <what changed> → <what to do>
+
+## What's new / Fixes
+- <user-facing change> (#PR)
+
+## Upgrade
+<command or steps, including any migration>
+```
+
+Publish with `gh release create v<x.y.z> --title "v<x.y.z>" --notes-file notes.md --verify-tag` (add `--prerelease` for pre-releases). `--verify-tag` aborts if the tag is not on the remote, instead of letting gh create a tag from the default branch's head. `--generate-notes` builds a PR list, which is a starting draft, not finished notes.
+
+## 6. Pre-releases
+
+- Format: `<x.y.z>-<label>.<n>`, for example `3.0.0-beta.2`. SemVer orders `alpha < beta < rc` and `3.0.0-rc.1 < 3.0.0`. Always put a dot before the counter: `beta.10` sorts after `beta.9` (numeric identifiers compare as numbers), but `beta10` sorts before `beta9` (compared as text).
+- Publish so default installs don't pick them up: `npm publish --tag next` (npm), a pre-release version string for PyPI (`3.0.0b2`, PEP 440), `--prerelease` on the GitHub release.
+- Bump only the counter between pre-releases of the same version; the final release drops the suffix.
+
+## 7. Hotfixes to a released line
+
+When a fix must ship without unreleased work on the default branch:
+
+1. Branch from the release tag: `git switch -c hotfix/<x.y.z+1> v<x.y.z>`.
+2. Land the fix on the default branch first when possible, then `git cherry-pick -x <sha>` onto the hotfix branch (`-x` records the source commit). If it only applies to the old line, fix it there and port forward.
+3. Run the full checks on the hotfix branch, then do steps 3-5 with a PATCH bump.
+4. Make sure the changelog entry also reaches the default branch, so the next release doesn't lose it.
+5. For long-lived support lines, keep a `release/<major>.<minor>` branch instead of recreating it each time.
+
+## 8. Automating releases
+
+Pick one tool, and only if the project has none yet. **Ask** before adding it, since it changes how everyone merges.
+
+| Tool | Fits | How it works |
+|---|---|---|
+| release-please | GitHub repos, monorepos, wanting a human gate | Opens a release PR from Conventional Commits; merging it tags and releases |
+| semantic-release | Fully automatic releases on every merge | Analyses commits in CI, then bumps, tags and publishes |
+| Changesets | JS monorepos, versioning decided per PR | Contributors add `.changeset/*.md` files; a release PR applies them |
+| git-cliff | Changelog generation only | Builds the changelog from commits via `cliff.toml` |
+
+Before wiring one in: confirm commit messages already follow the convention it needs, give the CI token only the permissions the tool's docs list, and run it in dry-run mode first (`semantic-release --dry-run`, or check release-please's PR before merging).
+
+## Never
+
+- Never tag or publish from a dirty tree or an unpushed commit.
+- Never delete or move a published tag, or republish the same version with different contents.
+- Never hand-edit files that the release tool generates.
+- Never publish (tag push, registry publish, GitHub release) without the user's go-ahead.
+
+## Report back
+
+```
+Version: <old> → <new> (<major|minor|patch|pre-release|hotfix>), reason: <change that decided it>
+Changed files: <version files, CHANGELOG.md>
+Tag: <tag> (<pushed | local only>)
+Published: <registry/release URL, or not yet>
+Notes: <path or inline>
+Follow-ups: <port hotfix forward, announce, etc.>
+```

package/skills/release-management/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "We removed a deprecated endpoint and added CSV export, what should the next version be? Then cut the release",
+    "Prepare release 1.4.0: update CHANGELOG.md, bump the version and tag it",
+    "Customers on 2.3.x need a security fix but main has unreleased features, how do we ship 2.3.5?",
+    "Set up release-please so merging to main produces versioned releases and a changelog",
+    "Publish a 3.0.0 release candidate to npm without making it the default install"
+  ],
+  "should_not_trigger": [
+    "Write a commit message for this fix that follows the feat/fix convention",
+    "Rebase my feature branch onto main and push it safely",
+    "Plan a blue-green deployment for the API so we can roll back quickly",
+    "Write a GitHub Actions workflow that builds and tests the project",
+    "Update the README to document the new configuration options"
+  ]
+}

package/skills/remotion-video/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: remotion-video
+description: Remotion video projects written in React, covering Composition and Sequence timing, frame-driven animation with interpolate and spring, staticFile assets, font loading held by delayRender, deterministic rendering with the remotion CLI or renderMedia, and serverless rendering on AWS Lambda with concurrency and S3 privacy settings. Use when building or fixing a Remotion composition, timing scenes in frames, animating with useCurrentFrame, rendering an MP4 from React code, or setting up Remotion Lambda.
+license: MIT
+compatibility: Any Agent Skills host. Needs Node 18+ and a Remotion 4 project; Lambda rendering needs an AWS account and network access.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "node, npx"
+  kete-loom/owner: "Kete-org"
+---
+
+# Remotion video
+
+Remotion renders a React tree once per frame in a headless browser and encodes the frames. Everything visible must be a pure function of the current frame. That one rule explains most Remotion bugs.
+
+## Ground rules
+
+1. **Time is frames, not seconds.** Read `useCurrentFrame()` and `useVideoConfig()` (`fps`, `durationInFrames`, `width`, `height`). Convert seconds with `seconds * fps`. Never use `Date.now()`, `setTimeout`, `setInterval` or CSS transitions/animations for motion: they don't follow the frame and render as jumps or flicker.
+2. **Deterministic.** No `Math.random()`; use `random(seed)` from `remotion`. Data fetched at render time must be the same on every frame and every machine.
+3. **Anything async holds the frame.** Fetching data, loading fonts, waiting for a canvas or a third-party chart: wrap it with `useDelayRender()` (or `delayRender()` / `continueRender(handle)`), and call `cancelRender(err)` on failure. The default timeout is 30 seconds; raise it per call with `timeoutInMilliseconds`, not globally by habit.
+4. **Use Remotion's media tags.** `<Img>`, `<Audio>`, and `<Video>` from `@remotion/media` (or `<OffthreadVideo>` for older code) wait for media to load before a frame is captured. A plain `<img>` or `<video>` can be captured half-loaded.
+5. **Assets come from `public/` through `staticFile('name.png')`**, or from a full URL. Don't import big videos into the bundle.
+
+## Project shape
+
+- `src/index.ts` calls `registerRoot(RemotionRoot)`.
+- `src/Root.tsx` lists `<Composition id="Intro" component={Intro} durationInFrames={300} fps={30} width={1920} height={1080} defaultProps={...} />`. The `id` is what you render.
+- Typed props: give the composition a Zod `schema` so props can be edited in the Studio and validated before render. Use `calculateMetadata` when duration or size depends on props or data (for example, length of a voice-over).
+- Preview with `npx remotion studio`. Start a new project with `npx create-video@latest`.
+
+## Timing scenes
+
+1. Put each scene in `<Sequence from={f} durationInFrames={d}>`. Inside, `useCurrentFrame()` restarts at 0, so a scene's animation code doesn't need to know where it sits.
+2. Lay out back-to-back scenes with `<Series>` and `<Series.Sequence durationInFrames={d}>` instead of adding offsets by hand.
+3. For crossfades and slides between scenes use `@remotion/transitions` (`TransitionSeries` with `fade()`, `slide()` and a timing such as `linearTiming` or `springTiming`). A transition overlaps two scenes, so the total gets shorter by the transition length.
+4. Wrap layers in `<AbsoluteFill>` to stack them full-frame.
+5. Keep timing numbers in one place (a `timings` object or computed from props) so a script change doesn't mean editing ten files.
+
+## Animation
+
+- `interpolate(frame, [0, 30], [0, 1], { extrapolateLeft: 'clamp', extrapolateRight: 'clamp' })`. Without `clamp` the value keeps going past the range: opacity above 1, elements flying off-screen. Input ranges must be strictly increasing.
+- Easing: pass `easing: Easing.bezier(...)` or `Easing.out(Easing.cubic)` to `interpolate`.
+- `spring({ frame, fps, config: { damping: 200 }, delay: 10, durationInFrames: 30 })` returns 0 to about 1 with physics; defaults are `mass: 1`, `damping: 10`, `stiffness: 100`. Higher `damping` means less bounce. Feed the result into `interpolate` to map it to pixels or degrees.
+- Colours: `interpolateColors(frame, [0, 60], ['#000', '#fff'])`.
+- Animate `transform` and `opacity`. Animating `width`, `top` or heavy `filter: blur()` per frame is slow to render.
+
+## Text, fonts and audio
+
+- Load fonts before frames are captured: `loadFont()` from `@remotion/google-fonts/<Family>`, or `@remotion/fonts` `loadFont({ family, url: staticFile('x.woff2') })`. Both hold the render until the font is ready. A system font that isn't installed on the render machine or Lambda will silently fall back.
+- Measure text with `@remotion/layout-utils` (`measureText`, `fitText`) when it must fit a box.
+- Audio: `<Audio src={staticFile('music.mp3')} volume={(f) => interpolate(f, [0, 30], [0, 1], {extrapolateRight: 'clamp'})} />`. Skip the start with `trimBefore` (in frames; code before 4.0.319 uses `startFrom`) and cap the length by wrapping it in a `<Sequence durationInFrames>`.
+- Captions: `@remotion/captions` for the caption data type and TikTok-style pages.
+
+## Rendering locally
+
+1. `npx remotion render <entry> <composition-id> out/video.mp4` (the entry defaults to the configured entry point). Common flags: `--props=./props.json`, `--codec=h264|h265|vp8|vp9|prores`, `--crf`, `--concurrency`, `--frames=0-59` for a quick check, and `npx remotion still <id> out/frame.png --frame=120` for one frame.
+2. From Node: `bundle()` from `@remotion/bundler`, then `selectComposition()` and `renderMedia()` from `@remotion/renderer`. Bundle once and reuse it for many renders.
+3. Check the output with a quick look in a player and `ffprobe out/video.mp4` (duration, fps, resolution, audio stream present).
+
+## Rendering on Lambda
+
+Follow `references/lambda.md`. In short: create the IAM role and user from `npx remotion lambda policies role|user`, `npx remotion lambda functions deploy`, `npx remotion lambda sites create src/index.ts --site-name=<name>`, then `npx remotion lambda render <serve-url> <composition-id>` or `renderMediaOnLambda()` with `getRenderProgress()`.
+
+## Performance checklist
+
+When renders are slow or time out, check in order:
+
+1. Run `npx remotion benchmark` or render with `--log=verbose` to see slow frames.
+2. Heavy work per frame (parsing JSON, building big arrays): move it into `useMemo` or `calculateMetadata`.
+3. Big images: resize to the output size; prefer JPEG/WebP over huge PNGs.
+4. Too many simultaneous videos, or `<Video>` sources with sparse keyframes: re-encode sources with FFmpeg (see the ffmpeg-media-processing skill).
+5. GPU-only CSS (`backdrop-filter`, large blurs, WebGL) on a machine without a GPU: check what's available with `npx remotion gpu`, try `--gl=angle` or `--gl=swangle` (the Lambda default), or simplify the effect.
+6. Tune `--concurrency`; more is not always faster on a small machine.
+
+## Never
+
+- Never drive motion with timers, CSS animations, or state updated in `useEffect` per frame.
+- Never leave a `delayRender()` without a matching `continueRender()` or `cancelRender()` on every code path.
+- Never commit AWS keys; `REMOTION_AWS_ACCESS_KEY_ID` and `REMOTION_AWS_SECRET_ACCESS_KEY` live in `.env` that is gitignored.
+
+## Stop and ask the user
+
+- Before the first Lambda deploy or a large Lambda render: it creates AWS resources and costs money.
+- Whether rendered files should be public or private in S3 (`--privacy`); the default is public.
+- Licensing: Remotion is free for individuals and companies of up to 3 people; bigger for-profit companies need a company license. Point it out once when the project is for a company; don't decide for them.
+
+## Report back
+
+Composition IDs touched, the render command you ran, output path with duration/fps/resolution from `ffprobe`, and any frame you checked by eye.

package/skills/remotion-video/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Build a 15-second Remotion intro where the logo springs in and the title fades up",
+    "My Remotion render flickers because the text animates with a CSS transition, how do I fix it?",
+    "Deploy our Remotion composition to Lambda and render personalised videos from an API",
+    "Google font isn't showing in the Remotion MP4 even though it works in the Studio",
+    "Use Series and TransitionSeries to stitch five slides into one Remotion video with fades"
+  ],
+  "should_not_trigger": [
+    "Trim the first ten seconds off this MP4 and convert it to WebM",
+    "Animate a proof of the Pythagorean theorem with Manim",
+    "Add a Framer Motion hover animation to the pricing cards",
+    "Generate a short product clip from a text prompt with a video generation API",
+    "Speed up our React dashboard that re-renders on every keystroke"
+  ]
+}

package/skills/remotion-video/references/lambda.md

@@ -0,0 +1,66 @@
+# Remotion Lambda setup and rendering
+
+Check www.remotion.dev/docs/lambda for the current version before changing anything; the function and the site must be on the same Remotion version as the project.
+
+## One-time setup
+
+1. `npx remotion add @remotion/lambda` (keeps every `remotion` and `@remotion/*` package on the same version).
+2. In AWS IAM create a role named `remotion-lambda-role` with the policy printed by `npx remotion lambda policies role`.
+3. Create a user with the policy from `npx remotion lambda policies user` and an access key. Put the key in a gitignored `.env`:
+
+   ```txt
+   REMOTION_AWS_ACCESS_KEY_ID=...
+   REMOTION_AWS_SECRET_ACCESS_KEY=...
+   ```
+
+4. Check it: `npx remotion lambda policies validate`.
+5. See your concurrency limit: `npx remotion lambda quotas`. New AWS accounts often have a low limit; request an increase before big renders.
+
+## Deploy
+
+```bash
+npx remotion lambda functions deploy                       # once per Remotion version / memory / timeout / region
+npx remotion lambda sites create src/index.ts --site-name=my-video   # every time the video code changes
+```
+
+`sites create` prints a serve URL. Redeploying with the same `--site-name` overwrites it, so a stable name keeps the URL.
+
+## Render from the CLI
+
+```bash
+npx remotion lambda render <serve-url-or-site-name> <composition-id> [out.mp4] \
+  --privacy=private --props=./props.json
+```
+
+- `--concurrency=<n>` or `--frames-per-lambda=<n>` controls how the video is split (one or the other, at most 200 functions).
+- `--privacy`: `public` (default), `private` (use `presignUrl()` to hand out a link) or `no-acl`.
+- Without an output path the file stays in the S3 bucket.
+
+## Render from Node
+
+```ts
+import { renderMediaOnLambda, getRenderProgress } from '@remotion/lambda/client';
+
+const { renderId, bucketName } = await renderMediaOnLambda({
+  region: 'us-east-1',
+  functionName,            // from getFunctions({ region, compatibleOnly: true })
+  serveUrl,
+  composition: 'Intro',
+  inputProps: { title },
+  codec: 'h264',
+  privacy: 'private',
+});
+
+// Poll from a job, not from an HTTP request handler
+const progress = await getRenderProgress({ renderId, bucketName, functionName, region: 'us-east-1' });
+// progress.done, progress.overallProgress, progress.outputFile, progress.fatalErrorEncountered, progress.errors
+```
+
+Store `renderId` and `bucketName` with your job row so a restart can resume polling. A `webhook` option on `renderMediaOnLambda` can notify you instead of polling; verify every delivery against the secret you set, using `validateWebhookSignature({ secret, body, signatureHeader })` from `@remotion/lambda/client` with the `X-Remotion-Signature` request header, before you trust it.
+
+## Common failures
+
+- Version mismatch between project, function and site: redeploy both after upgrading.
+- Fonts missing on Lambda: load them with `@remotion/google-fonts` or `@remotion/fonts`; Lambda has few system fonts.
+- `delayRender` timeouts on Lambda but not locally: remote assets are slower to fetch; raise `timeoutInMilliseconds` for that call or host assets in the same region.
+- Rate limit / concurrency errors: lower `--concurrency` or raise the AWS quota.

package/skills/returns-reverse-logistics/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: returns-reverse-logistics
+description: Returns and reverse-logistics flow design for physical goods, from writing the return policy and issuing RMA authorisations to receiving, inspecting and grading items, routing each one to restock, refurbish, liquidate, recycle or dispose, timing the refund against receipt, and flagging return-fraud patterns such as wardrobing, item swaps and empty boxes. Use when building or fixing a returns portal, RMA workflow or grading rules, deciding when refunds are released, or reducing return losses and abuse.
+license: MIT
+compatibility: Any Agent Skills host. Applies to a store platform, WMS, order system or spreadsheet; consumer law references are EU/UK and must be checked for other markets.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: business
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Returns and reverse logistics
+
+Every return becomes an RMA with a reason, a physical route and a money outcome, and each step changes one status. The goal is to recover the most value per returned unit while refunding honest customers fast.
+
+## 0. Before you design
+
+Ask for, or find in the codebase and docs:
+
+1. Markets sold into, and whether customers are consumers or businesses. Consumer law sets minimum rights you cannot design away.
+2. Product types: apparel, electronics with serials, perishables, hygiene items, made-to-order. Each has different returnability.
+3. Current return rate and top reasons, if known.
+4. Who pays return shipping, and whether you use prepaid labels, drop-off points or the customer's own carrier.
+5. Systems: order system, store platform, WMS, payment provider (for refunds).
+
+If the user wants a policy that may breach consumer law in a market (for example no returns at all for distance sales to EU consumers), **stop and say so**; a lawyer must sign off the final policy text.
+
+## 1. Return policy
+
+Decide and write down:
+
+- Return window and when it starts (delivery date, not order date).
+- Condition rules: unused, tags on, original packaging; what is non-returnable (sealed hygiene items once unsealed, perishables, custom items) where the law allows.
+- Who pays return shipping per reason (defect or wrong item: seller; change of mind: per policy).
+- Refund method (original payment method by default), exchange and store-credit options.
+- Restocking fees, only where legal and disclosed before purchase.
+
+Legal floor examples, verify current law per market:
+- EU (Consumer Rights Directive 2011/83/EU) and UK (Consumer Contracts Regulations 2013): consumers have 14 days to withdraw from a distance sale, and the trader must refund within 14 days of being told, but may hold the refund until it receives the goods or proof they were sent back, whichever is first.
+- Faulty goods have separate statutory remedies that a change-of-mind policy does not limit.
+
+## 2. RMA process
+
+States: `requested -> authorised -> label_issued -> in_transit -> received -> inspected -> dispositioned -> refunded | exchanged | rejected -> closed`.
+
+1. Customer requests a return with order line, quantity and a **reason code** from a fixed list (wrong size, not as described, defective, damaged in transit, changed mind, arrived late, other + text).
+2. Auto-authorise inside policy; route exceptions (outside window, high value, repeat returner) to a person.
+3. Issue the RMA number and label; print the RMA on the label or packing slip so the warehouse can match the parcel.
+4. Damaged in transit goes to the logistics-exception-management flow for a carrier claim, not just a return.
+
+## 3. Receive, inspect, grade
+
+- Scan the RMA on arrival; record date, weight and photos for high-value items.
+- Check: correct item (SKU, serial or IMEI matches the outbound record), quantity, condition, accessories, signs of use.
+- Grade on a fixed scale with written criteria and photo examples:
+
+| Grade | Meaning | Default route |
+|---|---|---|
+| A | As new, sealed or unworn, full packaging | Restock as new |
+| B | Opened, fully working, light packaging wear | Restock as open-box or B-stock |
+| C | Cosmetic damage or missing accessories, works | Refurbish or sell as graded |
+| D | Faulty or heavily damaged | Repair if cost < recovery value, else return to vendor, recycle or dispose |
+| X | Wrong item, empty box or tampered | Hold, fraud review, no refund until resolved |
+
+Set an inspection SLA (for example 2 business days from receipt) because refunds wait on it.
+
+## 4. Disposition rule
+
+For each graded unit: compare **recovery value** (resale price at that grade minus refurbish, repack and handling cost) across restock, refurbish, return to vendor, liquidate, donate, recycle and dispose. Pick the highest; prefer restock or refurbish over disposal. Log the decision so finance can book the right inventory value. Check vendor return-to-vendor terms and any rules on disposing of unsold goods in your markets.
+
+## 5. Refund timing
+
+- Pick the trigger per risk: on carrier first scan (fast, more fraud exposure), on receipt, or on inspection (slowest). Low-value, low-risk items can refund on first scan; high-value and serialised items refund on inspection.
+- Respect the legal maximum where it applies (section 1), so inspection must be fast enough to fit inside it.
+- Refund through the payment provider's refund API, keyed by an idempotency key per RMA so a retry cannot refund twice.
+- Partial refunds for missing parts or wear only where the policy and law allow, with the reason and photos stored.
+
+## 6. Fraud and abuse signals
+
+Flag for review, never auto-ban:
+- Wardrobing: worn items returned (deodorant, makeup, removed tags reattached), often after events.
+- Item swap: serial mismatch, counterfeit or older model returned.
+- Empty box or weight far below the outbound weight.
+- Serial returner: return rate far above peers, many "not received" plus "defective" claims.
+- Refund to a different payment method than the purchase, or return from a different address.
+
+## Rules
+
+- Never auto-refuse a refund that the law requires; route doubtful cases to a person.
+- Never release a refund twice for one RMA; check status and idempotency.
+- Never restock a returned item as new without grading.
+- Do not publish policy text as legally compliant; tell the user it needs legal review.
+
+## Report
+
+For a design: the policy summary, the RMA state machine, the grading table, disposition and refund-trigger rules, and the integration points. For a review of existing returns: return rate and top reasons, average days from receipt to refund, recovery value per return, fraud flags raised and confirmed, and the three changes with the biggest saving.

package/skills/returns-reverse-logistics/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Design the RMA workflow for our online shop, from return request to refund",
+    "Write grading criteria so the warehouse knows whether a returned laptop is restocked, refurbished or scrapped",
+    "Should we refund returns when the carrier scans the parcel or only after inspection?",
+    "We keep getting empty boxes and swapped serial numbers back, how do we catch return fraud?",
+    "Draft a 30 day return policy for our apparel store that also works for EU customers"
+  ],
+  "should_not_trigger": [
+    "The outbound parcel was lost in transit, help me open a trace and claim with the courier",
+    "Set up dunning emails and retries for failed subscription renewals",
+    "Calculate safety stock for our returnable packaging crates",
+    "Generate a VAT-compliant credit note PDF for a cancelled invoice",
+    "Pick the right HS code and duty rate for refurbished phones we import"
+  ]
+}

package/skills/ruby-patterns/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: ruby-patterns
+description: Ruby 3 idioms for plain Ruby and gem code - small objects with clear responsibilities, blocks and Enumerable over manual loops, custom exception hierarchies and narrow rescue, frozen string literals, keyword arguments, Bundler and Gemfile.lock discipline, RuboCop configuration, optional RBS or Sorbet signatures, and the allocation and lookup mistakes that make Ruby slow. Use when writing or restructuring Ruby classes and modules, designing a gem's public API, setting up RuboCop or type signatures, or asking why a Ruby script is slow or allocating heavily.
+license: MIT
+compatibility: Any Agent Skills host. Needs ruby and bundler; rubocop, steep or sorbet only if the project uses them.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "ruby, bundle"
+  kete-loom/owner: "Kete-org"
+---
+
+# Ruby patterns
+
+Ruby code that reads plainly, fails loudly, and does not surprise the next person.
+
+## 0. Read the project first
+
+1. Find the Ruby version: `.ruby-version`, `.tool-versions`, the `ruby` line in `Gemfile`, `required_ruby_version` in a `.gemspec`. Do not use syntax newer than that version (for example the `it` block parameter needs Ruby 3.4).
+2. Read `.rubocop.yml` and any `inherit_from` / `inherit_gem` files. Their rules win over this skill.
+3. Check for typing: `sig/` and `Steepfile` (RBS + Steep), or `sorbet/` and `# typed:` comments (Sorbet). Follow whichever exists; don't add one without asking.
+4. Run commands through Bundler: `bundle exec rubocop`, `bundle exec rake`. Never rely on globally installed gem versions.
+
+If the code is a Rails app, apply this skill to plain Ruby objects only; framework conventions come from the project.
+
+## 1. Object design
+
+- One class, one job. If a class name needs "And" or "Manager", split it.
+- Prefer plain objects with an explicit `initialize` over hashes passed around. A hash with fixed keys that travels more than one method wants to be a `Data` (Ruby 3.2+) or `Struct`:
+
+  ```ruby
+  Point = Data.define(:x, :y)        # immutable, value equality, keyword or positional init
+  Point.new(x: 1, y: 2).with(y: 3)
+  ```
+
+- Use keyword arguments for anything beyond one or two obvious positionals. Required keywords (`def charge(amount:, currency:)`) fail at the call site instead of deep inside.
+- Keep the public surface small: mark helpers `private`. Expose `attr_reader`, not `attr_accessor`, unless callers truly must write.
+- Composition over inheritance. Use a module for shared behaviour that has no state of its own; use `Comparable` / `Enumerable` by defining `<=>` / `each`.
+- Avoid metaprogramming (`method_missing`, `define_method`, `send` with user input, `class_eval` strings) unless it removes real duplication. If you add `method_missing`, also define `respond_to_missing?`.
+- Do not monkey-patch core classes. If you must extend one, use a `refinement` scoped with `using`.
+
+## 2. Blocks and Enumerable
+
+- Reach for `map`, `select`/`filter`, `reject`, `filter_map`, `each_with_object`, `sum`, `group_by`, `partition`, `tally`, `min_by`/`max_by`, `each_slice`, `find` before writing `each` with an accumulator.
+- `each` is for side effects only. Never `map` and ignore the result.
+- `sum` with floats: `sum(0.0)`; for money use `BigDecimal` or integer minor units, never `Float`.
+- Large or infinite sequences: `.lazy` or `each_slice` so you don't build huge intermediate arrays.
+- Methods that yield should return an `Enumerator` when called without a block: `return enum_for(__method__) unless block_given?`.
+- `&:name` for single method calls; a short block (`{ it.strip }` on 3.4+, `{ _1.strip }` on 2.7+, or a named param) otherwise. Named params read best beyond one line.
+
+## 3. Exceptions
+
+- Define one base error per library or domain and subclass it:
+
+  ```ruby
+  module Billing
+    class Error < StandardError; end
+    class CardDeclined < Error; end
+  end
+  ```
+
+- Rescue the narrowest class you can handle. Never `rescue Exception` (it swallows `Interrupt`, `NoMemoryError`, `SystemExit`). A bare `rescue` means `StandardError`; still too broad unless you re-raise.
+- Never `rescue => e` and then do nothing. Either handle it, re-raise (`raise`), or wrap it with context: `raise Billing::Error, "charge #{id} failed"` (Ruby sets `cause` automatically).
+- Keep `begin` blocks to the call that can fail. Use `ensure` for cleanup, or better a block API (`File.open(path) { |f| ... }`) that closes for you.
+- Use `retry` only with a counter and backoff; an unbounded `retry` loops forever.
+- Don't use exceptions for expected control flow (lookups that may miss): return `nil` or a result object and let the caller decide. Use `fetch` when a missing key is a bug.
+
+## 4. Strings, symbols and nil
+
+- Put `# frozen_string_literal: true` at the top of every file if the project does (RuboCop `Style/FrozenStringLiteralComment`). Build strings with `+"..."`, `String.new` or interpolation when you need a mutable one.
+- On Ruby 3.4, mutating a literal in a file without the magic comment emits a deprecation warning when deprecation warnings are on (`ruby -W:deprecated` or `Warning[:deprecated] = true`). Turn them on in CI to find code that will break when literals become frozen.
+- Use `<<` on a mutable buffer for loops; `+=` allocates a new string each time.
+- Treat `nil` deliberately: `&.` for genuinely optional values, `Hash#fetch` / `Array#fetch` to fail loudly, `Array(x)` to normalise. Repeated `&.` chains usually mean a missing object.
+- Symbols for identifiers and keys you control; never `to_sym` on user input in long-lived processes.
+
+## 5. Bundler and dependencies
+
+- Commit `Gemfile.lock` for applications. For a gem, declare runtime dependencies in the `.gemspec` with `~>` ranges and keep the lockfile out of the release.
+- Pin loosely with intent: `gem "faraday", "~> 2.9"`. No unbounded `>=` for runtime gems.
+- Group dev and test gems (`group :development, :test do`), and `require: false` for gems loaded on demand (`rubocop`, `bootsnap`).
+- Add or upgrade one gem at a time: `bundle add <gem>`, `bundle update --conservative <gem>`. Never a bare `bundle update` without asking: it moves every gem.
+- In CI and deploys: `bundle config set frozen true` (or `deployment true`) so a stale lockfile fails instead of re-resolving.
+- Since Ruby 3.4, `base64`, `bigdecimal`, `csv`, `drb`, `mutex_m`, `observer`, `getoptlong`, `nkf`, `syslog`, `abbrev`, `rinda` and `resolv-replace` are bundled gems: under Bundler, declare them in the Gemfile if you `require` them.
+
+## 6. RuboCop
+
+- Run `bundle exec rubocop` on changed files; `-a` applies safe corrections only. Use `-A` (unsafe) only on files you are editing, and review the diff.
+- Fix the cause rather than disabling a cop. If a disable is right, scope it: `# rubocop:disable Metrics/MethodLength` ... `# rubocop:enable ...` on the smallest range, with a reason.
+- Adopting RuboCop on an old codebase: `rubocop --auto-gen-config` to create `.rubocop_todo.yml`, then shrink it over time. Don't reformat the whole repo in a feature change.
+- Use plugins the project already has (`rubocop-performance`, `rubocop-rspec`, `rubocop-rails`); ask before adding new ones.
+
+## 7. Optional typing
+
+Only when the project already uses it, or the user asks.
+
+- **RBS + Steep:** signatures in `sig/**/*.rbs`; check with `bundle exec steep check`. Start with `rbs prototype rb lib/foo.rb` and then tighten `untyped` by hand.
+- **Sorbet:** `# typed: false|true|strict` per file, `sig { params(x: Integer).returns(String) }` above methods, check with `bundle exec srb tc`; generate gem RBIs with `bundle exec tapioca gem`.
+- Type the public API first. Don't use `T.unsafe`, `T.untyped` or `untyped` to silence an error you don't understand.
+
+## 8. Performance pitfalls
+
+Measure first: `Benchmark.realtime`, `benchmark-ips`, `memory_profiler`, `stackprof`. Then look for:
+
+| Pitfall | Fix |
+|---|---|
+| `array.include?(x)` inside a loop | build a `Set` (or Hash) once |
+| `+=` / `+` building strings or arrays in loops | `<<`, `concat`, `join`, `each_with_object` |
+| `.map { }.flatten`, `.select { }.first`, `.select { }.count` | `flat_map`, `find`, `count { }` |
+| Reading a whole file to iterate lines | `File.foreach(path)` |
+| Regex or object built inside a hot loop | hoist it to a constant |
+| `method_missing` / `send` on hot paths | define real methods |
+| `Hash#merge` in a loop | `merge!` / `[]=` on one hash |
+| N+1 calls to a DB or HTTP API per element | batch the call, then index the result by key |
+
+Ruby threads share the GVL: they help with I/O waits, not CPU-bound work. For CPU-bound parallelism use processes; consider `Ractor` only after checking it is stable enough for the project's Ruby version.
+
+## Never
+
+- `eval`, `instance_eval` or `class_eval` with strings built from input.
+- `Marshal.load` or `YAML.load` of untrusted data; use `JSON.parse` or `YAML.safe_load`.
+- Backticks, `system("cmd #{x}")` or `%x()` with interpolated input; pass an argument list: `system("git", "log", ref)`.
+- Global state via `$globals` or class variables (`@@var`); use constants, injected objects, or class-level instance variables.
+
+## Report back
+
+When you finish, say: files changed, the RuboCop (and type-check) command you ran and its result, the test command and pass/fail counts, and anything you chose not to change.

package/skills/ruby-patterns/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "What's the idiomatic way to model this config hash as a Ruby object? Struct or Data?",
+    "Refactor this Ruby class: it's 400 lines and uses each with an accumulator everywhere",
+    "Set up RuboCop for our gem and tell me which cops to keep",
+    "Why is my Ruby script that dedupes a CSV so slow and eating memory?",
+    "Should I add RBS signatures or Sorbet to this Ruby library?",
+    "How should I design the error classes for my Ruby gem so callers can rescue them?"
+  ],
+  "should_not_trigger": [
+    "Write RSpec examples for the Invoice#total method",
+    "bundle install fails building the pg gem native extension on my Mac",
+    "Review my Ruby PR for N+1 queries and unpermitted params before merge",
+    "How do I structure a Rails app with service objects and concerns?",
+    "Show me the idiomatic way to handle errors in Python with custom exceptions",
+    "Write a Ruby on Rails migration that adds an index concurrently"
+  ]
+}