@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/llm-evals/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: llm-evals
+description: Builds and runs evaluation suites that measure whether an LLM feature is good enough to ship, from assembling a versioned case set and choosing graders (exact match, code checks, rubrics, a judge model) to tracking scores across prompt and model changes, keeping test cases out of prompts and training data, and deciding when people must review outputs. Use when a team needs a pass/fail bar for an AI feature, wants to catch regressions before a prompt or model upgrade, or doubts whether its LLM-as-judge scores can be trusted.
+license: MIT
+compatibility: Any Agent Skills host. Needs the project's language runtime to run the eval harness; graders using a judge model need model API access.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: ai
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# LLM evals
+
+An eval is a test suite for behaviour that isn't deterministic. It turns "seems better" into a number you can compare across prompt versions and models. This skill builds the suite. To grade one agent's existing outputs and report failure patterns, delegate to the `agent-evaluator` agent. To rewrite the prompt itself, use `prompt-engineering`.
+
+## 0. Define what you measure
+
+1. State the feature's job in one sentence and list 2 to 5 **criteria** that decide a good output (for example: correct label, cites a source, under 120 words, refuses out-of-scope requests).
+2. For each criterion, decide if it can be checked by code. Prefer code. Use a model grader only where code can't decide.
+3. Agree a ship bar with the user (for example "≥ 95% on correctness, 0 safety failures"). If the user can't give one, **stop and ask**; a suite with no bar can't block a release.
+4. Search the codebase for an existing eval harness, test runner or dataset folder before creating a new one.
+
+## 1. Build the case set
+
+- **Sources, in order of value:** real production inputs (from logs, redacted), reported bugs and user complaints, hand-written edge cases, synthetic cases generated by a model and then reviewed by a person.
+- **Coverage:** typical inputs, hard inputs, edge cases (empty, very long, wrong language, ambiguous), adversarial inputs (prompt injection, requests the feature must refuse), and one case per past bug.
+- **Size:** 20 to 50 good cases beat 1,000 unreviewed ones. Grow it as failures appear.
+- Each case is a record with an id, the input, the expected output or the facts a good answer must contain, tags (category, difficulty, source), and the date added. Store it in the repo as JSONL or similar, under version control.
+- Never put real personal data or secrets in the case set; redact first. If unsure whether data may be used, **stop and ask the user**.
+
+## 2. Avoid leakage
+
+- Split the set: a **dev** portion you look at while editing prompts, and a **held-out** portion you only run to report results. Never copy held-out inputs into prompts as few-shot examples.
+- When you add a production failure, put it in dev first; move a fresh sample into held-out periodically.
+- Don't evaluate a model on cases it may have trained on (public benchmarks, text copied from the web) and call it generalisation.
+- When a model generates synthetic cases, don't use the same prompt you are evaluating to create them.
+
+## 3. Choose graders
+
+Use the cheapest grader that decides the criterion correctly.
+
+| Grader | Use for | Notes |
+|---|---|---|
+| Exact / normalised match | labels, IDs, numbers, yes/no | Normalise case, whitespace and number format first |
+| Code check | JSON validity, schema, length, required keywords, regex, citation present, tool called with right args | Deterministic, fast, run on every case |
+| Reference similarity | short factual answers | Only as a hint; similar text can be wrong |
+| Rubric, model-graded | tone, helpfulness, faithfulness to a source, reasoning quality | Needs calibration (section 4) |
+| Pairwise, model-graded | "is B better than A?" between two prompt versions | Randomise order to cancel position bias |
+| Human review | ship decisions on subjective quality, safety, legal or medical content, calibrating judges | Slow; sample, don't review everything |
+
+Grader templates and a judge prompt are in `references/graders.md`. Read it before writing a model-graded rubric.
+
+## 4. Make model graders trustworthy
+
+1. Grade one criterion per judge call, with a short rubric that defines each score level in concrete terms. Prefer pass/fail or a 1 to 3 scale over 1 to 10.
+2. Ask the judge for its reasoning first, then the verdict in a fixed field your code parses.
+3. Use a capable model as judge, and preferably not the exact model and prompt under test.
+4. **Calibrate:** have a person label 20 to 50 outputs, run the judge on them, and measure agreement. Fix the rubric until agreement is acceptable to the user; report the agreement rate alongside every judged score.
+5. Re-calibrate when you change the judge model or rubric.
+
+## 5. Run and track
+
+1. Run every case with the exact production config: model version, prompt version, temperature, tools.
+2. Outputs vary between runs. Run each case several times (3 or more when results are close) and report the pass rate per case, not just the mean.
+3. Store each run as a record: date, git commit, prompt version, model, per-case results, aggregate scores, cost and latency.
+4. Compare against the last accepted run **case by case**. A higher average that breaks previously passing cases is a regression to report, not a win.
+5. Wire the fast, code-graded portion into CI so prompt or model changes can't merge when it drops below the bar. Run expensive judge-graded suites on demand or nightly.
+
+## 6. When to involve people
+
+Bring in human review when:
+- Setting or changing the ship bar.
+- Calibrating a judge model (section 4).
+- The domain is high-stakes (health, finance, legal, safety) or the output reaches users unreviewed.
+- Judge scores and user feedback disagree.
+- Labelling new production failures before they join the case set.
+
+Give reviewers the rubric, blind them to which version produced the output, and record their labels in the case set.
+
+## Never
+
+- Never report a score without the case count, run count and grader type.
+- Never tune a prompt on the held-out set.
+- Never treat a judge model's score as ground truth before checking it against human labels.
+- Never delete a failing case to raise the score. Fix the feature or mark the case as wrong, with a reason, after the user agrees.
+
+## Report back
+
+```
+Feature: <name>   Prompt: <version>   Model: <exact id>
+Cases: <n dev> dev / <n held-out> held-out   Runs per case: <k>
+Criterion          Grader        Score     Bar     Δ vs last
+<correctness>      exact         47/50     ≥ 45    +2
+<faithfulness>     judge (κ=..)  44/50     ≥ 45    -1  ← regression
+Newly failing: <case ids>   Newly passing: <case ids>
+Verdict: ship | don't ship, because <one line>
+```

package/skills/llm-evals/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "We want to swap to a cheaper model, set up evals so we know if quality drops",
+    "Build a test set and graders for our support-ticket classifier",
+    "How do I check that my LLM-as-judge scores actually agree with humans?",
+    "Add an eval step to CI that fails the build if the summariser's accuracy regresses",
+    "Our eval cases keep ending up in the few-shot examples, how do we keep the held-out set clean?"
+  ],
+  "should_not_trigger": [
+    "Make the extraction prompt handle missing dates better",
+    "Score these 40 agent transcripts against our rubric and tell me where it fails",
+    "Add a timeout and JSON schema validation to our model call",
+    "Benchmark the p99 latency of the search API under load",
+    "Increase unit test coverage for the billing module to 80 percent"
+  ]
+}

package/skills/llm-evals/references/graders.md

@@ -0,0 +1,66 @@
+# Grader templates
+
+Read this when writing graders for an LLM eval suite. Adapt names to the project's language; the shapes matter, not the syntax.
+
+## Case record (JSONL, one per line)
+
+```json
+{"id": "refund-017", "split": "dev", "input": {"message": "I was charged twice"}, "expected": {"label": "billing"}, "must_include": ["refund"], "tags": ["billing", "hard"], "source": "prod-log", "added": "2026-01-14"}
+```
+
+## Code graders
+
+Each grader takes `(case, output)` and returns `{ "pass": bool, "reason": str }`. Return a reason on failure so reports show why.
+
+```python
+def grade_label(case, output):
+    got = (output.get("label") or "").strip().lower()
+    want = case["expected"]["label"]
+    return {"pass": got == want, "reason": f"got {got!r}, want {want!r}"}
+
+from jsonschema import Draft202012Validator  # pip package "jsonschema"
+
+def grade_schema(case, output, schema):
+    errors = list(Draft202012Validator(schema).iter_errors(output))
+    return {"pass": not errors, "reason": "; ".join(e.message for e in errors[:3])}
+
+def grade_must_include(case, output):
+    text = output["text"].lower()
+    missing = [w for w in case.get("must_include", []) if w.lower() not in text]
+    return {"pass": not missing, "reason": f"missing {missing}"}
+```
+
+Other useful code checks: word or token count within a range, no forbidden phrases, every cited ID exists in the retrieved documents, the expected tool was called with the expected arguments, the agent finished within N steps.
+
+## Judge prompt (one criterion, pass/fail)
+
+```
+You are grading one output from an AI feature against one criterion.
+
+<criterion>
+Faithfulness: every factual claim in the answer is supported by the source.
+PASS: all claims are supported, or the answer says the source doesn't cover it.
+FAIL: any claim is missing from or contradicts the source.
+</criterion>
+
+<source>{source}</source>
+<question>{input}</question>
+<answer>{output}</answer>
+
+First list each factual claim in the answer and whether the source supports it.
+Then give your verdict on the last line exactly as: VERDICT: PASS or VERDICT: FAIL
+```
+
+Parse only the last `VERDICT:` line. Treat a missing or malformed verdict as a grader error, not a pass.
+
+## Pairwise judge
+
+Show outputs A and B for the same input with the criterion, ask which is better or "tie". Run each pair twice with A and B swapped; count a win only when both orders agree, otherwise a tie.
+
+## Measuring judge agreement
+
+With human labels for the same outputs:
+
+- Agreement rate = cases where judge and human agree / cases labelled.
+- For pass/fail labels, also report Cohen's kappa, which corrects for agreement by chance: κ = (p_o − p_e) / (1 − p_e), where p_o is observed agreement and p_e is the agreement expected from each rater's pass rate.
+- Look at the disagreements, not just the number. They usually point to a vague rubric line.

package/skills/logistics-exception-management/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: logistics-exception-management
+description: Shipment exception handling for parcels and freight that are late, damaged, lost, refused or stuck on a bad address, covering triage by exception type, evidence capture, carrier claim deadlines, customer messages, SLA clocks and a root-cause log that shows which lane, carrier or packaging keeps failing. Use when a delivery has gone wrong and someone must decide what to do, when building an exceptions queue or claims tracker, or when setting up rules and templates for delay, damage and loss cases.
+license: MIT
+compatibility: Any Agent Skills host. Works from carrier tracking exports, a ticket or order system, or a spreadsheet tracker; carrier API calls need network access.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: business
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Logistics exception management
+
+Turn every failed delivery into one tracked case with an owner, a deadline and a cause. Resolve the customer first, recover money from the carrier second, and fix the pattern third.
+
+## 0. Before you act
+
+1. Identify the shipment: order ID, tracking or waybill number, carrier and service, origin and destination, ship date, declared value, and the Incoterm or shipping terms if B2B.
+2. Get the latest carrier scan events and the promised delivery date.
+3. Find the policy that applies: your customer SLA (reship or refund rules), the carrier's contract or tariff, and any insurance.
+
+If you cannot tell who bears the risk in transit (seller, buyer or carrier), **stop and ask the user**. That decides who files the claim.
+
+## 1. Triage by exception type
+
+| Type | Signals | First action |
+|---|---|---|
+| Delay | No scan for 2+ business days, missed promised date, weather or customs hold | Open a trace with the carrier; tell the customer with a new ETA |
+| Address issue | "Address incomplete", "Recipient moved", return-to-sender pending | Contact the customer to confirm the address; request an address correction from the carrier before it returns |
+| Damage | Customer photos, "damaged" scan, refused delivery | Collect evidence (below); decide reship or refund; keep the goods and packaging |
+| Loss | Tracking stops, carrier confirms not found, or "delivered" but customer says not received | Open a trace; for "delivered not received" check GPS/photo proof of delivery and neighbours before claiming |
+| Customs hold | "Clearance delay", duties unpaid, documents requested | Send the missing document or payment; route classification questions to the customs-trade-compliance skill |
+| Refused / undeliverable | Recipient refused, unpaid COD or duties | Decide: return, abandon or re-deliver, by goods value vs return cost |
+
+Set a severity: **P1** high value, perishable, medical or a key account; **P2** standard order past SLA; **P3** informational (delay inside SLA).
+
+## 2. Evidence for damage and loss
+
+Collect within the carrier's window, before anything is thrown away:
+
+- Photos of the outer box (all sides, labels), inner packaging, and the damaged item with the serial or SKU visible.
+- Weight at dispatch vs weight at delivery if available.
+- Commercial invoice or proof of value, packing list, and proof of delivery (signature, notes, photo).
+- For freight: the delivery receipt or bill of lading with exceptions written on it. A clean signature with no noted damage makes a claim much harder. Train receivers to write the specific damage (for example "3 cartons crushed, 1 wet") before signing; a generic "subject to inspection" note often does not protect the claim.
+
+## 3. Carrier claims
+
+1. Check the carrier's own terms for filing windows and liability limits. They vary by carrier, service and contract; read the current tariff instead of assuming.
+2. Reference points that are set by law, not the carrier:
+   - US interstate motor freight (Carmack Amendment, 49 U.S.C. 14706): carriers may not set a claim filing period shorter than 9 months (standard bill of lading terms count it from delivery, or from when a reasonable time for delivery has passed), nor less than 2 years to sue after a claim is declined.
+   - International air cargo (Montreal Convention, Article 31): written complaint within 14 days of receipt for damage and within 21 days of being placed at disposal for delay. Any court action must start within 2 years (Article 35), which is the outer limit for a lost shipment.
+3. Claim the provable value (invoice cost, or as the contract says) up to the liability limit; declared value or cargo insurance governs anything above it.
+4. Record claim number, amount, date filed, deadline and status. Chase at fixed intervals.
+
+Never miss a filing window to wait for a perfect evidence pack; file on time and add documents later if the carrier allows it.
+
+## 4. Customer communication
+
+- First message within your SLA (for example same business day for P1). Say what happened, what you are doing, and when they will next hear from you.
+- Offer the resolution your policy allows: reship now, refund, or wait for trace. Do not make the customer wait for the carrier claim to finish.
+- Never blame the carrier in a way that implies the customer must chase them; the seller owns the relationship.
+- Use templates per exception type; keep the tracking link and case ID in every message.
+
+## 5. SLA clocks
+
+Track per case: opened at, first customer response at, carrier trace opened at, resolution offered at, claim filed at, closed at. Report breaches by type and carrier.
+
+## 6. Root-cause log
+
+Every closed case gets one primary cause from a fixed list: carrier handling, packaging, address data, warehouse pick/pack, customs documentation, weather/force majeure, customer unavailable, fraud suspected, unknown. Review weekly:
+
+- Exception rate by carrier, service, lane and packaging type.
+- Repeated "delivered not received" by address or customer, which may be fraud; send to a person, do not auto-block.
+- Address errors traced to checkout validation.
+
+## Rules
+
+- Never promise a refund or reship outside written policy without the user's approval.
+- Never discard damaged goods or packaging before the carrier says the claim does not need an inspection.
+- Never file a claim or contact a carrier on the user's behalf without confirmation.
+- Do not state a carrier's deadline or liability limit you have not read in its current terms.
+
+## Case record and report
+
+```
+case_id | order_id | tracking | carrier/service | type | severity | opened | sla_due | customer_action | claim_no | claim_deadline | claim_amount | status | root_cause
+```
+
+Summary for a review: open cases by type and age, SLA breaches, claims filed vs recovered, and the top three root causes with a proposed fix each.

package/skills/logistics-exception-management/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Tracking has not updated in five days and the customer is angry, what should we do and say?",
+    "Help me put together a damage claim for a pallet that arrived crushed via our LTL carrier",
+    "Design a shipment exceptions queue with severities, SLA timers and root-cause codes",
+    "The carrier marked the parcel delivered but the customer says it never arrived, how do we handle it?",
+    "Write customer email templates for delayed, lost and wrong-address deliveries"
+  ],
+  "should_not_trigger": [
+    "Customers want to send items back, design our returns portal and RMA numbering",
+    "Calculate the reorder point for SKU 1043 given a four week lead time",
+    "Which Incoterm should we quote to a buyer in Germany so they handle import duties?",
+    "Plan the shift schedule for our packing line around the bottleneck machine",
+    "Write a postmortem for yesterday's checkout outage"
+  ]
+}

package/skills/manim-animations/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: manim-animations
+description: Manim Community Edition (the manim Python package, not 3b1b manimgl) for math and explainer animations, covering Scene construct methods, Mobjects and VGroups, play with the .animate syntax, Transform versus ReplacementTransform, ValueTracker updaters and always_redraw, MathTex and Tex with a LaTeX install, and render quality flags from -ql drafts to -qk 4K. Use when writing or debugging a Manim scene, animating equations, graphs or geometry in Python, or fixing Manim LaTeX, updater or render-output problems.
+license: MIT
+compatibility: Any Agent Skills host. Needs Python 3 with the manim package; MathTex and Tex also need a LaTeX distribution with dvisvgm.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "python3, manim"
+  kete-loom/owner: "Kete-org"
+---
+
+# Manim animations
+
+Manim Community (`pip install manim`, `from manim import *`) builds a video from Python: a `Scene` subclass whose `construct()` adds objects and plays animations. Iterate at low quality, check single frames, and only render high quality at the end.
+
+## 0. Before you start
+
+1. Confirm which Manim: `import manim` and `manim --version` mean Community Edition. Code with `from manimlib import *` or `manimgl` is 3Blue1Brown's version; its API differs (for example `ShowCreation` vs `Create`, `TexText` vs `Tex`). **Don't mix them**; ask the user which one if the repo doesn't say.
+2. Run `manim checkhealth` once. If equations are planned, check `latex --version` and `dvisvgm --version`. Missing LaTeX is the most common setup failure.
+3. Write the storyboard as a list of beats (what appears, what changes, how long) before code. Ask the user for the target length and resolution if unknown.
+
+## 1. Scene structure
+
+```python
+from manim import *
+
+class PythagorasProof(Scene):
+    def construct(self):
+        title = Text("a² + b² = c²").to_edge(UP)
+        tri = Polygon(ORIGIN, 3 * RIGHT, 3 * RIGHT + 2 * UP, color=BLUE)
+        self.play(Write(title))
+        self.play(Create(tri), run_time=2)
+        self.wait()
+```
+
+- One scene class per beat or section; render sections separately and join them later. Long single scenes are slow to iterate on.
+- Use `MovingCameraScene` to pan or zoom (`self.camera.frame.animate.scale(0.5)`), `ThreeDScene` for 3D (`self.set_camera_orientation(phi=..., theta=...)`).
+- Group with `VGroup(a, b, c)` and lay out with `.arrange(DOWN, buff=0.4)`, `.next_to(obj, RIGHT)`, `.to_edge(UP)`, `.move_to(ORIGIN)`. The frame is about 14.2 by 8 units; keep content inside it.
+
+## 2. Animations
+
+- `self.play(Create(x))`, `Write(text)`, `FadeIn(x, shift=UP)`, `FadeOut(x)`, `GrowFromCenter(x)`, `Indicate(x)`, `Circumscribe(x)`.
+- `.animate`: `self.play(square.animate.shift(RIGHT).set_color(RED))` animates the start-to-end difference of the chained calls. It interpolates positions, not paths, so a rotation by `.animate.rotate(PI)` can look like a squash; use `Rotate(square, angle=PI)` instead.
+- Run several animations together by passing them to one `self.play(...)`; stagger with `LaggedStart(*anims, lag_ratio=0.2)` or `AnimationGroup`.
+- Control timing with `run_time=` and `rate_func=` (`smooth` is the default, also `linear`, `there_and_back`, `rush_into`).
+
+### Transform pitfalls
+
+- `Transform(a, b)` morphs `a` into `b`'s shape but **`a` stays on screen as the object**; `b` is never added. Later code that animates `b` does nothing visible.
+- `ReplacementTransform(a, b)` removes `a` and adds `b`; use it when the code later refers to `b`.
+- `TransformMatchingTex(eq1, eq2)` (or `TransformMatchingShapes`) for equation steps where terms move to new places.
+
+## 3. Updaters and changing values
+
+- A `ValueTracker` holds a number you animate: `t = ValueTracker(0)`, `self.play(t.animate.set_value(5), run_time=3)`.
+- Rebuild an object every frame from the tracker: `dot = always_redraw(lambda: Dot(axes.c2p(t.get_value(), f(t.get_value()))))`.
+- Or attach an updater: `label.add_updater(lambda m: m.next_to(dot, UP))`. Use the `(m, dt)` signature for motion based on elapsed time.
+- Remove updaters (`clear_updaters()`) when done, or they keep running in later animations and slow rendering.
+- Updaters only run while the scene is playing or waiting; a `self.wait()` keeps them going.
+
+## 4. Text and LaTeX
+
+- `Text("...")` uses Pango, no LaTeX needed, supports non-Latin scripts and `font=`.
+- `MathTex(r"\int_0^1 x^2\,dx")` is math mode; `Tex(r"Area is $\pi r^2$")` is text mode. Always use raw strings (`r"..."`), or backslashes break.
+- Split an equation into parts to colour or transform them: `MathTex("a^2", "+", "b^2", "=", "c^2")`, then `eq[0].set_color(BLUE)` or `eq.set_color_by_tex("c^2", RED)`.
+- Extra packages: a `TexTemplate` with `add_to_preamble(r"\usepackage{...}")`, passed as `tex_template=`.
+- A LaTeX error prints the `.tex` file path under `media/Tex/`; read its `.log` for the real error.
+
+## 5. Graphs and geometry
+
+- `axes = Axes(x_range=[-3, 3, 1], y_range=[-1, 9, 1], axis_config={"include_numbers": True})`, `graph = axes.plot(lambda x: x**2, color=YELLOW)`, `axes.get_area(graph, x_range=[0, 2])`, `axes.c2p(x, y)` to convert coordinates.
+- `NumberPlane()` for grids, `ParametricFunction` for curves, `Arrow`, `Brace(obj, DOWN)` with `.get_text("...")`.
+
+## 6. Rendering
+
+`manim [flags] file.py SceneName` (same as `manim render ...`).
+
+| Flag | Output |
+|---|---|
+| `-ql` | 854x480, 15 fps: drafts |
+| `-qm` | 1280x720, 30 fps |
+| `-qh` | 1920x1080, 60 fps |
+| `-qp` | 2560x1440, 60 fps |
+| `-qk` | 3840x2160, 60 fps |
+
+- `-p` opens the result; `-s` saves only the last frame as PNG (fast layout check); `-n 3,5` renders only a range of `play`/`wait` calls by index; `-a` renders all scenes in the file; `--format=png|gif|mp4|webm|mov` (`png` writes an image sequence); `-t` for a transparent background (`.mov`).
+- Output goes to `media/videos/<file>/<resolution><fps>/SceneName.mp4`, for example `media/videos/proof/480p15/`.
+- Partial-movie caching makes re-renders fast; if output looks stale after changing something outside `construct` (a template, an asset), add `--disable_caching` or delete the `media/` folder.
+- Set defaults per project in `manim.cfg` (`[CLI]` section, for example `quality = low_quality`, `background_color = WHITE`).
+
+## Never
+
+- Never render the whole video at `-qh` or `-qk` while still changing it; draft at `-ql` and check frames with `-s`.
+- Never mix ManimGL and Manim Community imports or examples from the other's docs.
+- Never leave updaters attached to objects that are later faded out and re-added; they stack up.
+
+## Stop and ask the user
+
+- If LaTeX isn't installed and equations are needed: installing a TeX distribution is large; ask before doing it, and offer `Text` as a fallback for simple formulas.
+- When the maths shown must be correct for teaching (proofs, statistics): show the user the formulas and steps for review before the final render.
+
+## Report back
+
+Scenes written, the exact render commands, output file paths and resolution, and a list of beats with their approximate durations.

package/skills/manim-animations/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Make a Manim scene that plots y = x^2 and shades the area from 0 to 2",
+    "My MathTex fails with LaTeX compilation error converting to dvi, what's wrong?",
+    "After Transform(a, b) in Manim, animating b does nothing on screen",
+    "Animate a dot moving along a sine curve with a ValueTracker and always_redraw",
+    "Render my Manim explainer at 1080p60 instead of the low quality draft"
+  ],
+  "should_not_trigger": [
+    "Build an animated intro video in React with spring physics",
+    "Plot a matplotlib histogram of the survey results in a Jupyter notebook",
+    "Convert the rendered MP4 into an HLS stream for our website",
+    "Write a generative p5.js flow field sketch",
+    "Create a D3 chart that animates when the data changes"
+  ]
+}

package/skills/market-research/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: market-research
+description: Structured market and competitor analysis that sizes a market top-down and bottom-up (TAM, SAM, SOM), builds a competitor feature and pricing matrix, defines customer segments, and attaches a source and a confidence level to every figure. Use when someone needs to judge whether a market is worth entering, size an opportunity, compare competitors, or back a business plan or deck with researched numbers rather than guesses.
+license: MIT
+compatibility: Any Agent Skills host. Web access makes it far more useful; without it, the skill works from sources the user provides and labels everything else as an estimate.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: business
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Market research
+
+Answer a business question with evidence: how big, who competes, who buys, and how sure we are. Every number carries its source and a confidence level.
+
+## 0. Frame the question
+
+1. Write the decision the research supports ("Should we build a pharmacy inventory product for Ghana and Nigeria?"). Research without a decision sprawls.
+2. Fix the scope: product category, geography, customer type (B2B or B2C, size), time frame and currency.
+3. Ask what the user already knows: their data, customer interviews, known competitors.
+4. **Stop and ask** if the market definition is ambiguous ("fintech in Africa" is not a market). Propose two or three narrower definitions and let the user choose.
+
+## 1. Gather sources
+
+Prefer, in order:
+
+1. **Primary**: the user's own data, customer interviews, sales conversations, surveys.
+2. **Official statistics**: national statistics offices, central banks, regulators, World Bank, IMF, UN and industry regulators' published registers (licensed businesses, operators).
+3. **Company disclosures**: annual reports, regulatory filings, investor presentations, pricing pages.
+4. **Industry reports and reputable press**: note publisher, date and methodology if stated.
+5. **Estimates and blogs**: last resort, and always low confidence.
+
+For each source record: title, publisher, date, URL or reference, and what figure it supports. Note when a figure is old or from another geography being used as a proxy.
+
+## 2. Size the market
+
+Do both methods and compare them.
+
+**Top-down**: start from a published total and narrow it.
+`total category spend x share in our geography x share in our segment`.
+
+**Bottom-up** (the more credible one): count the customers and multiply by what they would pay.
+`number of target customers x share reachable x annual price = SAM`; then `SOM = SAM x realistic share in 3-5 years`, based on channel capacity and competitor shares, not a round percentage.
+
+Definitions:
+
+- **TAM**: total demand for the category if every possible customer bought.
+- **SAM**: the part your product and channels can serve (geography, segment, price point).
+- **SOM**: the part you can realistically win in the stated period.
+
+Show every step of the arithmetic with its input and source. If the two methods differ by more than about 3x, explain why or say which you trust and why.
+
+## 3. Competitor matrix
+
+1. List competitors in three groups: direct (same job, same customer), indirect (different product, same job), and substitutes (spreadsheets, manual process, doing nothing).
+2. For the main 4-8, fill a matrix:
+
+| Competitor | Target customer | Core offer | Pricing (source, date) | Channels | Strengths | Weaknesses | Evidence of traction |
+|---|---|---|---|---|---|---|---|
+
+3. Pick the two or three dimensions that customers actually choose on and place competitors on them. Say where the gap is, and whether a gap reflects an opportunity or a lack of demand.
+4. Pricing and features come from the competitor's own pages or documents when possible; date them, as they change.
+
+## 4. Customer segments
+
+For each segment (two to four):
+
+- Who: firmographics (industry, size) or demographics, and geography.
+- Job to be done and trigger for buying.
+- Current solution and its pain.
+- Willingness and ability to pay; who decides and who pays.
+- Size (count) and how you reached it.
+- How to reach them (channels).
+
+Recommend which segment to start with and why (pain, reachability, ability to pay).
+
+## 5. Confidence levels
+
+Tag every figure and conclusion:
+
+- **High**: primary data or an official or audited source, recent, same geography and definition.
+- **Medium**: reputable secondary source with stated methodology, or a close proxy.
+- **Low**: estimate, old data, a different geography, or a source with no method.
+
+The overall conclusion can be no more confident than the inputs it rests on most.
+
+## Rules
+
+- Never invent a statistic, a source, a competitor's revenue or a quote. If you cannot find it, say "not found" and estimate openly with the assumptions shown.
+- Never present a paid-report headline figure without its date and publisher.
+- Keep facts, estimates and opinions visibly separate.
+- Respect site terms; do not scrape behind logins or paywalls.
+
+## Report format
+
+```
+# Market research: <question>
+Decision supported: <...>   Scope: <category, geography, customer, period, currency>
+
+## Answer in brief
+<3-5 lines with the headline numbers and confidence>
+
+## Market size
+| Measure | Value | Method | Key inputs | Confidence |
+<arithmetic for top-down and bottom-up>
+
+## Competitors
+<matrix> <positioning and gaps>
+
+## Customer segments
+<table> <recommended starting segment>
+
+## Risks and unknowns
+## Sources
+| # | Source | Publisher | Date | Used for |
+```

package/skills/market-research/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "How big is the market for school fee payment software in Ghana? Give me TAM, SAM and SOM.",
+    "Build a competitor matrix for invoicing tools aimed at freelancers, with pricing and positioning",
+    "Is there a real market for a B2B logistics app for informal traders in Lagos? Research it with sources.",
+    "Who are the customer segments for a telehealth subscription in East Africa and which should we start with?",
+    "Compare the main players in the African payroll software space and tell me how confident you are in the numbers"
+  ],
+  "should_not_trigger": [
+    "Outline a 12-slide pitch deck for our seed raise",
+    "Plan the channels, calendar and budget for our app launch campaign next month",
+    "Our pages dropped out of Google's index, audit the site",
+    "Research the best Python library for parsing PDFs before I write my own",
+    "Write an article explaining why mobile money took off in Kenya"
+  ]
+}