opencode-skills-collection 3.0.49 → 3.0.51

package/bundled-skills/super-code/elixir/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: elixir
+description: "Language-specific super-code guidelines for elixir."
+risk: safe
+source: community
+date_added: "2026-06-16"
+---
+# Elixir / Erlang: Idiomatic Efficiency Reference
+
+## Table of Contents
+1. [Pattern Matching & Guards](#patterns)
+2. [Pipe Operator & Transforms](#pipes)
+3. [Processes & OTP](#otp)
+4. [Error Handling](#errors)
+5. [Collections & Enum](#collections)
+6. [Structs & Protocols](#structs)
+7. [Anti-patterns specific to Elixir/Erlang](#antipatterns)
+
+---
+
+## 1. Pattern Matching & Guards {#patterns}
+
+```elixir
+# ❌ Extracting with Map.get then checking
+value = Map.get(map, :key)
+if value != nil do
+  process(value)
+end
+
+# ✅ — pattern match directly
+case map do
+  %{key: value} -> process(value)
+  _ -> :noop
+end
+# or with if:
+if value = map[:key], do: process(value)
+```
+
+```elixir
+# ❌ Nested case for multiple conditions
+case fetch_user(id) do
+  {:ok, user} ->
+    case validate(user) do
+      {:ok, valid_user} -> save(valid_user)
+      {:error, reason} -> {:error, reason}
+    end
+  {:error, reason} -> {:error, reason}
+end
+
+# ✅ — with clause
+with {:ok, user} <- fetch_user(id),
+     {:ok, valid_user} <- validate(user) do
+  save(valid_user)
+end
+```
+
+```elixir
+# ❌ if/else for known shapes
+def area(shape) do
+  if shape.type == :circle do
+    :math.pi() * shape.radius * shape.radius
+  else
+    shape.width * shape.height
+  end
+end
+
+# ✅ — multi-clause function with pattern match
+def area(%{type: :circle, radius: r}), do: :math.pi() * r * r
+def area(%{type: :rect, width: w, height: h}), do: w * h
+```
+
+```elixir
+# ❌ Checking type at runtime
+def process(x) do
+  if is_integer(x) and x > 0 do
+    x * 2
+  end
+end
+
+# ✅ — guard clause
+def process(x) when is_integer(x) and x > 0, do: x * 2
+def process(_), do: {:error, :invalid_input}
+```
+
+---
+
+## 2. Pipe Operator & Transforms {#pipes}
+
+```elixir
+# ❌ Nested function calls
+String.trim(String.downcase(String.replace(input, ~r/\s+/, " ")))
+
+# ✅
+input
+|> String.replace(~r/\s+/, " ")
+|> String.downcase()
+|> String.trim()
+```
+
+```elixir
+# ❌ Pipe into anonymous function awkwardly
+data
+|> (fn x -> x * 2 end).()
+
+# ✅ — use then/1 or named function
+data
+|> then(&(&1 * 2))
+# or better: extract a named function
+data |> double()
+```
+
+```elixir
+# ❌ Single-step pipe (no gain in readability)
+result = list |> Enum.count()
+
+# ✅ — direct call for single operation
+result = Enum.count(list)
+```
+
+**Pipe when 2+ transforms. Direct call for single operation. First arg flows through pipe.**
+
+---
+
+## 3. Processes & OTP {#otp}
+
+```elixir
+# ❌ Raw spawn for stateful process
+pid = spawn(fn -> loop(%{count: 0}) end)
+send(pid, {:increment})
+
+# ✅ — GenServer for stateful processes
+defmodule Counter do
+  use GenServer
+
+  def start_link(init \\ 0), do: GenServer.start_link(__MODULE__, init)
+  def increment(pid), do: GenServer.call(pid, :increment)
+
+  @impl true
+  def init(count), do: {:ok, count}
+
+  @impl true
+  def handle_call(:increment, _from, count), do: {:reply, count + 1, count + 1}
+end
+```
+
+```elixir
+# ❌ Spawning without linking (orphan process on crash)
+spawn(fn -> do_work() end)
+
+# ✅ — Task for fire-and-forget with supervision
+Task.start(fn -> do_work() end)
+# or for awaitable result:
+task = Task.async(fn -> do_work() end)
+result = Task.await(task)
+```
+
+```elixir
+# ❌ Manual process registry
+Process.register(self(), :my_worker)
+
+# ✅ — use Registry or named GenServer
+{:ok, _} = Registry.start_link(keys: :unique, name: MyRegistry)
+GenServer.start_link(Worker, arg, name: {:via, Registry, {MyRegistry, :my_worker}})
+```
+
+```elixir
+# ❌ try/catch in GenServer (breaks supervision)
+def handle_call(:work, _from, state) do
+  try do
+    result = risky_operation()
+    {:reply, result, state}
+  catch
+    _ -> {:reply, :error, state}
+  end
+end
+
+# ✅ — let it crash; supervisor restarts
+def handle_call(:work, _from, state) do
+  result = risky_operation()
+  {:reply, result, state}
+end
+```
+
+**"Let it crash" — supervisors handle recovery. Don't defensively catch inside GenServers.**
+
+---
+
+## 4. Error Handling {#errors}
+
+```elixir
+# ❌ Raising for expected failures
+def find_user(id) do
+  case Repo.get(User, id) do
+    nil -> raise "User not found"
+    user -> user
+  end
+end
+
+# ✅ — tagged tuples for expected outcomes
+def find_user(id) do
+  case Repo.get(User, id) do
+    nil -> {:error, :not_found}
+    user -> {:ok, user}
+  end
+end
+```
+
+```elixir
+# ❌ Ignoring error tuple
+{:ok, result} = might_fail()  # crashes on {:error, _}
+
+# ✅ — handle both cases
+case might_fail() do
+  {:ok, result} -> process(result)
+  {:error, reason} -> Logger.error("Failed: #{inspect(reason)}")
+end
+```
+
+```elixir
+# ❌ String errors
+{:error, "something went wrong"}
+
+# ✅ — atom or struct errors (matchable, cheap)
+{:error, :timeout}
+{:error, %ValidationError{field: :email, reason: :invalid_format}}
+```
+
+```elixir
+# ❌ Deep nesting of ok/error checks
+case step1() do
+  {:ok, a} ->
+    case step2(a) do
+      {:ok, b} ->
+        case step3(b) do
+          {:ok, c} -> {:ok, c}
+          error -> error
+        end
+      error -> error
+    end
+  error -> error
+end
+
+# ✅
+with {:ok, a} <- step1(),
+     {:ok, b} <- step2(a),
+     {:ok, c} <- step3(b) do
+  {:ok, c}
+else
+  {:error, reason} -> {:error, reason}
+end
+```
+
+---
+
+## 5. Collections & Enum {#collections}
+
+```elixir
+# ❌ Multiple passes when one suffices
+items
+|> Enum.filter(&(&1.active))
+|> Enum.map(&(&1.name))
+
+# ✅ — for comprehension when filter + transform
+for %{active: true, name: name} <- items, do: name
+```
+
+```elixir
+# ❌ Enum.count for empty check (traverses whole list)
+if Enum.count(list) == 0, do: :empty
+
+# ✅
+if Enum.empty?(list), do: :empty
+# or pattern match:
+case list do
+  [] -> :empty
+  _ -> :has_items
+end
+```
+
+```elixir
+# ❌ Building map with Enum.reduce when Map.new works
+Enum.reduce(users, %{}, fn user, acc -> Map.put(acc, user.id, user) end)
+
+# ✅
+Map.new(users, &{&1.id, &1})
+```
+
+```elixir
+# ❌ Enum on large dataset (eager — builds intermediate lists)
+huge_list
+|> Enum.map(&transform/1)
+|> Enum.filter(&valid?/1)
+|> Enum.take(10)
+
+# ✅ — Stream for lazy evaluation
+huge_list
+|> Stream.map(&transform/1)
+|> Stream.filter(&valid?/1)
+|> Enum.take(10)
+```
+
+**Use `Stream` when chaining transforms on large/infinite collections. `Enum` for small or final step.**
+
+---
+
+## 6. Structs & Protocols {#structs}
+
+```elixir
+# ❌ Plain map for domain entities
+user = %{name: "Alice", email: "a@b.com", age: 30}
+# typo in key goes unnoticed: user.emaail
+
+# ✅ — struct enforces keys
+defmodule User do
+  @enforce_keys [:name, :email]
+  defstruct [:name, :email, age: 0]
+end
+user = %User{name: "Alice", email: "a@b.com"}
+```
+
+```elixir
+# ❌ Protocol with only one implementation (over-abstraction)
+defprotocol Renderable do
+  def render(data)
+end
+defimpl Renderable, for: HtmlPage do ... end
+
+# ✅ — just a function until you need polymorphism
+def render(%HtmlPage{} = page), do: ...
+```
+
+```elixir
+# ❌ Updating nested struct manually
+updated = %{user | address: %{user.address | city: "NYC"}}
+
+# ✅
+updated = put_in(user.address.city, "NYC")
+# or Kernel.update_in/3 for transforms
+```
+
+---
+
+## 7. Anti-patterns specific to Elixir/Erlang {#antipatterns}
+
+| Anti-pattern | Preferred |
+|---|---|
+| `spawn` without link/monitor | `Task.start_link` or `GenServer` |
+| `try/catch` inside GenServer | let it crash; supervisor restarts |
+| String error reasons | atom or struct errors |
+| `Enum.count(x) == 0` | `Enum.empty?(x)` or `match?([], x)` |
+| Mutable-style accumulator | `Enum.reduce` / recursion |
+| `if/else` chain on data shape | multi-clause function + pattern match |
+| Nested `case` for ok/error | `with` expression |
+| `IO.inspect` left in prod | `Logger` with levels |
+| Single-step pipe | direct function call |
+| `Enum` on huge/infinite data | `Stream` |
+| Raw PID passing | named processes / Registry |
+| Boolean returns for success/fail | `{:ok, val}` / `{:error, reason}` tuples |
+| `length(list) > 0` (O(n)) | pattern match `[_ | _]` |
+| Shared mutable state via ETS without wrapper | GenServer or Agent as access layer |
+
+
+
+## Limitations
+- These are language-specific guidelines and do not cover overall architectural decisions.
+- Over-compression might reduce readability; apply judgement.

package/bundled-skills/super-code/go/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: go
+description: "Language-specific super-code guidelines for go."
+risk: safe
+source: community
+date_added: "2026-06-16"
+---
+# Go: Idiomatic Efficiency Reference
+
+## Table of Contents
+1. [Error Handling](#errors)
+2. [Slices & Maps](#slices)
+3. [Goroutines & Channels](#concurrency)
+4. [Structs & Interfaces](#structs)
+5. [Functions & Closures](#functions)
+6. [Anti-patterns specific to Go](#antipatterns)
+
+---
+
+## 1. Error Handling {#errors}
+
+```go
+// ❌ Ignoring errors
+result, _ := os.Open(path)
+
+// ✅ — always handle; only use _ when error is provably irrelevant
+result, err := os.Open(path)
+if err != nil {
+    return fmt.Errorf("open %s: %w", path, err)
+}
+```
+
+```go
+// ❌ Redundant error variable
+err := doA()
+if err != nil { return err }
+err = doB()
+if err != nil { return err }
+
+// ✅ — each :=/:  is fine; this is idiomatic Go. Don't try to "fix" it.
+// What you CAN simplify: collapsing to one-liners where the if body is a single return
+if err := doA(); err != nil { return err }
+if err := doB(); err != nil { return err }
+```
+
+```go
+// ❌ Custom error type with no added value
+type MyError struct{ msg string }
+func (e MyError) Error() string { return e.msg }
+
+// ✅ — use errors.New or fmt.Errorf unless callers need to inspect type
+var ErrNotFound = errors.New("not found")
+return fmt.Errorf("lookup %q: %w", key, ErrNotFound)
+```
+
+**Wrap errors with `%w` (not `%v`) so callers can use `errors.Is` / `errors.As`.**
+
+---
+
+## 2. Slices & Maps {#slices}
+
+```go
+// ❌ Growing a slice without pre-allocation when size is known
+var result []string
+for _, item := range items {
+    result = append(result, item.Name)
+}
+
+// ✅
+result := make([]string, 0, len(items))
+for _, item := range items {
+    result = append(result, item.Name)
+}
+```
+
+```go
+// ❌ Manual existence check before map write
+if _, ok := m[key]; !ok {
+    m[key] = []string{}
+}
+m[key] = append(m[key], value)
+
+// ✅ — append to nil slice is valid Go
+m[key] = append(m[key], value)
+```
+
+```go
+// ❌ Copying a map by assignment (copies reference)
+copy := original
+
+// ✅
+copy := make(map[K]V, len(original))
+for k, v := range original { copy[k] = v }
+```
+
+---
+
+## 3. Goroutines & Channels {#concurrency}
+
+```go
+// ❌ Fire-and-forget goroutine with no lifecycle
+go doWork()
+
+// ✅ — use errgroup or WaitGroup to track completion
+var wg sync.WaitGroup
+wg.Add(1)
+go func() {
+    defer wg.Done()
+    doWork()
+}()
+wg.Wait()
+```
+
+```go
+// ❌ Unbuffered channel causing unnecessary goroutine block
+ch := make(chan Result)
+go func() { ch <- compute() }()
+result := <-ch
+
+// ✅ — for single-result, buffered channel avoids goroutine leak if receiver exits early
+ch := make(chan Result, 1)
+go func() { ch <- compute() }()
+result := <-ch
+```
+
+```go
+// ❌ select with a busy-wait default
+for {
+    select {
+    case v := <-ch:
+        process(v)
+    default:
+        // spin
+    }
+}
+
+// ✅ — blocking select unless you genuinely need non-blocking
+for v := range ch {
+    process(v)
+}
+```
+
+**Use `golang.org/x/sync/errgroup` for fan-out with error collection.**
+
+---
+
+## 4. Structs & Interfaces {#structs}
+
+```go
+// ❌ Large interface
+type Storage interface {
+    Get(key string) ([]byte, error)
+    Set(key string, val []byte) error
+    Delete(key string) error
+    List(prefix string) ([]string, error)
+    // ... 10 more methods
+}
+
+// ✅ — small, composable interfaces
+type Getter interface { Get(key string) ([]byte, error) }
+type Setter interface { Set(key string, val []byte) error }
+type Storage interface { Getter; Setter }
+```
+
+```go
+// ❌ Returning concrete struct from constructor (ties callers to implementation)
+func NewStore() *RedisStore { ... }
+
+// ✅ — return interface when you have or anticipate multiple implementations
+func NewStore() Storage { return &RedisStore{...} }
+```
+
+```go
+// ❌ Pointer receiver for tiny value types
+func (p *Point) X() float64 { return p.x }
+
+// ✅ — value receiver for small immutable types
+func (p Point) X() float64 { return p.x }
+```
+
+**Rule: pointer receiver when method mutates state OR struct is large (>3 fields of non-trivial size). Value receiver otherwise.**
+
+---
+
+## 5. Functions & Closures {#functions}
+
+```go
+// ❌ Named return values used just to avoid a variable declaration
+func divide(a, b float64) (result float64, err error) {
+    result = a / b
+    return
+}
+
+// ✅ — named returns are worth it only for deferred mutation or documentation
+func divide(a, b float64) (float64, error) {
+    if b == 0 { return 0, errors.New("division by zero") }
+    return a / b, nil
+}
+```
+
+```go
+// ❌ Closure capturing loop variable (classic Go bug, fixed in Go 1.22+)
+// Pre-1.22: each goroutine captures the same i
+for i := 0; i < n; i++ {
+    go func() { use(i) }()
+}
+
+// ✅ (Go <1.22 — pass as parameter)
+for i := 0; i < n; i++ {
+    go func(i int) { use(i) }(i)
+}
+// Go 1.22+: loop variable scoped per iteration, so the original is safe
+```
+
+---
+
+## 6. Anti-patterns specific to Go {#antipatterns}
+
+| Anti-pattern | Preferred |
+|---|---|
+| `if err != nil { return err }` repeated 5+ times | acceptable — it's idiomatic Go |
+| `panic` for expected errors | `return err` |
+| `init()` with side effects | explicit initialization in `main` or constructors |
+| `interface{}` / `any` without generics | use generics (Go 1.18+) or typed interfaces |
+| Mutex field not adjacent to the data it protects | put `mu` directly above the field it guards |
+| Channel of channels | usually a sign of over-engineering; redesign |
+| `time.Sleep` in tests | use `testing` hooks or channels for synchronization |
+| Exported types with unexported fields (when fields are the whole point) | `record`-style structs with all-exported fields |
+| `log.Fatal` outside `main` | return errors up the stack |
+
+
+## Limitations
+- These are language-specific guidelines and do not cover overall architectural decisions.
+- Over-compression might reduce readability; apply judgement.