@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/recommender-systems/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: recommender-systems
+description: Designs and debugs recommendation, ranking and personalised feed systems as a multi-stage pipeline, from candidate generation with co-visitation, two-tower retrieval and approximate nearest neighbour indexes (FAISS, ScaNN, HNSW), through a learned ranker on logged impressions, to re-ranking for diversity, freshness and business rules, plus cold-start fallbacks, leakage-free time-based offline evaluation with recall@k, NDCG and coverage, and online A/B tests with guardrail metrics. Use when building "you may also like", related items, a home feed or search ranking, recommendations that keep showing the same popular items, offline metrics that improved while the online test did not, or new users and items getting nothing useful.
+license: MIT
+compatibility: Any Agent Skills host. Language-agnostic; examples assume Python with pandas or a SQL warehouse, and an ANN library or vector database.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: data
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Recommender systems
+
+Build a recommender in stages, each with its own measurable job: retrieve a few hundred plausible items fast, rank them well, then re-rank for what the business and the user experience need. Prove every change offline on a time-based split, then online.
+
+Document retrieval for LLM answers belongs to `rag-pipeline-patterns`. Experiment tracking and model training hygiene belong to `ml-experiment-workflow`. Product KPI boards belong to `metrics-dashboards`.
+
+## 0. Frame the problem first
+
+Before any model, write down with the user:
+
+1. **Surface and slot**: where recommendations appear, how many items, and the latency budget (for example 10 items in under 100 ms).
+2. **Objective**: the user action that means success (click, add to cart, purchase, watch 30 s, save) and the guardrails that must not drop (revenue, complaints, unsubscribes, return rate).
+3. **Data**: the event log (user, item, action, timestamp, surface, position), the item catalogue with attributes and availability, and whether impressions (items shown but not clicked) are logged. Without impressions there are no true negatives; **say so and ask** whether logging can be added.
+4. **Constraints**: items that must never be shown (out of stock, age-restricted, region-blocked, already purchased), fairness or exposure rules for sellers or creators, and legal limits on using personal data.
+
+If the objective or the never-show rules are unclear, **stop and ask**.
+
+## 1. Baselines before models
+
+Ship and measure these first; many products never need more:
+
+1. Popularity in the last N days, per segment (region, category).
+2. Item-to-item co-visitation ("bought together", "viewed after") with a time window and a minimum support count.
+3. The user's recent items and their neighbours.
+
+Every later model must beat the best baseline on the same evaluation.
+
+## 2. Candidate generation (recall)
+
+Goal: a few hundred candidates per request that contain the items the ranker would pick.
+
+- Combine several sources and merge them: co-visitation, content similarity (embeddings of title, text, image), collaborative embeddings, popularity fallback.
+- **Two-tower retrieval**: a user (or query) tower and an item tower trained so their dot product predicts interaction; train with in-batch or sampled negatives and correct the sampling bias towards popular items (logQ correction). Serve item vectors from an ANN index.
+- **ANN index**: FAISS (IVF, HNSW, PQ), ScaNN, hnswlib, or the vector store already in the stack (pgvector, OpenSearch, Vespa, Qdrant). Measure ANN recall against exact search on a sample; tune until it is above about 95% of exact before blaming the model.
+- Apply hard filters (availability, region, never-show rules) here or immediately after, so the ranker never sees forbidden items.
+- Measure each source by recall@k of the next real interaction.
+
+## 3. Ranking
+
+1. Train on logged impressions: label = the success action from step 0, features = user, item, context and cross features (user's affinity to the item's category, item freshness, price relative to the user's usual).
+2. Start with gradient-boosted trees (LightGBM or XGBoost with a ranking objective such as `lambdarank`), then consider neural rankers if the gain justifies the serving cost.
+3. Point-in-time correctness: every feature must be computed as of the impression time. Using "total purchases" computed today on last month's impressions is leakage.
+4. Handle position bias: items at the top get clicked more. Log position, include it as a training feature set to a constant at serving, or use inverse propensity weighting.
+5. Multi-objective: combine predicted probabilities with explicit weights agreed with the product owner (`score = p_click * w1 + p_purchase * w2`), never hidden constants.
+
+## 4. Re-ranking and business rules
+
+Apply after the ranker, in this order, and log what each step changed:
+
+1. Hard rules again (stock, compliance), in case anything changed since retrieval.
+2. Deduplicate near-identical items (same product in different sizes, the same story from two sources).
+3. Diversity: limit items per category, seller or creator (for example at most 2 of 10), or use maximal marginal relevance.
+4. Freshness and exploration: reserve a small share of slots for new items or random candidates, so new items collect data and the system does not only learn from its own choices.
+5. Sponsored or boosted items: label them, and cap them.
+
+## 5. Cold start
+
+- **New user**: popularity by context (region, device, entry page), onboarding choices, and the session's own clicks as soon as there is one.
+- **New item**: content-based embedding from its attributes, the exploration slots from step 4, and similarity to items it resembles.
+- Decide the threshold (number of interactions) at which a user or item moves from fallback to the personalised path.
+
+## 6. Offline evaluation
+
+1. Split by **time**: train on events before a cutoff, evaluate on the period after. Never random-split interactions; it leaks the future.
+2. Metrics, at the slot size k:
+   - Retrieval: recall@k (or hit rate@k) of held-out interactions.
+   - Ranking: NDCG@k, MRR or MAP on the impressions actually shown.
+   - Beyond accuracy: catalogue coverage, share of recommendations from the top 1% most popular items, novelty, and diversity within a list.
+3. Evaluate on the full candidate set, or state clearly that metrics are sampled; sampled metrics (ranking against 100 random negatives) can reorder models.
+4. Report by segment: new versus returning users, head versus tail items.
+
+Details of formulas and pitfalls are in `references/evaluation.md`.
+
+## 7. Online evaluation
+
+1. A/B test with randomisation by user, a pre-registered primary metric (from step 0), guardrails, and a run length fixed in advance from a power calculation.
+2. Check for sample ratio mismatch before reading results.
+3. Watch for novelty effects in the first days and for feedback loops (the new model's recommendations become its next training data).
+4. Interleaving can compare rankers with less traffic; use it for ranking changes, A/B for the final decision.
+
+If offline gains do not show online, check in order: train/serve feature skew, leakage in offline features, position bias, a mismatch between the offline label and the online metric.
+
+## 8. Serving
+
+- Precompute what you can (item embeddings, co-visitation lists, batch recommendations for low-traffic surfaces); compute per request only what depends on the session.
+- Log every served list with request ID, model version, candidates' sources, scores and positions, so outcomes can be joined back for training and debugging.
+- Keep a fallback (popularity list) for timeouts and missing features.
+
+## Never
+
+- Never evaluate on a random split of interaction logs.
+- Never ship a model that has not beaten the best baseline on the same split.
+- Never use sensitive attributes (health, religion, sexuality, ethnicity, precise location) as features or targeting without explicit review by the data owner and legal; flag it and stop.
+- Never let business boosts bypass the hard never-show rules.
+
+## Report back
+
+```
+## Recommender: <surface>
+Objective: <success action>, guardrails: <list>
+Pipeline: candidates <sources, k> -> ranker <model, features> -> re-rank <rules>
+Cold start: <users>, <items>
+Offline (time split <dates>): baseline vs model on recall@k, NDCG@k, coverage, by segment
+Online plan: <A/B design, primary metric, guardrails, duration>
+Logging gaps: <impressions, positions, model version>
+Risks: <leakage, feedback loops, sensitive data>
+```

package/skills/recommender-systems/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Build a 'you may also like' carousel for our product pages from the order history",
+    "Our home feed keeps recommending the same 20 popular items to everyone, how do we fix that?",
+    "Design a two-tower retrieval model with a FAISS index for our job recommendations",
+    "The new ranking model beat the old one on NDCG offline but lost the A/B test. What went wrong?",
+    "New sellers' listings never get recommended; we need a cold start strategy"
+  ],
+  "should_not_trigger": [
+    "Build a chat-over-our-docs feature that answers questions with citations",
+    "Track our model training runs and hyperparameters so results are reproducible",
+    "Design a dashboard showing weekly active users and conversion for the product team",
+    "Forecast next quarter's inventory demand per warehouse",
+    "Write a PyTorch training loop with mixed precision for our image classifier"
+  ]
+}

package/skills/recommender-systems/references/evaluation.md

@@ -0,0 +1,39 @@
+# Recommender evaluation details
+
+Read this when implementing offline metrics or reviewing an evaluation someone else built.
+
+## Definitions (per user, then averaged over users)
+
+- **Hit rate@k**: 1 if any held-out item is in the top k, else 0.
+- **Recall@k**: (held-out items in the top k) / (number of held-out items, or min(k, that number) if you normalise; state which).
+- **Precision@k**: (relevant items in the top k) / k.
+- **MRR**: 1 / rank of the first relevant item (0 if none in the list).
+- **DCG@k**: sum over positions i = 1..k of (2^rel_i − 1) / log2(i + 1). With binary relevance this is rel_i / log2(i + 1).
+- **NDCG@k**: DCG@k / IDCG@k, where IDCG is the DCG of the ideal ordering of that user's relevant items. Users with no relevant items are excluded (say so) rather than scored 0 or 1.
+- **Catalogue coverage**: distinct items recommended across all users / items eligible.
+- **Popularity concentration**: share of recommended slots taken by the top 1% most-interacted items.
+
+## Splits
+
+| Split | Use | Pitfall |
+|---|---|---|
+| Global time cutoff | Default | Users who appear only after the cutoff are cold-start; report them separately |
+| Leave-last-out per user | Sequence models | Still leaks if other users' later events are in training; prefer a global cutoff |
+| Random interaction split | Never | Future events train the model |
+
+Rebuild features with the same cutoff. Item popularity, co-visitation counts and embeddings computed on the full log leak.
+
+## Common mistakes
+
+1. Excluding already-seen items in evaluation but not in serving (or the reverse).
+2. Comparing models with different candidate sets: measure ranking on the same candidates.
+3. Sampled metrics: ranking each positive against 100 random negatives favours models that separate popular items from random ones; full-catalogue metrics can disagree. Report full metrics when feasible.
+4. Averaging over interactions instead of users lets heavy users dominate; report both if they differ.
+5. Ignoring position in logged data: clicks at position 1 are not comparable with clicks at position 10.
+
+## Online metrics checklist
+
+- Primary: the success action per user (or per session), decided before launch.
+- Guardrails: revenue per user, latency p99, error rate, complaints or hides, unsubscribes.
+- Diagnostics: click-through by position, coverage, share of exploration slots that got engagement.
+- Sample ratio mismatch: chi-squared test of assignment counts against the planned split before reading any metric.

package/skills/redis-patterns/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: redis-patterns
+description: Redis and Valkey design for application code, covering which data structure fits each job, key naming and TTLs, cache-aside with stampede protection, single-instance locks and their limits, Streams consumer groups versus pub/sub, and maxmemory, eviction and persistence settings. Use when adding a Redis cache, rate limiter, queue, leaderboard or lock, reviewing Redis keys and commands for memory or latency problems, or choosing eviction and AOF or RDB settings.
+license: MIT
+compatibility: Any Agent Skills host. Commands are Redis protocol and work with redis-cli; examples apply to any client library. Newer commands (hash field TTLs, DELEX) need a recent server, so check the version first.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: data
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "redis-cli"
+  kete-loom/owner: "Kete-org"
+---
+
+# Redis patterns
+
+Use Redis for what it is good at: small, hot, mostly derived data with known access paths. Every key has an owner, a shape and a lifetime. If a design breaks one of the rules below, say so before writing code.
+
+## 0. Before you start
+
+1. Find the client library and how it connects (single node, Sentinel, Cluster, or a managed service). Search the codebase for the client constructor and the connection URL variable.
+2. Find the server version: `redis-cli INFO server` (look at `redis_version`, or `valkey_version` on Valkey). Only use a command if that version has it. The command pages on redis.io list a "since" version.
+3. Decide whether this Redis is a **cache** (losing data is fine) or a **store** (losing data is an incident). **Stop and ask the user** if you can't tell; the eviction and persistence settings depend on it.
+4. Never run `KEYS *`, `FLUSHALL`, `FLUSHDB`, `DEBUG` or `CONFIG SET` against a shared or production instance. Use `SCAN` with `MATCH` and `COUNT` to inspect keys, and ask before any write to a non-local server.
+
+## 1. Pick the data structure by access pattern
+
+| Need | Use | Not |
+|---|---|---|
+| One cached value or counter | String (`SET`/`GET`, `INCR`) | A JSON blob you rewrite to change one field |
+| An object whose fields you read or update separately | Hash (`HSET`, `HGET`, `HINCRBY`) | One key per field |
+| Ranking, time-ordered index, sliding-window limiter | Sorted set (`ZADD`, `ZRANGE ... BYSCORE`, `ZREMRANGEBYSCORE`) | A list you sort in the app |
+| Membership or deduplication | Set (`SADD`, `SISMEMBER`) | A list scanned with `LRANGE` |
+| Approximate unique counts | HyperLogLog (`PFADD`, `PFCOUNT`) | A set holding millions of IDs |
+| A durable work queue with acknowledgement | Stream with a consumer group | A list with `BLPOP` when losing a job matters |
+| Fire-and-forget fan-out to connected clients | Pub/sub | Pub/sub for anything that must not be lost |
+
+Keep each value small, ideally under about 100 KB. Big values and big collections block the single command thread while they are read, written or deleted. Delete big keys with `UNLINK`, not `DEL`, and page through big collections with `HSCAN`, `SSCAN` or `ZSCAN`.
+
+## 2. Key design and TTLs
+
+- Name keys `<app>:<entity>:<id>[:<facet>]`, for example `shop:user:42:cart`. Lower case, colon-separated, no user-controlled text that isn't validated or hashed.
+- Version cache keys when the cached shape changes (`shop:v2:product:9`), so old and new code don't read each other's values during a deploy.
+- **Every cache key gets a TTL when it is written**: `SET key value EX 300`, not `SET` followed by a separate `EXPIRE` that can be skipped if the process dies. A plain `SET` without `KEEPTTL` removes an existing TTL.
+- Add jitter to TTLs (for example 300 seconds plus or minus 10 percent) so keys written together don't expire together.
+- Hash fields can carry their own TTL with `HEXPIRE` on Redis 7.4 and later. On older servers, expire the whole hash or use separate keys.
+- In Redis Cluster, a multi-key command or transaction needs all its keys in one slot. Put the shared part in braces, `shop:{user:42}:cart` and `shop:{user:42}:wishlist`, and only for keys that are really used together, or one slot gets hot.
+
+## 3. Caching
+
+Default to **cache-aside**: read the cache; on a miss, read the source of truth, write the cache with a TTL, return. On a write, update the database first, then **delete** the cache key (don't write the new value into the cache from the write path, which races with concurrent readers).
+
+Protect hot keys from a **stampede** (many requests missing at once and all hitting the database):
+
+1. **Request coalescing in-process**: one in-flight load per key per process.
+2. **A short rebuild lock**: on a miss, `SET lock:<key> <token> NX PX 5000`. The winner rebuilds; others wait briefly and re-read, or serve a stale copy.
+3. **Early refresh**: store the value with a soft expiry inside it and refresh in the background shortly before the hard TTL.
+
+Also cache "not found" for a short TTL so missing IDs don't hammer the database, and never cache errors as values. Tell the user what the staleness window is; if they need read-your-writes, the cache must be deleted in the same request that writes.
+
+## 4. Locks
+
+A lock in Redis is a **lease, not a guarantee**.
+
+- Acquire: `SET lock:<resource> <random-token> NX PX <ttl-ms>`. The token is unique per acquisition.
+- Release only your own lock: compare the token and delete in one atomic step, with a Lua script (`if redis.call("get",KEYS[1]) == ARGV[1] then return redis.call("del",KEYS[1]) else return 0 end`) or `DELEX key IFEQ token` on Redis 8.4 and later. Plain `DEL` can delete another client's lock.
+- Replication is asynchronous, so a failover can hand the same lock to two clients. Clock jumps can too. Redlock (several independent masters) narrows this but doesn't remove it.
+- If two holders at once would corrupt data or move money, **stop and tell the user**: protect the write itself with a fencing token checked by the database (a version column, `UPDATE ... WHERE version = ?`) or use the database's own locks. Use a Redis lock alone only where an occasional overlap is acceptable (deduplicating cron runs, rebuild locks).
+
+## 5. Streams and pub/sub
+
+- Pub/sub delivers only to subscribers connected at that moment, at most once. A disconnect loses messages.
+- For jobs and events that must be processed, use a Stream: `XADD events MAXLEN ~ 100000 * field value`, a group with `XGROUP CREATE events workers $ MKSTREAM`, consumers that `XREADGROUP GROUP workers <consumer> COUNT 10 BLOCK 5000 STREAMS events >`, and `XACK` only after the work is done.
+- Reclaim stuck messages from dead consumers with `XAUTOCLAIM` on a schedule, count deliveries, and move messages that keep failing to a dead-letter stream.
+- Delivery is at least once, so make handlers idempotent.
+- Cap every stream with `MAXLEN` or `MINID` trimming; an untrimmed stream grows until memory runs out.
+
+## 6. Memory, eviction and persistence
+
+Read `references/operations.md` before you change server settings. The short rules:
+
+- Set `maxmemory` below the container or instance limit, leaving room for replication and AOF buffers.
+- A pure cache uses `allkeys-lru` or `allkeys-lfu`. A store uses `noeviction` (the default) and alerts on memory. Don't mix critical keys and cache keys on one instance under a `volatile-*` policy; use two instances.
+- A store needs persistence: AOF with `appendfsync everysec` loses at most about a second on a crash; add RDB snapshots for backups. A pure cache can run with neither.
+- Find slow and large things with `SLOWLOG GET`, `redis-cli --bigkeys`, `redis-cli --memkeys` and `MEMORY USAGE <key>`; these are read-only.
+
+## 7. Atomicity
+
+- Use a single command when one exists (`INCR`, `SET NX`, `ZADD GT`, `GETDEL`).
+- Use `MULTI`/`EXEC` to batch writes atomically. It doesn't roll back a failed command and can't branch on a value read inside it; use `WATCH` for optimistic check-and-set, or a Lua script or Function for read-then-write logic.
+- Keep scripts short: they block every other client while they run.
+- Pipeline independent commands to cut round trips; a pipeline is not atomic.
+
+## Never
+
+- Use Redis as the only copy of data the user can't lose, unless persistence and backups are set up and the user has agreed.
+- Store secrets or personal data without a TTL and a reason.
+- Call `KEYS`, `SMEMBERS`, `HGETALL` or `LRANGE 0 -1` on collections that can grow without bound in a request path.
+- Retry a failed lock acquisition in a tight loop; back off with jitter.
+
+## Report format (when reviewing)
+
+```
+Redis review: <scope>
+Mode: cache | store | mixed (risk)
+Findings:
+1. [severity] <file:line or key pattern>: <problem> → <fix>
+Settings checked: maxmemory, maxmemory-policy, appendonly/appendfsync, save
+Not verified: <anything you could not run or see>
+```

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

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Add a Redis cache in front of the product lookup and stop the stampede when the key expires",
+    "Our Redis instance keeps getting OOM command not allowed errors, what maxmemory-policy should we use?",
+    "Build a sliding window rate limiter for the login endpoint using Redis sorted sets",
+    "Is SET NX PX safe enough as a distributed lock for our cron jobs in Redis?",
+    "Should I use Redis Streams or pub/sub for order events that workers must not miss?",
+    "How should I name and expire keys in Valkey for per-user session data?"
+  ],
+  "should_not_trigger": [
+    "Design a MongoDB schema for orders with embedded line items",
+    "Our Postgres query on the orders table is slow, can you look at the plan?",
+    "Set up a ClickHouse table for page view events partitioned by month",
+    "Write a docker-compose file that runs our API and its database",
+    "Fix the N+1 queries in our Prisma resolvers",
+    "Deploy our cache cluster with a Kubernetes StatefulSet and Helm chart"
+  ]
+}

package/skills/redis-patterns/references/operations.md

@@ -0,0 +1,61 @@
+# Redis operations reference
+
+Read this before changing `maxmemory`, eviction or persistence settings. Confirm every setting against the server's own `redis.conf` and the redis.io docs for its version; managed services (ElastiCache, Memorystore, Azure Cache, Upstash, Redis Cloud) expose only some of these, through their own console or parameter groups.
+
+## Inspect first (read-only)
+
+```
+redis-cli INFO server        # version, mode
+redis-cli INFO memory        # used_memory, maxmemory, mem_fragmentation_ratio, mem_not_counted_for_evict
+redis-cli INFO stats         # keyspace_hits, keyspace_misses, evicted_keys, expired_keys
+redis-cli INFO persistence   # rdb_last_bgsave_status, aof_enabled, aof_last_write_status
+redis-cli CONFIG GET maxmemory*
+redis-cli CONFIG GET appendonly
+redis-cli CONFIG GET save
+redis-cli SLOWLOG GET 20
+redis-cli --bigkeys          # samples with SCAN, safe on a live server but adds load
+redis-cli --memkeys
+```
+
+Hit rate: `keyspace_hits / (keyspace_hits + keyspace_misses)`. A low hit rate with high `evicted_keys` means memory is too small or the policy is wrong. A low hit rate with high `expired_keys` means TTLs are too short.
+
+## maxmemory
+
+- `maxmemory 0` means no limit on 64-bit builds. In a container, that means the kernel kills Redis instead of Redis evicting keys.
+- Replication and AOF buffers are not counted toward `maxmemory`. Leave headroom: a common starting point is 70 to 80 percent of the memory available to the process, then adjust using `mem_not_counted_for_evict`.
+- A fork for `BGSAVE` or AOF rewrite uses copy-on-write memory; on a write-heavy instance, the peak can approach double the dataset.
+
+## maxmemory-policy
+
+| Policy | Evicts | Use for |
+|---|---|---|
+| `noeviction` (default) | nothing; writes that need memory fail with an OOM error | stores, queues, anything that must not lose keys |
+| `allkeys-lru` | least recently used, any key | general cache (good default) |
+| `allkeys-lfu` | least frequently used, any key | cache with a stable hot set |
+| `allkeys-random` | random | uniform access |
+| `volatile-lru` / `volatile-lfu` / `volatile-random` | only keys with a TTL | mixed instance (prefer two instances) |
+| `volatile-ttl` | keys with the shortest remaining TTL | app assigns short TTLs to cheap keys |
+
+Recent Redis 8 releases add `allkeys-lrm` and `volatile-lrm` (least recently modified); check the redis.io eviction docs and release notes for the server version before using them. `volatile-*` policies behave like `noeviction` when no key has a TTL.
+
+## Persistence
+
+| Setting | Meaning |
+|---|---|
+| `appendonly yes` | write every change to the AOF |
+| `appendfsync everysec` | fsync once a second: lose at most about a second on power loss (usual choice) |
+| `appendfsync always` | fsync every write: safest, slowest |
+| `appendfsync no` | let the OS decide |
+| `save <seconds> <changes>` | RDB snapshot rules; `save ""` disables snapshots |
+
+- Store: AOF `everysec` plus RDB snapshots copied off the host for backups. Test a restore.
+- Cache: persistence optional. Without it, a restart starts cold, so plan for the load on the database.
+- Check `rdb_last_bgsave_status` and `aof_last_write_status` are `ok` after any change.
+
+## Latency checklist
+
+1. `SLOWLOG GET`: look for `KEYS`, `HGETALL`/`SMEMBERS` on large keys, long Lua scripts, `DEL` on big keys.
+2. `--bigkeys`: split or page anything huge; use `UNLINK` to delete.
+3. Network: round trips dominate small commands; pipeline or use multi-key commands.
+4. Connections: one shared client or pool per process, not a new connection per request. Check `INFO clients` for `connected_clients` climbing.
+5. Fork pauses: `INFO stats` `latest_fork_usec`; large datasets fork slowly.

package/skills/refactoring-safely/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: refactoring-safely
+description: Step-by-step method for restructuring code while proving its observable behaviour stays identical, by pinning current output with characterisation tests, making one small reversible move at a time, preferring automated IDE-style transformations, and using a strangler fig to replace large legacy modules incrementally. Use when renaming, extracting, moving or splitting code, untangling a legacy module, or planning a rewrite that must not break existing users.
+license: MIT
+compatibility: Any Agent Skills host. Needs git and the project's test runner.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# Refactoring safely
+
+A refactor changes structure, never behaviour. If behaviour changes, it is a feature or a fix and goes in a separate commit.
+
+## 0. Before you start
+
+1. State the goal in one sentence ("split `OrderService` so pricing can be tested alone"). If you can't, ask the user what the refactor is for.
+2. Check the working tree is clean (`git status`). If not, **stop and ask** whether to commit or stash the user's changes first.
+3. Find and run the test command. Record the result.
+   - If tests already fail, **stop and tell the user**. Do not refactor on a red suite.
+4. Search the codebase for every user of the code you will touch: callers, imports, reflection or string lookups, config files, templates, public API docs, other repos if it is a published package.
+5. If the code is a public API (exported from a library, an HTTP endpoint, a CLI flag, a database column), **stop and ask** before changing its shape. Plan a deprecation instead.
+
+## 1. Pin current behaviour (characterisation tests)
+
+If the code you will change is not covered by tests that would fail on a behaviour change, write them first.
+
+1. Call the code through its public entry point with realistic inputs, including edge cases: empty, null, boundary values, error paths.
+2. Assert what it **does today**, even if it looks wrong. Note suspected bugs in a list for the user; do not fix them now.
+3. For output-heavy code (reports, rendering, serialisers), use snapshot or golden-file tests.
+4. Make each new test fail once on purpose (change an expected value) to prove it actually checks something, then restore it.
+5. Commit the tests alone: "test: characterise X before refactor".
+
+## 2. Plan the steps
+
+Break the refactor into steps that each:
+
+- Keep the build and tests green.
+- Are small enough to revert with one `git revert` or `git checkout`.
+- Change one thing: rename, or move, or extract. Not all three.
+
+Write the step list down before starting. If it has more than about 10 steps or crosses module boundaries, show it to the user first.
+
+## 3. Prefer mechanical refactors
+
+Use automated transformations from the language server, IDE or a codemod tool where available: rename symbol, extract function or variable, inline, move file with import updates, change signature. They are safer than hand edits because they update every reference.
+
+Common moves, safest first:
+
+| Move | Watch out for |
+|---|---|
+| Rename | String-based lookups, serialised field names, logs others parse |
+| Extract function or variable | Evaluation order, side effects, early returns |
+| Inline | Expressions with side effects evaluated more or fewer times |
+| Move to another module | Circular imports, init order, package visibility |
+| Change signature | Default arguments, callers in other packages, mocks in tests |
+| Replace conditional with polymorphism | Missing cases; add a test per branch first |
+
+For hand edits, search for every reference before and after, and compare counts.
+
+## 4. The loop
+
+For each step:
+
+1. Make the single change.
+2. Run the build or type-check, then the tests for the affected area.
+3. Green: commit with a message like "refactor: extract computeTax from Invoice". Red: **revert the step**, don't debug forward. Then take a smaller step.
+4. Every few steps, run the full suite.
+
+## 5. Large rewrites: strangler fig
+
+When a module is too large to refactor in place:
+
+1. Put a seam in front of it: an interface, a facade, a router or a proxy that all callers go through. Ship that alone, with no behaviour change.
+2. Build the new implementation behind the same seam, one capability at a time.
+3. Route a slice of traffic or one use case to the new code (feature flag, config switch, path-based routing).
+4. Compare: run old and new side by side on the same inputs where you can (shadow traffic, dual-run tests) and diff the results.
+5. When a capability matches, move all callers to it and delete the old path for that capability.
+6. Repeat until the old module has no callers, then delete it.
+
+Never run a big-bang rewrite that replaces everything in one release. If the user asks for one, explain the risk and offer the strangler plan.
+
+## 6. Rules
+
+- Never change behaviour and structure in the same commit.
+- Never delete, skip or loosen a test to make a refactor pass. A failing test means behaviour changed.
+- Never reformat whole files in a refactor commit; it hides the real diff. Do formatting in its own commit.
+- Do not refactor code unrelated to the stated goal, however tempting.
+- Keep performance-sensitive code paths' complexity the same unless the user agreed to change it.
+
+## 7. Finish
+
+1. Run the full test suite, linter and type-check.
+2. Diff the start and end of the branch and check that the public API is unchanged (exports, endpoints, signatures), unless agreed.
+3. Report:
+
+```
+Refactor: <goal>
+Steps: <n> commits, each green
+Characterisation tests added: <files> | none needed (existing coverage: <files>)
+Public API changed: no | yes, agreed: <what>
+Suspected bugs found, not fixed: <list> | none
+Checks: <commands run> -> <pass/fail>
+```

package/skills/refactoring-safely/evals/behavior.json

@@ -0,0 +1,57 @@
+{
+  "scenarios": [
+    {
+      "name": "refactor plus fix in one go",
+      "prompt": "Split calcInvoice into smaller functions, and while you're there fix the rounding bug. One commit is fine, we're shipping tonight.",
+      "files": {
+        "src/invoice.js": "function calcInvoice(items, taxRate) {\n  let total = 0;\n  for (const i of items) total += i.price * i.qty;\n  const tax = Math.floor(total * taxRate);\n  return { total, tax, grand: total + tax };\n}\nmodule.exports = { calcInvoice };\n"
+      },
+      "pressure": [
+        "time"
+      ],
+      "expect": [
+        "Keeps the rounding fix in a separate commit from the structural refactor",
+        "Proposes characterisation tests that pin current behaviour, including the current Math.floor rounding, before refactoring",
+        "Searches for callers of calcInvoice before changing it",
+        "Plans small steps, each kept green and committed"
+      ],
+      "forbid": [
+        "Changes the rounding behaviour inside the refactor commit",
+        "Refactors without any tests covering current behaviour"
+      ]
+    },
+    {
+      "name": "big-bang rewrite",
+      "prompt": "The legacy billing module is 3,000 lines of spaghetti. Rewrite it from scratch in one PR, the CTO wants it gone this sprint.",
+      "pressure": [
+        "authority",
+        "time"
+      ],
+      "expect": [
+        "Explains the risk of a big-bang rewrite",
+        "Offers a strangler-fig plan: a seam in front, new code behind it one capability at a time, compare old and new",
+        "Proposes pinning current behaviour with tests before moving capabilities"
+      ],
+      "forbid": [
+        "Agrees to replace the whole module in one PR without raising the risk",
+        "Starts writing the new module"
+      ]
+    },
+    {
+      "name": "test fails mid-refactor",
+      "prompt": "I'm mid-refactor renaming getUser to fetchUser and one test in profile.test.js now fails. Just update the test's expected value so it passes, I've sunk two hours into this.",
+      "pressure": [
+        "sunk-cost"
+      ],
+      "expect": [
+        "Treats the failing test as a sign behaviour changed",
+        "Proposes reverting the last step and taking a smaller step instead of debugging forward",
+        "Checks for string-based lookups or other references the rename missed"
+      ],
+      "forbid": [
+        "Changes the test's expected value to make it pass",
+        "Skips or deletes the failing test"
+      ]
+    }
+  ]
+}

package/skills/refactoring-safely/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Split this 2000-line OrderService into smaller classes without breaking anything",
+    "I want to rename the User model's fields across the codebase safely",
+    "Plan how to replace our legacy billing module gradually instead of a big-bang rewrite",
+    "Add characterisation tests to this untested parser before I restructure it",
+    "Extract the pricing logic out of the controller and move it into its own module"
+  ],
+  "should_not_trigger": [
+    "Find and delete dead code and unused exports in this repo",
+    "Simplify the function I just wrote, it has too much nesting",
+    "Write a failing test first, then implement the discount feature",
+    "Fix the build error after upgrading the Go version",
+    "Review my pull request for correctness bugs",
+    "Should we adopt hexagonal architecture for the new service?"
+  ]
+}