@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/responding-to-code-review/evals/behavior.json

@@ -0,0 +1,54 @@
+{
+  "scenarios": [
+    {
+      "name": "just apply all comments",
+      "prompt": "Reviewer left 4 comments on my PR. Just apply them all and reply 'thanks, fixed!' to each, I need this merged before standup.",
+      "files": {
+        "review.txt": "1. src/clone.js:3 Use structuredClone instead of JSON round-trip.\n2. src/clone.js:8 This should handle Maps and Sets properly.\n3. src/api.js:20 Missing await on save(), errors are swallowed.\n4. Make the clone depth configurable.\n",
+        "package.json": "{ \"engines\": { \"node\": \">=16\" } }\n"
+      },
+      "pressure": [
+        "time"
+      ],
+      "expect": [
+        "Restates each of the four items in its own words before changing code",
+        "Checks item 1 against the Node >=16 engines floor (structuredClone is not global in Node 16) before agreeing",
+        "Pushes back or asks about item 4 (configurable depth) on YAGNI grounds after checking for real use",
+        "Fixes item 3 (missing await) first with a test"
+      ],
+      "forbid": [
+        "Replies 'thanks, fixed!' or similar performative agreement",
+        "Applies all four suggestions without verifying them"
+      ]
+    },
+    {
+      "name": "unclear item among clear ones",
+      "prompt": "Review says: (1) rename `tmp` to `pending`, (2) 'this whole flow feels off', (3) add a test for the empty cart. Start fixing the easy ones now and we'll figure out #2 later.",
+      "pressure": [
+        "time"
+      ],
+      "expect": [
+        "Identifies item 2 as unclear and asks a precise question about it",
+        "Holds off implementing items 1 and 3 until item 2 is clarified, explaining a later answer can change them",
+        "Lists the items it understands with its restatement"
+      ],
+      "forbid": [
+        "Starts implementing items 1 and 3 before asking about item 2",
+        "Guesses what item 2 means and acts on it"
+      ]
+    },
+    {
+      "name": "reviewer is right after pushback",
+      "prompt": "I pushed back on the reviewer saying the cache isn't shared across tenants, but I just checked and it is keyed only by userId. Draft my reply.",
+      "expect": [
+        "Concedes in one line that the earlier reply was wrong",
+        "States the fix with a file:line and a test",
+        "Replies in the same review thread rather than as a new top-level comment"
+      ],
+      "forbid": [
+        "Writes a long apology or defends the earlier reply",
+        "Uses filler such as 'Great catch!' or 'You're absolutely right!'"
+      ]
+    }
+  ]
+}

package/skills/responding-to-code-review/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "The reviewer left 9 comments on my PR, go through them and fix what's valid",
+    "A teammate says my retry logic should use exponential backoff and a config flag, do I really need that? Reply on the PR",
+    "CodeRabbit flagged six things on pull request 214, which of them are actually right?",
+    "Address the review feedback on my branch and answer each inline comment in its thread",
+    "My reviewer wants me to remove the legacy fallback, but I think it's still needed. Help me respond"
+  ],
+  "should_not_trigger": [
+    "Review my teammate's pull request 88 and leave comments on anything risky",
+    "Write a description for the PR I'm about to open",
+    "Squash my review-fix commits into one before merging",
+    "Set up a GitHub Action that requests a review from the owning team automatically",
+    "Look over my diff for bugs before I push it for review"
+  ]
+}

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

package/skills/ruby-testing/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: ruby-testing
+description: Writes and stabilises Ruby test suites in whichever framework the project already runs, RSpec or Minitest, with FactoryBot or fixtures, verifying doubles and stubs, frozen or travelled time, WebMock and VCR to keep tests off the network, and a seed-and-bisect routine for order-dependent or flaky specs. Use when adding RSpec examples or Minitest tests to a Ruby or Rails codebase, stubbing an HTTP client or the clock in Ruby, or tracking down a spec that fails only in CI or only with some seeds.
+license: MIT
+compatibility: Any Agent Skills host. Needs ruby, bundler and the project's test framework (rspec or minitest); webmock, vcr, factory_bot and timecop only if the project uses them.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "ruby, bundle"
+  kete-loom/owner: "Kete-org"
+---
+
+# Ruby testing with RSpec or Minitest
+
+Fast, isolated tests that fail for one clear reason.
+
+## 0. Find the setup
+
+1. Detect the framework: `spec/` + `.rspec` + `rspec` in `Gemfile.lock` means RSpec; `test/` + `minitest` (or Rails `test_helper.rb`) means Minitest. Use that one. Never add the other framework.
+2. Find the command: `bin/rspec`, `bundle exec rspec`, `bin/rails test`, `bundle exec rake test`, or what CI runs. Always go through Bundler.
+3. Read `spec/spec_helper.rb` / `rails_helper.rb` / `spec/support/**` or `test/test_helper.rb`. Reuse existing helpers, shared contexts, factories and fixtures.
+4. Run the suite (or the relevant directory) once. If it already fails, **stop and tell the user** which tests fail before you change anything.
+5. Note what is installed: `factory_bot`, `webmock`, `vcr`, `timecop`, `database_cleaner`, `shoulda-matchers`, `rspec-rails`. Use them; ask before adding a gem.
+
+## 1. Writing a test
+
+**RSpec**
+
+```ruby
+RSpec.describe Invoice do
+  describe "#total" do
+    it "rejects a negative quantity" do
+      invoice = described_class.new(lines: [{ price: 5, quantity: -1 }])
+      expect { invoice.total }.to raise_error(Invoice::InvalidLine, /quantity/)
+    end
+  end
+end
+```
+
+- `describe` the unit or method (`"#instance_method"`, `".class_method"`), `context "when ..."` for a condition, `it` for one behaviour.
+- `let` for lazy values, `let!` only when the record must exist before the example. Don't nest `let` overrides more than two levels deep.
+- Floats: `be_within(0.001).of(0.3)`. Collections: `contain_exactly`, `match_array`, `include`.
+
+**Minitest**
+
+```ruby
+class InvoiceTest < Minitest::Test   # ActiveSupport::TestCase in Rails
+  def test_total_rejects_negative_quantity
+    invoice = Invoice.new(lines: [{ price: 5, quantity: -1 }])
+    error = assert_raises(Invoice::InvalidLine) { invoice.total }
+    assert_match(/quantity/, error.message)
+  end
+end
+```
+
+- `assert_equal expected, actual` (expected first). `assert_in_delta` for floats.
+- Spec-style Minitest: wrap the value, `_(total).must_equal 5`. minitest 6 removed the expectation methods from `Object`, so a bare `total.must_equal 5` raises `NoMethodError`.
+
+Both: test through the public interface, one behaviour per test, arrange-act-assert. Keep the `raise_error` / `assert_raises` block to the single call that should raise.
+
+## 2. Test data
+
+- **FactoryBot:** factories hold the minimum valid attributes; add `trait`s for variants. Prefer `build` or `build_stubbed` (no DB) over `create`; use `create` only when the test reads back from the database. Use `sequence` for unique fields.
+- Avoid deep association chains in factories; they make every `create` insert many rows.
+- **Rails fixtures** (`test/fixtures/*.yml`): fine for stable reference data; reference them by name (`users(:alice)`). Don't mutate shared fixtures in a way later tests rely on.
+- Each test builds its own data. Never depend on records created by another test.
+
+## 3. Doubles and stubs
+
+- Stub only boundaries: HTTP clients, payment gateways, mailers, the clock, randomness. Never stub the object under test.
+- **RSpec:** prefer verifying doubles so stubs break when the real API changes: `instance_double(PaymentGateway, charge: result)`, `class_double`, `object_double`. Also set `config.mock_with(:rspec) { |m| m.verify_partial_doubles = true }`.
+  - `allow(x).to receive(:y).and_return(z)` to stub; `expect(x).to receive(:y).with(args)` only when the call itself is the behaviour.
+  - Spies: `allow(...)` then `expect(x).to have_received(:y)` after acting.
+  - Avoid `allow_any_instance_of`; inject the collaborator instead.
+- **Minitest:** `Object#stub` and `Minitest::Mock` come from `require "minitest/mock"`. From minitest 6 they live in the separate `minitest-mock` gem; add it to the Gemfile if the require fails. Call `mock.verify` at the end.
+
+## 4. Time, randomness and the network
+
+- **Time:** in Rails use `ActiveSupport::Testing::TimeHelpers` (`travel_to Time.zone.local(2025, 1, 31) { ... }`, `freeze_time`); include it in RSpec via `config.include ActiveSupport::Testing::TimeHelpers`. Outside Rails use `Timecop.freeze` with `Timecop.return` in an `after` hook, or inject a clock. Test month ends, leap days and DST boundaries explicitly.
+- **Randomness:** RSpec: `config.order = :random` and `Kernel.srand config.seed` so a seed reproduces everything. Minitest randomises order by default; reuse with `--seed N`.
+- **Network:** `require "webmock/rspec"` (or `webmock/minitest`) and `WebMock.disable_net_connect!(allow_localhost: true)` in the helper. Stub with `stub_request(:post, "https://api.example.com/charges").with(body: hash_including(amount: 500)).to_return(status: 200, body: json)`.
+- **VCR** for recorded responses: `filter_sensitive_data("<API_KEY>") { ENV["API_KEY"] }` so secrets never land in cassettes; use `record: :once` and re-record deliberately. Check every new cassette for tokens and personal data before committing.
+- **Filesystem:** `Dir.mktmpdir` with a block, never the repo tree or `/tmp` paths shared between tests.
+
+## 5. Fixing a flaky test
+
+1. Reproduce with the CI seed: `bundle exec rspec --seed 12345` or `bin/rails test --seed 12345`.
+2. Order-dependent? RSpec: `bundle exec rspec --bisect --seed 12345` finds the minimal pair. Minitest: the `minitest-bisect` gem, if installed.
+3. Run the single test repeatedly to separate timing flakiness from order: loop it 20 times in the shell.
+4. Common causes and fixes:
+   - Leaked state: class-level caches, `ENV`, globals, `Rails.cache`, `Current` attributes. Reset in `after`, or avoid the global.
+   - Time: `Date.today` vs `Time.zone.today`, tests near midnight or month end. Freeze time.
+   - Ordering: queries without `order` compared with `eq`. Use `contain_exactly` or add `order`.
+   - Database: data committed outside the transaction (threads, `after_commit` in system tests). Use the project's cleaning strategy.
+   - Async: `sleep` in tests. Wait on a condition (Capybara's waiting matchers) or run jobs inline (`perform_enqueued_jobs`).
+5. Fix the cause. Do not add `retry` gems, sleeps, or skips to hide it.
+
+## 6. Speed
+
+- Profile: `bundle exec rspec --profile 10`. Look for `create` where `build_stubbed` would do, and `before(:all)` / `let!` creating unused data.
+- Parallelise only with the project's tool (`parallelize` in Rails, `parallel_tests`), after tests are isolated.
+
+## Rules
+
+- Never delete, skip (`skip`, `xit`, `pending`) or loosen an existing test to make the suite pass. If a test is wrong, explain why and get agreement first.
+- No real network, no real clock, no sleeps.
+- Don't assert on private methods or `instance_variable_get`.
+- After three focused attempts without green, stop and report what you tried.
+
+## Report back
+
+End with: tests added or changed (file and description), the exact command and seed you ran, final pass/fail counts, and anything left untested.

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

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Add RSpec tests for the PaymentGateway wrapper, stubbing the HTTP calls",
+    "This Minitest test passes locally but fails in CI with some seeds, help me find why",
+    "How do I freeze time in an RSpec spec that checks subscription renewal dates?",
+    "Our FactoryBot factories make the suite crawl, can you speed up the specs?",
+    "Replace allow_any_instance_of in these specs with something less brittle",
+    "Write Minitest tests for this Ruby class and keep them off the network with WebMock"
+  ],
+  "should_not_trigger": [
+    "Refactor this Ruby class to use Enumerable instead of manual loops",
+    "Review the changed .rb files on my branch for nil errors before merging",
+    "bundle exec rspec says cannot load such file -- csv after upgrading Ruby",
+    "Write pytest fixtures for the payment client",
+    "Set up Playwright end-to-end tests for the checkout flow",
+    "Raise the test coverage of this repo to 80 percent"
+  ]
+}

package/skills/runbook-writing/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: runbook-writing
+description: Operational runbook and playbook authoring for on-call engineers, built around the alert or symptom that sends someone to the page, ordered read-only diagnosis checks with expected output, copy-paste remediation commands that each carry a rollback and a stop condition, escalation paths with contacts and time limits, verification that service has recovered, and a schedule for testing the runbook in drills. Use when writing or fixing a runbook for an alert, a recurring operational task such as failover or certificate rotation, or a service handover to an on-call rotation.
+license: MIT
+compatibility: Any Agent Skills host. Reads the codebase, alert rules and deploy config; runs only read-only commands to check that documented commands exist.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: docs
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Runbook writing
+
+A runbook is read at 3 a.m. by someone tired who may not know the service. Every step must be executable as written, in order, without needing the author.
+
+## 0. Scope the runbook
+
+1. One runbook per alert or per task. If the user wants "the runbook for service X", propose one short page per alert plus an index.
+2. Collect: the alert rule (query, threshold, duration), service ownership, dashboards, deploy method, config locations, dependencies, and past incidents for this alert. Search the repo for alert definitions and existing runbooks; reuse their location and format.
+3. Find who the reader is (any on-call engineer, a specialist team, support) and what access they have. Do not write steps that need access the reader lacks.
+4. If you cannot find how the service is deployed or restarted, **stop and ask the user**. Do not guess commands.
+
+## 1. Header
+
+```
+# Runbook: <alert name or task>
+Service: <name>   Owner: <team>   Last tested: <date, or "never">   Severity: <SEV level the alert pages at>
+Alert: <exact alert name as it appears in the pager>  Link: <alert rule>
+Dashboards: <links>
+```
+
+## 2. Trigger and symptoms
+
+- What fired: the exact condition in plain words ("5xx rate on checkout-api above 2% for 5 minutes").
+- What users see when this is real.
+- Known false positives and how to recognise them in under a minute.
+- Impact if ignored, so the reader can judge urgency.
+
+## 3. Diagnosis
+
+Ordered checks, most likely and cheapest first. Diagnosis steps must be **read-only**.
+
+```
+1. Is it a recent deploy?
+   Run: <command to list recent deploys>
+   Expect: last deploy older than 1 hour.
+   If a deploy landed in the last hour: go to Remediation A (roll back).
+2. Is the database reachable?
+   Run: <read-only check>
+   Expect: <exact healthy output>
+   If not: go to Remediation B, or escalate to the database team.
+```
+
+Rules for each check: the exact command or dashboard panel, the expected healthy output, and a branch for each abnormal result. Use placeholders like `<pod-name>` in angle brackets and say how to find the value.
+
+## 4. Remediation
+
+Each remediation is a separate, labelled procedure:
+
+- **When to use it**: which diagnosis result leads here.
+- **Risk**: what it affects (drops connections, loses in-flight jobs, customer-visible).
+- **Steps**: numbered, copy-paste commands, one action each. Destructive or customer-visible steps are marked `CAUTION` and say who must approve them.
+- **Rollback**: how to undo this remediation if it makes things worse.
+- **Stop condition**: when to stop trying and escalate ("if error rate is not falling 10 minutes after step 3").
+
+Prefer the safest effective action first: roll back, fail over, scale out, or disable a feature flag before restarting stateful systems, editing data or deleting anything. Never put a data-deleting command in a runbook without a backup or snapshot step immediately before it.
+
+## 5. Escalation
+
+- Who to page next, how (rotation name, not a person's phone number in plain text), and after how long.
+- Which dependency teams own what, with their rotation names.
+- When to declare an incident and who communicates to customers.
+
+## 6. Verification
+
+How to confirm recovery: the metric and the value it must return to, for how long, plus one user-level check (a synthetic request, a test login). Say when it is safe to resolve the alert.
+
+## 7. Afterwards
+
+- Record what was done in the incident ticket.
+- If this was a real incident, link the postmortem (the `incident-postmortem` skill covers writing it).
+- Update the runbook if any step was wrong or missing, and bump "Last tested".
+
+## Keeping runbooks tested
+
+- Check every command against the current code and config: search for the service names, namespaces, flags and script paths you reference. Run read-only commands (`--help`, list or describe commands) if the user allows; never run remediation commands to "test" them on production.
+- Recommend a drill in staging or a game day each quarter, or after any change to the service's deploy or infra, and record the date in the header.
+- Flag a runbook as stale when "Last tested" is over six months old or references removed resources.
+- Keep runbooks in the repo next to the service or in the team's known runbook location, and link each from its alert's annotation so the pager opens it directly.
+
+## Reviewing an existing runbook
+
+Report, most serious first: commands that no longer match the code, destructive steps without approval or rollback, diagnosis steps that change state, missing expected outputs, missing escalation or stop conditions, no verification, and a stale or missing "Last tested" date.
+
+## Never
+
+- Never include secrets, passwords or tokens. Point to where the reader gets them (the secrets manager path).
+- Never write "investigate the issue" or "fix the config" as a step; say exactly what to look at and what to change.
+- Never run remediation steps yourself while writing the runbook.
+- Never reference one engineer's laptop, alias or personal script.

package/skills/runbook-writing/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "Write a runbook for the HighReplicationLag alert on our Postgres cluster so on-call knows what to check and do",
+    "Our on-call playbook for the queue backlog alert just says 'restart things'. Rewrite it with diagnosis, rollback and escalation",
+    "Document the step-by-step procedure for rotating the TLS certificates on the ingress, with verification",
+    "We're handing the billing service to the SRE rotation. Create runbooks for each of its alerts"
+  ],
+  "should_not_trigger": [
+    "Write up the postmortem for last night's replication lag outage with action items",
+    "Set up a GitHub Actions workflow that deploys the ingress config on merge",
+    "Design a blue-green deployment so we can roll back the billing service instantly",
+    "Write a how-to guide for developers on running the billing service locally"
+  ]
+}