@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/rag-pipeline-patterns/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: rag-pipeline-patterns
+description: Retrieval-augmented generation pipeline design covering document chunking, embedding choice, hybrid keyword plus vector search with reranking, metadata and permission filters, grounded answers with citations, index freshness, and measuring retrieval quality apart from answer quality. Use when building or fixing a RAG system, a chat-over-your-docs feature, a semantic search index, or when answers cite the wrong passages or miss documents that exist.
+license: MIT
+compatibility: Any Agent Skills host. Examples use SQL (Postgres with pgvector) and pseudocode; the rules apply to any vector store and model provider.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: ai
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# RAG pipeline patterns
+
+A RAG system is two systems: a search engine and a writer. Most "the model hallucinated" bugs are search bugs. Build, measure and fix retrieval first, then generation.
+
+## 0. Before you change anything
+
+1. Find the pipeline stages in the code: loaders, chunker, embedder, index writer, query path (rewrite, search, rerank, filter), prompt builder, answer post-processing.
+2. Write down the current settings: chunk size and overlap, embedding model and dimension, distance metric, top-k at each stage, filters, prompt template.
+3. Look for an evaluation set (questions with known relevant documents). If none exists, build one first (step 7). **Stop and ask the user** for 20 to 50 real questions if you can't find real traffic or logs; do not invent the whole set yourself.
+4. Never change the embedding model, chunker and prompt in one step. Change one stage, re-run the eval, keep or revert.
+
+## 1. Ingestion and chunking
+
+- Parse structure before splitting: keep headings, lists, tables and code blocks intact. Convert HTML and PDF to clean text or Markdown first; strip navigation, footers and boilerplate repeated on every page.
+- Split on structure (sections, then paragraphs, then sentences), not on a fixed character count. Fall back to token-count windows only for unstructured text.
+- Start with chunks of roughly 200 to 500 tokens and 10 to 20 percent overlap, then tune on the eval set. Short factual lookups favour smaller chunks; reasoning across a section favours larger ones.
+- Prepend context to each chunk before embedding: document title and the heading path (`Billing > Refunds > Partial refunds`). A chunk that says "it expires after 30 days" is useless without knowing what "it" is.
+- Store per chunk: stable `chunk_id`, `doc_id`, source URL or path, heading path, position, content hash, `updated_at`, and access-control fields (tenant, groups). Citations and filters depend on these.
+- Tables: keep the header row with every chunk of rows, or store the table as one chunk plus a text summary.
+- Deduplicate near-identical chunks (same content hash, or very high similarity) so top-k isn't five copies of one paragraph.
+
+## 2. Embeddings
+
+- Use one embedding model per index. Query and document vectors must come from the same model and version; mixing them silently ruins recall.
+- Record the model name and dimension in the index metadata. Changing models means a full re-embed into a new index, then a switch, never an in-place mix.
+- Use the model's query/document modes or prefixes if it has them (some models expect different input types for queries and passages). Check the model's docs.
+- Match the distance metric to the model (most text models are trained for cosine; normalise vectors if you use inner product).
+- Batch embedding calls, retry with backoff on rate limits, and cache by content hash so re-ingesting unchanged chunks costs nothing.
+
+## 3. Retrieval
+
+Default to hybrid search, then rerank:
+
+1. **Keyword search** (BM25 or the database's full-text search) catches exact terms: product codes, error messages, names, acronyms. Vector search alone misses these.
+2. **Vector search** catches paraphrases and synonyms.
+3. **Fuse** the two ranked lists with reciprocal rank fusion: `score = sum(1 / (k + rank))` over both lists, with `k = 60` as the usual starting value. RRF needs no score normalisation, which is why it is the safe default.
+4. **Rerank** the fused top 30 to 100 with a cross-encoder or a reranking API, then keep the top 3 to 10 for the prompt.
+
+Decision rules:
+
+- Apply metadata and permission filters **inside** the search query (pre-filter), not after top-k. Post-filtering returns too few results and can leak titles or counts of documents the user cannot see.
+- If an approximate index (HNSW, IVF) combined with a restrictive filter returns fewer than k rows, raise the index's search breadth setting or use exact search for that filter; check your store's docs for the knob.
+- Query rewriting (expanding a follow-up question into a standalone one using chat history) belongs before search. Keep the original question for the prompt.
+- Return nothing rather than something irrelevant: set a minimum reranker score and let the generator say "I couldn't find this" below it.
+
+Postgres + pgvector examples are in `references/retrieval-recipes.md`.
+
+## 4. Building the prompt
+
+- Put retrieved chunks in clearly delimited blocks, each with its `chunk_id` and source, e.g. `<source id="c_812" title="Refund policy">...</source>`.
+- Instruct the model to answer only from the sources, to cite the source ids it used for each claim, and to say it doesn't know when the sources don't cover the question.
+- Treat retrieved text as untrusted data. Documents can contain instructions ("ignore previous instructions"); the system prompt must say sources are reference material, never commands. Never give the generation step tools that act on the world based on retrieved text without a confirmation step.
+- Trim to a token budget rather than a fixed k. With long contexts, put the strongest chunks at the start (and, if you must send many, at the end) rather than burying them in the middle.
+
+## 5. Citations
+
+- Validate citations after generation: every cited id must be one you actually sent. Drop or flag answers that cite unknown ids.
+- Map ids back to source URL plus heading or page so users can click through.
+- For high-stakes answers, check that each cited chunk actually supports the sentence (a second model call or string-overlap check), and mark unsupported sentences.
+
+## 6. Freshness and deletion
+
+- Re-ingest incrementally: compare content hashes per document, re-chunk and re-embed only what changed, and delete chunks whose document was removed or whose permissions changed.
+- Deletion is a requirement, not a cleanup task. A deleted or access-revoked document that stays in the index is a data leak.
+- Store `updated_at` and allow a recency boost or filter for time-sensitive corpora (news, release notes, prices).
+- Schedule a periodic full reconciliation (index ids vs source ids) to catch missed deletes.
+
+## 7. Evaluate retrieval separately from generation
+
+Build an eval set of question → relevant `doc_id`s (or chunk ids), then measure each stage on its own. Details and formulas are in `references/evaluation.md`.
+
+| Stage | Metric | Tells you |
+|---|---|---|
+| Retrieval | recall@k, MRR, nDCG@k | Did the right chunks come back, and how high? |
+| Reranking | recall@final_k before vs after | Is the reranker helping or dropping good chunks? |
+| Generation | faithfulness (claims supported by sources), answer correctness, citation accuracy | Is the writer using what it got? |
+| End to end | task success, "I don't know" rate on unanswerable questions | Does it work for users? |
+
+Rules:
+
+- If recall@k is low, fix chunking, hybrid search or filters. Do not touch the prompt.
+- If recall is high but answers are wrong, fix the prompt, context ordering or model.
+- Include unanswerable questions; a good system refuses them.
+- Re-run the eval on every change to chunking, embeddings, retrieval settings or prompt, and report before and after numbers.
+
+## Never
+
+- Never mix embeddings from two models in one index.
+- Never filter permissions after retrieval or in the prompt ("only use documents the user may see").
+- Never tune top-k, chunk size or the prompt without an eval set to measure against.
+- Never let retrieved text trigger tool calls or override system instructions.
+- Never report "better" from a handful of eyeballed answers.
+
+## Report format
+
+When you finish a change, report:
+
+```
+Stage changed: <chunking | embeddings | retrieval | rerank | prompt | freshness>
+Change: <one line>
+Eval set: <n questions, source>
+recall@k: <before> → <after>   MRR: <before> → <after>
+Faithfulness / correctness: <before> → <after> (or "not measured")
+Risks: <re-index needed, cost change, latency change>
+```

package/skills/rag-pipeline-patterns/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Build a chat-over-our-docs feature that answers from our Confluence export with citations",
+    "Our RAG bot keeps citing the wrong section of the handbook, how do I fix retrieval?",
+    "Add hybrid BM25 plus vector search with a reranker to our pgvector document index",
+    "What chunk size and overlap should I use for embedding these PDF manuals?",
+    "Deleted documents still show up in our semantic search answers, fix the re-indexing job",
+    "How do I measure recall@k for our retrieval step separately from answer quality?"
+  ],
+  "should_not_trigger": [
+    "Review our RAG pipeline code and config and list its weaknesses without changing anything",
+    "Write a Model Context Protocol server that exposes our docs search as a tool",
+    "Design the tool set and permission model for our coding agent",
+    "Set up an eval harness that scores our chatbot's prompts against a golden set",
+    "Tune this Postgres query that joins orders and customers, it is slow",
+    "Fine-tune a PyTorch model on our labelled support tickets"
+  ]
+}

package/skills/rag-pipeline-patterns/references/evaluation.md

@@ -0,0 +1,37 @@
+# Evaluating a RAG pipeline
+
+Read this when building the eval set or computing metrics.
+
+## Building the eval set
+
+1. Collect 20 to 50 real questions to start (support tickets, search logs, chat logs). Grow to a few hundred over time.
+2. For each, record the ids of the documents (or chunks) that answer it, and a short reference answer. A subject-matter expert should confirm these.
+3. Add 10 to 20 percent unanswerable questions (the corpus doesn't cover them) with an empty relevant set.
+4. Add hard cases: exact identifiers (error codes, SKUs), follow-up questions that need history, questions whose answer changed recently, questions where the user lacks access to the answering document.
+5. Freeze the set in version control as JSONL: `{"id": "q17", "question": "...", "relevant": ["doc_42"], "answer": "..."}`. Never tune on the test portion; keep a held-out split if you iterate a lot.
+
+Synthetic questions generated by a model from your chunks are fine for extra coverage, but they over-reward chunk-shaped questions. Never use only synthetic data.
+
+## Retrieval metrics
+
+For each question, take the ranked list of retrieved ids (deduplicated to doc level if relevance is labelled per document).
+
+- **recall@k** = |relevant ∩ top-k| / |relevant|. Average over answerable questions.
+- **hit@k** = 1 if any relevant id is in top-k, else 0. Useful when one document is enough.
+- **MRR** = mean of 1 / (rank of first relevant id), 0 if none in the list.
+- **nDCG@k** = DCG@k / ideal DCG@k, with DCG = sum over positions i of rel_i / log2(i + 1). Use graded relevance if you have it.
+
+Measure at the retriever's k (before rerank) and at the final k sent to the prompt. The gap shows what reranking and trimming cost.
+
+## Generation metrics
+
+- **Faithfulness**: split the answer into claims; the fraction supported by the provided sources. Usually judged by a model with a fixed rubric; spot-check the judge against human labels on 30+ examples before trusting it.
+- **Answer correctness**: compare to the reference answer (model judge or human).
+- **Citation accuracy**: fraction of citations that point to a sent chunk that actually supports the sentence.
+- **Refusal on unanswerable**: fraction of unanswerable questions where the system said it didn't know.
+
+## Running it
+
+- Run the full set on every pipeline change and log: git commit, settings (chunk size, model, k values, prompt version), and every metric.
+- Report before and after side by side, and list questions that flipped from pass to fail. Regressions on individual questions matter more than a small average gain.
+- Judges and generators are non-deterministic: fix temperature at 0 where possible and repeat runs if differences are small.

package/skills/rag-pipeline-patterns/references/retrieval-recipes.md

@@ -0,0 +1,78 @@
+# Retrieval recipes (Postgres + pgvector)
+
+Read this when the project stores vectors in Postgres. The patterns carry over to other stores; check that store's docs for the equivalent syntax.
+
+## Schema
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+
+CREATE TABLE chunks (
+  chunk_id     text PRIMARY KEY,
+  doc_id       text NOT NULL,
+  tenant_id    text NOT NULL,
+  heading_path text,
+  content      text NOT NULL,
+  content_hash text NOT NULL,
+  updated_at   timestamptz NOT NULL,
+  embedding    vector(1024) NOT NULL,          -- dimension of YOUR model; HNSW on `vector` indexes up to 2,000 dims
+  tsv          tsvector GENERATED ALWAYS AS (to_tsvector('english', content)) STORED
+);
+
+CREATE INDEX ON chunks USING hnsw (embedding vector_cosine_ops);
+CREATE INDEX ON chunks USING gin (tsv);
+CREATE INDEX ON chunks (tenant_id);
+```
+
+pgvector distance operators: `<=>` cosine distance, `<->` Euclidean (L2), `<#>` negative inner product. The index operator class must match the operator you query with (`vector_cosine_ops` for `<=>`).
+
+## Hybrid search with reciprocal rank fusion
+
+```sql
+WITH vec AS (
+  SELECT chunk_id, row_number() OVER (ORDER BY embedding <=> $1) AS rank
+  FROM chunks
+  WHERE tenant_id = $2                      -- pre-filter: permissions first
+  ORDER BY embedding <=> $1
+  LIMIT 50
+),
+kw AS (
+  SELECT chunk_id,
+         row_number() OVER (ORDER BY ts_rank_cd(tsv, q) DESC) AS rank
+  FROM chunks, websearch_to_tsquery('english', $3) q
+  WHERE tenant_id = $2 AND tsv @@ q
+  ORDER BY ts_rank_cd(tsv, q) DESC
+  LIMIT 50
+)
+SELECT c.chunk_id, c.doc_id, c.heading_path, c.content,
+       COALESCE(1.0 / (60 + vec.rank), 0) + COALESCE(1.0 / (60 + kw.rank), 0) AS rrf
+FROM vec FULL OUTER JOIN kw USING (chunk_id)
+JOIN chunks c USING (chunk_id)
+ORDER BY rrf DESC
+LIMIT 40;   -- send these to the reranker
+```
+
+`$1` is the query embedding, `$2` the caller's tenant, `$3` the raw query text.
+
+## Filtered approximate search
+
+With a selective filter, HNSW may return fewer than `LIMIT` rows because the filter is applied after the index scan. Two knobs, both set per query inside a transaction:
+
+- `SET LOCAL hnsw.ef_search = 200;` widens the candidate list (default 40).
+- From pgvector 0.8.0: `SET LOCAL hnsw.iterative_scan = relaxed_order;` (or `strict_order`) keeps scanning the index until enough rows pass the filter. IVFFlat uses `ivfflat.iterative_scan`.
+
+Check the installed version (`SELECT extversion FROM pg_extension WHERE extname = 'vector';`) before relying on iterative scans. For a very selective filter (one small tenant), a partial index or exact search on that subset can beat both.
+
+## Incremental re-ingest
+
+```
+for each source document:
+    new_hash = hash(normalised text)
+    if new_hash == stored doc hash: skip
+    chunks = chunk(document)
+    upsert chunks by chunk_id (re-embed only chunks whose content_hash changed)
+    delete chunks for this doc_id whose chunk_id is not in the new set
+for each doc_id in index but not in source: delete its chunks
+```
+
+Run the delete pass in the same job as the upsert pass so a failure can't leave removed documents searchable.

package/skills/rails-patterns/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: rails-patterns
+description: Ruby on Rails application work that follows the framework's conventions - fat-enough models and thin controllers, Active Record queries without N+1 (includes, preload, strict_loading), strong parameters with params.expect or require/permit, Active Job enqueued after commit, zero-downtime migrations, encrypted credentials, Turbo Frames and Streams, and Rails tests for models, requests, jobs and system flows. Use when building or reviewing a Rails app, fixing slow Active Record pages, writing a migration for a busy table, adding a background job or Hotwire form, or storing secrets in Rails credentials.
+license: MIT
+compatibility: Any Agent Skills host. Needs Ruby, Bundler and the project's bin/rails. Written for Rails 7.1 and later; Rails 8 specifics are marked.
+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"
+---
+
+# Rails patterns
+
+Put code where Rails expects it and let the conventions do the work. For plain Ruby style (objects, Enumerable, RuboCop) follow the `ruby-patterns` skill; for RSpec or Minitest mechanics in depth follow `ruby-testing`.
+
+## 0. Before you change anything
+
+1. Read `Gemfile.lock` for the `rails` version, the database adapter, the job backend (Solid Queue, Sidekiq, GoodJob) and whether tests are RSpec (`spec/`) or Minitest (`test/`).
+2. Run the suite (`bin/rails test` or `bundle exec rspec`). If it fails before you start, **stop and tell the user**.
+3. Check `db/schema.rb` (or `structure.sql`) for the tables you touch, their indexes and row counts if the user can tell you.
+
+## 1. Conventions
+
+- Controllers are RESTful: `index show new create edit update destroy`. A new verb usually means a new resource (`resource :publication` with `create`/`destroy`), not a custom action.
+- A controller action: find the record scoped to the current user, authorize, call the model or a plain object in `app/models` or `app/services`, then render or redirect.
+- Scope lookups through the owner: `current_user.projects.find(params[:id])`, never `Project.find(params[:id])` for user-owned data.
+- Callbacks only for the record's own consistency (normalising, defaults). Side effects (emails, API calls, other aggregates) go in explicit code or `after_commit` jobs, not `before_save`.
+- Use `normalizes :email, with: ->(e) { e.strip.downcase }` (Rails 7.1+) instead of hand-written callbacks.
+
+## 2. Active Record queries and N+1
+
+1. Turn N+1s into errors in development and test: `config.active_record.strict_loading_by_default = true` in those environments, or `.strict_loading` on a relation / `strict_loading!(mode: :n_plus_one_only)` on a record. On an existing app the global setting can fail many tests at once, so ask before turning it on and start per model or relation. Add the `bullet` gem only if the project already uses it.
+2. Load associations before iterating:
+   - `includes(:author)`: Rails picks preload or a join.
+   - `preload(:tags)`: separate queries; use for has_many.
+   - `eager_load(:author)`: one LEFT JOIN; required when you filter or order on the association.
+3. Counts: `counter_cache: true` or `left_joins(:comments).group(:id).select("posts.*, COUNT(comments.id) AS comments_count")`. Never `post.comments.count` inside a loop.
+4. Existence: `exists?` (or `any?` / `empty?`, which query without loading), never `present?` or `blank?` on an unloaded relation; those load every row.
+5. Batches: `find_each` / `in_batches` for anything that grows; never `Model.all.each`.
+6. `pluck(:id)` when you only need columns; `select` when you need model objects with fewer columns.
+7. Bulk writes `update_all`, `insert_all`, `upsert_all` skip validations and callbacks. Use them deliberately and say so.
+8. Wrap multi-record changes in `ActiveRecord::Base.transaction do ... end`. Use `with_lock` or `lock!` for read-modify-write on one row.
+9. Raw SQL: `where("price > ?", min)` or named binds. Never interpolate params into `where`, `order` or `pluck`; whitelist sort columns.
+
+## 3. Strong parameters
+
+Rails 8:
+```ruby
+def post_params
+  params.expect(post: [:title, :body, tag_ids: []])
+end
+```
+Rails 7.x:
+```ruby
+def post_params
+  params.require(:post).permit(:title, :body, tag_ids: [])
+end
+```
+- `params.expect` returns 400 on a missing or wrongly shaped key instead of raising a 500 on tampered input.
+- Never permit `:user_id`, `:role`, `:admin` or `:account_id` from a form; set them from `current_user` on the server.
+- Never use `permit!`.
+
+## 4. Background jobs (Active Job)
+
+1. `bin/rails generate job SendReceipt`. Pass records (serialised via GlobalID) or IDs, not big hashes.
+2. Enqueue only after the data is committed: `after_create_commit -> { SendReceiptJob.perform_later(self) }` or enqueue after the transaction block ends. A job enqueued inside an open transaction can run before the row exists.
+3. Make jobs idempotent: check state first, use unique keys on what they create, and use `retry_on` for transient errors with a limit and `discard_on ActiveJob::DeserializationError` for deleted records.
+4. Rails 8 defaults to Solid Queue (`bin/jobs`). Whatever the backend, production needs a supervised worker process; `:async` and `:inline` are for development and tests.
+
+## 5. Migrations that don't take the site down
+
+- One concern per migration. Use reversible `change` or explicit `up`/`down`.
+- Adding a column with a constant (non-volatile) default is a metadata-only change on PostgreSQL 11+ and MySQL 8.0.12+; backfilling existing rows is not. Backfill in a separate migration or job with `in_batches`, then add `null: false`.
+- Indexes on big PostgreSQL tables:
+  ```ruby
+  disable_ddl_transaction!
+  def change
+    add_index :orders, :customer_id, algorithm: :concurrently
+  end
+  ```
+- Removing a column: first add it to `self.ignored_columns` and deploy, then drop it in a later deploy.
+- Renaming a column or table in place breaks running code. Add new, write both, backfill, switch reads, drop old.
+- Add foreign keys with `add_foreign_key ..., validate: false`, then `validate_foreign_key` in a second migration on large tables.
+- If the project uses `strong_migrations`, follow its messages; don't silence them with `safety_assured` without telling the user why.
+
+## 6. Credentials and config
+
+- Secrets live in encrypted credentials: `bin/rails credentials:edit --environment production`. Read with `Rails.application.credentials.dig(:stripe, :secret_key)`.
+- Never commit `config/master.key` or `config/credentials/*.key`; production gets `RAILS_MASTER_KEY` from the environment.
+- Non-secret per-environment settings go in `config/environments/*.rb` or `config_for(:name)` YAML.
+- Keep `config.force_ssl = true` and `config.filter_parameters` covering tokens and passwords in production.
+
+## 7. Hotwire basics
+
+- Turbo Drive is on by default. A failed form must render with a 4xx status, or Turbo won't show the errors:
+  ```ruby
+  if @post.save
+    redirect_to @post
+  else
+    render :new, status: :unprocessable_entity   # 422; Rack 3.1+ also names it :unprocessable_content
+  end
+  ```
+- Turbo Frames (`turbo_frame_tag dom_id(post)`) replace one part of the page; the response must contain a frame with the same id.
+- Turbo Streams (`turbo_stream.replace`, `.append`, `.remove`) for multi-part updates from a form response or `broadcasts_to` over Action Cable.
+- Stimulus controllers for small client behaviour; keep state in the HTML, not in the controller.
+- Authorization still happens in the controller; a frame request is a normal request.
+
+## 8. Testing
+
+- Model tests for validations, scopes and domain methods. Request (or integration) tests for every controller action, including the "other user gets 404/403" case. System tests (Capybara) only for critical flows and Turbo behaviour.
+- Use the project's fixtures or FactoryBot; don't introduce the other.
+- Jobs: `assert_enqueued_with(job: SendReceiptJob)` (or `have_enqueued_job` in RSpec), and `perform_enqueued_jobs` to run them inline.
+- Mail: `assert_emails(1) { ... }`. Time: `travel_to`. HTTP: WebMock, never real network.
+
+## Stop and ask the user
+
+- Before a migration that drops, renames or rewrites a column or table with data, or locks a large table.
+- Before changing the job backend, cache store or session store.
+- Before editing production credentials or rotating `secret_key_base`.
+
+## Never
+
+- Never commit master keys or put secrets in `database.yml` or code.
+- Never `permit!` or permit ownership and role fields.
+- Never enqueue a job inside an open transaction that the job depends on.
+- Never run `db:drop`, `db:reset` or `db:schema:load` against a shared or production database.
+
+## Finish
+
+Run the suite and, if migrations changed, `bin/rails db:migrate` then `bin/rails db:rollback` then migrate again to prove reversibility. Report: files changed, queries fixed, migrations and their deploy order, and anything untested.

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Our Rails dashboard loads every project's owner one query at a time, use includes or preload to fix it",
+    "Write a Rails migration to add an index on orders.customer_id without locking the table in production",
+    "How should I store the Stripe secret key in Rails credentials for production?",
+    "The Rails form doesn't show validation errors after I switched to Turbo, what's wrong?",
+    "Add strong parameters to the Rails PostsController so users can't set their own role"
+  ],
+  "should_not_trigger": [
+    "Set up RuboCop and RBS signatures for my Ruby gem",
+    "Find which RSpec example leaks state and only fails with seed 4821",
+    "Fix the Eloquent N+1 on the Laravel users page",
+    "Design the REST endpoints and error format for our public orders API",
+    "Tune this PostgreSQL query plan that does a sequential scan on events"
+  ]
+}

package/skills/react-native-patterns/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: react-native-patterns
+description: React Native and Expo app guidance for picking a navigation library, keeping global state small, writing or wrapping native modules for the New Architecture, fixing slow lists and needless re-renders, handling iOS versus Android differences, and shipping over-the-air updates with EAS Update without breaking installed binaries. Use when building or restructuring screens in a React Native or Expo project, debugging jank in a FlatList or FlashList, adding a native dependency or config plugin, or planning a store release or OTA update.
+license: MIT
+compatibility: Any Agent Skills host. Needs Node and the project's package manager; device builds need Xcode (iOS) or Android Studio and a JDK (Android). Expo projects use the expo and eas CLIs.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "node, npx"
+  kete-loom/owner: "Kete-org"
+---
+
+# React Native patterns
+
+Build React Native screens that stay at 60 fps, behave on both platforms, and survive the release process. Plain React component design and web-only concerns belong to `react-patterns`; TypeScript typing belongs to `typescript-patterns`.
+
+## 0. Before you change anything
+
+1. Read `package.json` and find the `react-native` and (if present) `expo` versions. Read `app.json` / `app.config.(js|ts)` for Expo projects.
+2. Decide the project type, because it changes every native step:
+   - **Expo with Continuous Native Generation (CNG)**: no committed `ios/` or `android/` folders, native config comes from `app.config` and config plugins. Never hand-edit generated native folders; they are overwritten by `npx expo prebuild`.
+   - **Bare / committed native folders**: native changes are made in `ios/` and `android/` directly and reviewed like any other code.
+3. Find the navigation library (`expo-router`, `@react-navigation/*`) and state libraries already in use. Follow them; don't introduce a second one.
+4. Run the project's type check and tests once and record the result.
+
+## 1. Navigation
+
+- Expo projects with `expo-router`: routes are files under `app/`. Use `_layout.tsx` for stacks and tabs, `[id].tsx` for params, and typed routes if the project enables them.
+- React Navigation projects: declare param lists per navigator in TypeScript and pass only IDs and small serialisable values as params. Fetch the object on the destination screen.
+- Never pass functions, class instances or large objects through params. They break deep links, state persistence and state restoration.
+- Deep links: define them once (Expo `scheme` or React Navigation `linking` config) and test a cold start from a link on both platforms.
+
+## 2. State
+
+Decision rule, smallest first:
+
+1. Local `useState` / `useReducer` for state used by one screen.
+2. Server data: a query cache (TanStack Query, RTK Query, SWR or whatever the project uses), not a global store.
+3. Truly global client state (session, theme, feature flags): the project's existing store (Zustand, Redux Toolkit, Jotai, Context).
+4. Persisted values: `expo-secure-store` or the Keychain/Keystore for secrets and tokens; AsyncStorage or MMKV only for non-sensitive data.
+
+Never store tokens or personal data in AsyncStorage: it is unencrypted.
+
+## 3. Lists and re-renders
+
+Lists are the first place to look for jank.
+
+- Use `FlatList`, `SectionList` or `FlashList` for anything that can grow. Never `.map()` a long array inside a `ScrollView`.
+- Give every list a stable `keyExtractor` from the data's ID, never the index.
+- Memoise `renderItem` with `useCallback` and the row component with `React.memo`; pass primitive props so memo can skip.
+- For fixed-height rows provide `getItemLayout` (FlatList). Tune `initialNumToRender`, `windowSize` and `maxToRenderPerBatch` only after measuring.
+- Don't create new objects, arrays or inline style objects per render in hot rows; hoist them or use `StyleSheet.create`.
+- Selectors: subscribe to the smallest slice of a store (`useStore(s => s.count)`), not the whole store.
+- Animations: run them on the UI thread with Reanimated worklets or `useNativeDriver: true`, never by setting state every frame.
+
+Measure before and after: React DevTools Profiler for renders, the platform profiler (Xcode Instruments, Android Studio profiler) for frames, and always test in a **release** build. Dev builds are much slower and mislead.
+
+## 4. Native modules
+
+The New Architecture (TurboModules, Fabric) is the default since React Native 0.76, and from 0.82 it can no longer be turned off.
+
+1. Before writing a module, search for a maintained library or Expo SDK module that already does it, and check it supports the New Architecture.
+2. Expo projects: write new native code as an Expo Module (`npx create-expo-module`) and any native config change as a config plugin, so `prebuild` reproduces it.
+3. Bare projects: write a TurboModule with a typed JS spec and Codegen.
+4. Keep the JS/native boundary coarse: one call that does the work, not many chatty calls per frame.
+5. Every native dependency change needs a new binary. **Stop and tell the user** that an OTA update cannot ship it.
+
+## 5. Platform differences
+
+Check each of these on both platforms before calling a screen done:
+
+- Safe areas and notches: `react-native-safe-area-context`, not hard-coded padding.
+- Keyboard: `KeyboardAvoidingView` behaviour differs (`padding` on iOS is usual; Android often relies on `windowSoftInputMode`). Test forms with the keyboard open.
+- Android hardware back button and predictive back; iOS swipe-back gesture.
+- Permissions: iOS needs usage-description strings (`NSCameraUsageDescription` and friends, via `ios.infoPlist` in Expo); Android needs manifest permissions plus a runtime request.
+- Shadows (`shadow*` on iOS vs `elevation` on Android), fonts and text line height.
+- Use `Platform.select` or `.ios.tsx` / `.android.tsx` files for real divergence, not scattered `Platform.OS` checks.
+
+## 6. OTA updates and releases
+
+An OTA update (EAS Update or similar) only replaces the JavaScript bundle and assets.
+
+- Set `runtimeVersion` deliberately. With the `appVersion` policy you must bump the app `version` whenever native code changes; the `fingerprint` policy derives it from native inputs. A wrong runtime version ships JS that calls native code the binary doesn't have, which crashes on launch.
+- Ship native changes (new native dependency, SDK upgrade, permission, config plugin) only through a store build.
+- Publish to a staging channel, test on a real installed build, then promote to production.
+- Keep a rollback path: know the command to republish or roll back the previous update before you publish.
+- Release builds: bump the store version and build number (`ios.buildNumber`, `android.versionCode`), keep signing credentials out of git, and test the release build, not the dev client.
+
+**Stop and ask the user** before publishing an update to a production channel or submitting to a store.
+
+## Never
+
+- Never hand-edit `ios/` or `android/` in a CNG project.
+- Never ship native changes over the air.
+- Never leave `console.log` in hot render paths of a release build, or secrets in the JS bundle (anything in the bundle is readable).
+- Never judge performance from a debug build.
+
+## Report back
+
+End with: what changed, which platforms you ran it on (simulator, device, release or debug), commands run and results, and whether the change needs a new binary or can go out as an OTA update.

package/skills/react-native-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "My FlatList of 2000 chat messages stutters when scrolling on Android, how do I fix it?",
+    "Set up expo-router tabs with a details screen that takes an id param",
+    "We need to call a native Bluetooth SDK from our Expo app, how should I wrap it?",
+    "Can I push this fix to users with EAS Update or do I need a new App Store build?",
+    "The keyboard covers the login form on iOS but not Android in our React Native app"
+  ],
+  "should_not_trigger": [
+    "Build a Next.js page that server-renders the product catalogue",
+    "My Flutter ListView rebuilds every item when one changes",
+    "Write Playwright end-to-end tests for the web checkout",
+    "Add a SwiftUI settings screen with a NavigationStack",
+    "Reduce re-renders in this React web dashboard using memo and useCallback"
+  ]
+}