@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/llm-app-patterns/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: llm-app-patterns
+description: Engineering patterns for shipping LLM-backed product features in application code, covering schema-validated structured output, timeouts and bounded retries, streaming responses, prompt caching and token budgets, choosing a model tier, defending against prompt injection from untrusted content, and logging each call so it can be evaluated later. Use when wiring a model API call into a backend or app, hardening an existing LLM feature for production, cutting its latency or cost, or handling tool output and user documents that reach the model.
+license: MIT
+compatibility: Any Agent Skills host. Provider-neutral; applies to any model API or SDK in any backend language.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: ai
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# LLM app patterns
+
+Treat a model call like any other unreliable network dependency that returns untrusted text. This skill covers the code around the call. For wording the prompt itself, use `prompt-engineering`; for measuring quality, use `llm-evals`; for retrieval pipelines, use `rag-pipeline-patterns`.
+
+## 0. Before you write code
+
+1. Find what the project already uses: search for the provider SDK import, an existing client wrapper, env vars holding API keys, and any logging or tracing of model calls. Extend that; don't add a second client.
+2. Write down the feature contract in one or two lines: input, output shape, latency budget, and what the user sees when the model fails.
+3. If there is no fallback behaviour for "model unavailable" and the feature is user-facing, **stop and ask the user** what should happen (hide the feature, show an error, use a non-LLM default).
+
+## 1. Structured output
+
+1. Define the output as a schema in code (JSON Schema, Zod, Pydantic, a typed struct). That schema is the source of truth for the prompt, the parser and the tests.
+2. Use the provider's native structured output or tool/function calling with that schema when available. Otherwise ask for JSON only and parse strictly.
+3. **Always validate** the parsed result against the schema in your code, even when the provider claims to enforce it. Reject unknown enum values and out-of-range numbers.
+4. On a validation failure: retry once, sending the validation error back to the model. If it fails again, return the defined fallback. Never pass unvalidated model output to a database write, a shell, a SQL query, an HTML page or another tool.
+5. Keep schemas flat and small. Add an explicit "unknown" or `null` option so the model is not forced to invent a value.
+
+## 2. Timeouts, retries and failure
+
+- Set a client timeout on every call. Streaming calls get a time-to-first-token timeout and an overall timeout.
+- Check the SDK's own retry behaviour before adding yours. The official OpenAI and Anthropic SDKs already retry connection errors, 408, 409, 429 and 5xx (2 retries by default, configurable with `max_retries`). Wrapping your own retry loop around that multiplies the attempts; either tune the SDK setting or disable it and own the loop.
+- Retry only transient failures: timeouts, connection errors, 408, 429, 5xx and provider "overloaded" errors. Use exponential backoff with jitter and honour a `retry-after` header if present. Cap the total at 2 to 3 attempts.
+- Don't retry other 4xx errors (bad request, auth, permission, not found, request too large): fix the request instead.
+- Put a per-user and global concurrency limit in front of the API so a traffic spike cannot burn the rate limit for everyone.
+- If an action has side effects (sending an email, calling a tool that writes), make the retry idempotent or don't retry the step that has the side effect.
+
+## 3. Streaming
+
+- Stream when a human is waiting on long free text. Don't stream when the output must be validated as a whole before use (structured output feeding code).
+- Forward chunks to the client as they arrive (SSE or WebSocket), and handle the stream ending early: show partial text as incomplete, never as final.
+- Read the final usage and stop reason from the end of the stream and log them. A stop because of the max-token limit means the answer is truncated; treat it as a failure for structured output.
+- Cancel the upstream request when the client disconnects so you stop paying for tokens nobody reads.
+
+## 4. Cost and latency
+
+1. Measure first: log input tokens, output tokens, cached tokens and latency per call (section 6). Optimise the call that costs the most, not the one you suspect.
+2. **Prompt caching:** put stable content first (system prompt, tool definitions, long reference documents, few-shot examples) and variable content (the user's turn) last. Some providers cache matching prefixes automatically; others need an explicit cache marker on the stable block. Check the provider's docs for the minimum cacheable length and cache lifetime, and confirm hits in the usage fields.
+3. Don't put timestamps, request IDs or per-user data at the top of the prompt: they break the cached prefix.
+4. Set `max_tokens` (or the provider's equivalent) to what the feature needs, not the model maximum.
+5. Trim context: send only the fields the task needs, summarise long histories, and cap retrieved documents.
+6. Cache whole responses in your own store only for deterministic, non-personal requests, keyed on model + prompt version + normalised input.
+7. Use batch APIs for offline jobs that can wait.
+
+## 5. Model selection
+
+- Start with the most capable model to prove the feature works and to build the eval set, then try a smaller, cheaper or faster tier and keep it only if it passes the same evals.
+- Route by task: a small model for classification, extraction and routing; a larger one for multi-step reasoning or long writing.
+- Pin an exact model version in config, not a floating alias, so behaviour doesn't change under you. Upgrading the model is a change that must re-run the evals.
+- Keep the model name, temperature and max tokens in config next to the prompt version, not scattered through code.
+
+## 6. Prompt injection and untrusted content
+
+Anything the model reads that you did not write is untrusted: user messages, uploaded files, web pages, emails, retrieved documents and tool results.
+
+1. Keep instructions in the system prompt. Put untrusted content in clearly delimited blocks (for example XML-style tags) and say in the instructions that text inside them is data, not instructions.
+2. **Assume injection will sometimes succeed** and limit the damage: give the model only the tools the task needs, scope credentials to the current user, and enforce authorisation in your code, never by asking the model to check.
+3. Require human confirmation before irreversible or external actions the model proposes (payments, sending messages, deleting data).
+4. Never render model output as raw HTML or Markdown that can load remote images or links without sanitising; that is a data-exfiltration path.
+5. Don't put secrets in prompts. Assume the system prompt can be extracted.
+6. Add injection attempts to the eval set (`llm-evals`) so a prompt change cannot quietly remove a defence.
+
+## 7. Logging for evaluation
+
+Log one record per model call, with the project's normal logger or tracing system:
+
+```
+{ request_id, feature, prompt_version, model, params, input_tokens, output_tokens,
+  cached_tokens, latency_ms, stop_reason, validation_ok, retry_count, error, user_feedback }
+```
+
+- Log full prompts and outputs only where the project's privacy rules allow it. Redact or hash personal data and secrets before storage, and set a retention period. If unsure, **stop and ask the user**.
+- Version prompts like code (a constant or file with a version string) and log the version, so a regression can be traced to a change.
+- Capture explicit user feedback (thumbs, edits, retries) against the `request_id`. Those records become eval cases.
+
+## Never
+
+- Never trust model output as authorisation, as a safe identifier, or as already validated.
+- Never send API keys to a browser or mobile client; call the model from your server.
+- Never retry without a cap, or loop on tool calls without a maximum step count.
+- Never ship a prompt or model change without re-running the evals.
+
+## Report back
+
+End with: the files changed, the schema and fallback chosen, timeout and retry settings, how caching is arranged, what is logged, and any risk left open (for example "no eval set yet").

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

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Our summarize endpoint calls the model and sometimes returns broken JSON, make it return a validated object every time",
+    "Add retries with backoff and a timeout around the OpenAI call in our ticket classifier",
+    "The chat feature is too expensive, help me restructure the prompt so prompt caching actually hits",
+    "Stream the assistant's reply to the browser over SSE and cancel the request if the user closes the tab",
+    "Users can upload PDFs that get sent to the LLM, how do we stop instructions inside those files from hijacking it?"
+  ],
+  "should_not_trigger": [
+    "Rewrite this system prompt so the model stops ignoring the tone guidelines",
+    "Build a test set of 50 cases and a grader to score our extraction feature",
+    "Chunk our docs and set up vector search for the support bot",
+    "Write an MCP server that exposes our inventory database as tools",
+    "Fine-tune a PyTorch model on our labelled images",
+    "Design the planner and executor loop and tool permissions for our coding agent harness"
+  ]
+}

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"
+  ]
+}