wotann 0.5.0

package/skills/karpathy-principles.md

@@ -0,0 +1,62 @@
+---
+name: karpathy-principles
+description: Apply Andrej Karpathy's four engineering-discipline principles — Think-Before-Coding, Simplicity-First, Surgical-Changes, Goal-Driven-Execution. Injects a terse preamble before any non-trivial coding task. Use when the user flags high-stakes code, invokes /karpathy, or when the request involves API design, refactoring, or architectural decisions.
+---
+
+# Karpathy Principles — Engineering Discipline Prelude
+
+Andrej Karpathy's lean approach to AI/software engineering distilled into four operating rules. Each rule is short, concrete, and applies to every turn of a non-trivial coding task. Use this as a system-prompt preamble rather than a standalone workflow — it composes cleanly with TDD, plan-first, verification-based-completion, and existing WOTANN quality bars.
+
+## 1. Think-Before-Coding
+
+Before writing a single line:
+
+- State the problem in one sentence. If you cannot, the problem is not yet understood.
+- List 2–3 failure modes you predict. If you cannot predict them, you will miss them.
+- Identify the smallest change that could verify your hypothesis — run that first.
+
+When the prompt is ambiguous: ask one specific question, not a paragraph of caveats.
+
+## 2. Simplicity-First
+
+Write code a reader can hold in their head.
+
+- Prefer obvious over clever. A loop is clearer than a fold for most readers.
+- Name variables after the thing they represent, not their type.
+- One function, one purpose. If the name has "and" in it, split it.
+- Zero indirection unless an existing pattern requires it.
+- Default to arrays and dicts; reach for classes only when identity matters.
+
+When you find yourself reaching for a library: first try 15 lines of hand-rolled code. Often good enough, often better.
+
+## 3. Surgical-Changes
+
+Edit the smallest possible scope.
+
+- One concern per commit. Drive-by refactors have their own commit.
+- Never "tidy up" in the same change as a bug fix.
+- Preserve existing style until explicitly asked to change it.
+- If you must touch a function for an unrelated reason, touch the narrowest part.
+- Reject the temptation to "improve while you're there." That is how churn compounds.
+
+## 4. Goal-Driven-Execution
+
+Every step must move the state toward a verifiable goal.
+
+- Rewrite imperative tasks as declarative success criteria the agent can self-verify in a loop. "Fix the bug" → "the test at tests/x.test.ts:42 passes".
+- Before running a long operation, state the expected outcome. Compare after. If they diverge, debug the divergence, not the symptom.
+- When uncertain, prefer shorter feedback loops (smaller change + run tests) over longer ones (big refactor + run tests at the end).
+- Know when to stop: a "done enough" state with tests green beats a "perfect" state that is still compiling.
+
+## How to apply
+
+1. Prepend this preamble to the system prompt when the user invokes `/karpathy` or sets `WOTANN_KARPATHY_MODE=1`.
+2. Treat the four rules as priorities in order. If Think-Before-Coding and Surgical-Changes conflict, think more first.
+3. Quote the specific principle when you explain a decision that it drove: "Surgical-Changes — deferring the unrelated refactor to a separate PR."
+4. These rules do NOT replace project-specific conventions (immutability, TDD, reference-completeness before signature changes). They layer on top.
+
+## Why this exists
+
+Karpathy's public engineering posture (llm.c, nanoGPT, micrograd) is the cleanest demonstration of these rules in AI tooling. Each project is small, readable, and teaches a concept in under 1000 lines. That quality bar is what this skill reaches for.
+
+WOTANN's skill system makes the preamble composable: `/karpathy` stacks with `/tdd`, `/verify`, `/systematic-debugging` without conflict. The four rules are behavioral priors, not workflow gates — they shape HOW you move through a task, not WHICH tasks to take.

package/skills/kotlin-specialist.md

@@ -0,0 +1,64 @@
+---
+name: kotlin-specialist
+description: Coroutines, Flow, multiplatform, null safety - idiomatic Kotlin patterns
+context: fork
+paths: ["**/*.kt", "**/build.gradle.kts"]
+requires:
+  bins: ["kotlin"]
+---
+
+# Kotlin Specialist
+
+## When to Use
+
+- Building Android apps or Kotlin Multiplatform projects with shared business logic.
+- Writing server-side Kotlin with Ktor, Spring Boot, or Http4k.
+- Refactoring Java code to idiomatic Kotlin (leveraging nullability, data classes, extensions).
+- Implementing concurrent code with coroutines and Flow.
+- Working with `build.gradle.kts` or Gradle version catalogs.
+
+## Rules
+
+- Use null safety rigorously. Avoid `!!` (prefer `?.`, `?:`, `let`, `require`, `checkNotNull`).
+- Use `data class` for DTOs (auto-generates equals/hashCode/toString/copy).
+- Use `sealed class/interface` for closed type hierarchies (exhaustive `when`).
+- Use coroutines for async work (never raw threads, never `Thread.sleep` in suspend).
+- Never call `runBlocking` in production code paths (only in main/tests).
+- Prefer `val` over `var`; prefer immutable collections (`listOf`, `mapOf`).
+- Use extension functions to add behavior without inheritance.
+
+## Patterns
+
+- **Structured concurrency**: scopes own children; cancellation propagates.
+- **Flow for streams**: `flow { }` builders, `stateIn`/`shareIn` for hot flows.
+- **Result type**: `Result<T>` or `sealed class Either` for typed errors.
+- **Scope functions**: `let` (transform), `apply` (configure), `also` (side-effect), `run` (scoped compute).
+- **Inline + reified**: zero-cost generic type checks (`inline fun <reified T>`).
+
+## Example
+
+```kotlin
+sealed interface LoadState<out T> {
+    data object Loading : LoadState<Nothing>
+    data class Success<T>(val data: T) : LoadState<T>
+    data class Error(val cause: Throwable) : LoadState<Nothing>
+}
+
+fun <T> Flow<T>.asLoadState(): Flow<LoadState<T>> = this
+    .map<T, LoadState<T>> { LoadState.Success(it) }
+    .onStart { emit(LoadState.Loading) }
+    .catch { emit(LoadState.Error(it)) }
+```
+
+## Checklist
+
+- [ ] No `!!` operators remain (search `!!` in changed files).
+- [ ] All suspend functions live inside a structured `CoroutineScope`.
+- [ ] Sealed hierarchies have exhaustive `when` branches (no `else`).
+- [ ] Public APIs have explicit nullability and KDoc where non-obvious.
+
+## Common Pitfalls
+
+- Using `GlobalScope.launch` leaks coroutines; use a scoped `viewModelScope` or inject a scope.
+- Mutating `MutableStateFlow` from multiple coroutines without synchronization; use `update { }`.
+- Forgetting `@JvmStatic` on companion members when Java callers need direct access.

package/skills/kubernetes-specialist.md

@@ -0,0 +1,68 @@
+---
+name: kubernetes-specialist
+description: Kubernetes manifests, Helm, operators, multi-cluster patterns
+context: fork
+paths: ["**/k8s/**", "**/kubernetes/**", "**/helm/**", "**/Chart.yaml", "**/*.yaml"]
+---
+
+# Kubernetes Specialist
+
+## When to Use
+- Authoring or reviewing Deployments, StatefulSets, Jobs, CronJobs.
+- Packaging workloads with Helm or Kustomize.
+- Building or reviewing a Kubernetes operator (controller-runtime, kubebuilder).
+- Diagnosing pod/service/ingress misbehavior.
+- Planning multi-tenant or multi-cluster topologies.
+
+## Rules
+- Set resource requests AND limits on every container.
+- Use readiness + liveness + startup probes — never trust "it's running".
+- Never run as root; set `securityContext.runAsNonRoot: true`.
+- Pin image tags to immutable digests in production.
+- Separate config (ConfigMap/Secret) from image.
+- Namespaces for boundaries, NetworkPolicies for enforcement.
+
+## Patterns
+- **Blue-green** via two Deployments + Service selector swap.
+- **Canary** via Argo Rollouts or Flagger with analysis templates.
+- **GitOps** (Argo CD / Flux) — cluster state follows a git repo.
+- **Operator pattern** for stateful apps (databases, queues, ML).
+- **HPA + VPA** for horizontal and vertical autoscaling.
+- **PodDisruptionBudget** to protect quorum during evictions.
+
+## Example
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata: { name: api, labels: { app: api } }
+spec:
+  replicas: 3
+  strategy: { type: RollingUpdate, rollingUpdate: { maxUnavailable: 0, maxSurge: 1 } }
+  selector: { matchLabels: { app: api } }
+  template:
+    metadata: { labels: { app: api } }
+    spec:
+      securityContext: { runAsNonRoot: true, fsGroup: 2000 }
+      containers:
+        - name: api
+          image: ghcr.io/acme/api@sha256:abcd1234
+          resources:
+            requests: { cpu: 100m, memory: 128Mi }
+            limits:   { cpu: 500m, memory: 512Mi }
+          readinessProbe: { httpGet: { path: /ready, port: 8080 }, periodSeconds: 5 }
+          livenessProbe:  { httpGet: { path: /live,  port: 8080 }, periodSeconds: 10 }
+```
+
+## Checklist
+- [ ] Every container has requests + limits.
+- [ ] Every Deployment has readiness + liveness probes.
+- [ ] NetworkPolicies deny-by-default, allow-by-exception.
+- [ ] Secrets come from Vault/ASM/GSM, not raw Secret objects.
+- [ ] PodDisruptionBudget protects quorum services.
+
+## Common Pitfalls
+- **`resources: {}`** — one pod hogs the whole node.
+- **`:latest` tag** — rollbacks become impossible.
+- **Ignoring PodSecurity standards** — compliance audits fail.
+- **One-pod StatefulSets** with no quorum.
+- **HPA on CPU** for I/O-bound or queue-bound workloads.

package/skills/lsp-operations.md

@@ -0,0 +1,40 @@
+---
+name: lsp-operations
+description: Semantic code operations via the Language Server Protocol — rename symbols, find references, go-to-definition, extract refactorings. Use when code edits benefit from type-aware, cross-file awareness instead of text matching.
+---
+
+# LSP-Aware Semantic Operations
+
+Use when: refactoring code, renaming symbols, finding references, understanding type hierarchies,
+or performing any operation that benefits from language server protocol awareness.
+
+## Capabilities
+- Go-to-definition across import boundaries
+- Find all references (callers, implementers)
+- Rename symbol with automatic import updates
+- Extract function/variable/type refactoring
+- Inline function/variable refactoring
+- Organize imports
+- Auto-fix diagnostics
+- Signature help and parameter hints
+
+## Protocol
+1. Start the LSP server for the target language (TypeScript: tsserver, Python: pylance, Rust: rust-analyzer)
+2. Open the target file to trigger indexing
+3. Use textDocument/references to find ALL callers before modifying any signature
+4. Use textDocument/rename for multi-file renames
+5. Use textDocument/codeAction for automated refactorings
+6. After changes, run textDocument/diagnostic to verify no new errors
+
+## Supported Languages
+- TypeScript/JavaScript (tsserver)
+- Python (pylance/pyright)
+- Rust (rust-analyzer)
+- Go (gopls)
+- Java (jdtls)
+- C# (OmniSharp)
+
+## Anti-Patterns
+- Never rename via find-and-replace — use LSP rename
+- Never assume all references were found without running a search
+- Never modify a public API without checking all callers first

package/skills/marketing-conversion-ops.md

@@ -0,0 +1,36 @@
+---
+name: marketing-conversion-ops
+description: CRO audit framework for landing pages, survey segmentation, and lead-magnet ideation
+context: fork
+paths: []
+category: marketing
+requires:
+  anyBins: ["python3", "python"]
+---
+
+# Marketing Conversion Ops
+
+## Audit Dimensions
+- Headline clarity
+- CTA visibility and contrast
+- Social proof quality
+- Urgency or momentum cues
+- Trust signals
+- Form friction
+- Mobile usability
+- Speed indicators
+
+## Review Workflow
+1. Score the page across all dimensions.
+2. Rank fixes by impact, not by how easy they are to ship.
+3. Rewrite the weakest sections with specific before/after suggestions.
+4. Where survey data exists, cluster pain points before inventing a lead magnet.
+
+## Survey-to-Offer Pattern
+- Group respondents by problem, not demographics alone.
+- Prioritize segments by pain intensity and commercial potential.
+- Turn the top segments into lead magnets with format, hook, CTA, and distribution guidance.
+
+## Guardrails
+- Do not call a page “high converting” without showing where the friction still lives.
+- Do not recommend more fields, more copy, or more CTAs unless the evidence is strong.

package/skills/marketing-expert-panel.md

@@ -0,0 +1,33 @@
+---
+name: marketing-expert-panel
+description: Multi-expert scoring loop for content, landing pages, and strategy until quality is genuinely strong
+context: fork
+paths: []
+category: marketing
+requires:
+  anyBins: ["python3", "python"]
+---
+
+# Marketing Expert Panel
+
+## When To Use
+- Quality-gating copy, landing pages, nurture sequences, pricing pages, or strategy docs.
+- Comparing multiple variants and choosing a winner with explicit reasons.
+- Tightening content that feels weak, generic, or AI-written.
+
+## Panel Construction
+- Start with 5-7 reviewers matched to the artifact: copy, conversion, brand voice, offer clarity, and audience fit.
+- Always include a humanizer lens and a brand-voice lens.
+- Add 1-3 domain experts when the niche matters.
+- Cap the panel at 10 reviewers; merge overlapping perspectives instead of padding.
+
+## Review Loop
+1. Score each variant from 0-100 with one-line rationale.
+2. Weight humanizer and conversion more heavily than stylistic polish.
+3. Identify the top 3 weaknesses, revise specifically, and rescore.
+4. Stop at 90+ quality or after 3 rounds, then report the real ceiling.
+
+## Output Rules
+- Show the winner first, then the score table and revision history.
+- Preserve the reasoning trail; the feedback history is part of the deliverable.
+- If the artifact came from another skill, produce a brief explaining what the source workflow should change next time.

package/skills/marketing-growth-engine.md

@@ -0,0 +1,33 @@
+---
+name: marketing-growth-engine
+description: Growth experimentation workflow with playbook reuse, hypothesis tracking, and weekly scorecards
+context: fork
+paths: []
+category: marketing
+requires:
+  anyBins: ["python3", "python"]
+---
+
+# Marketing Growth Engine
+
+## Core Pattern
+- Treat marketing as an experiment system, not a stream of one-off assets.
+- Check the current playbook before proposing a new variant.
+- Every test needs a hypothesis, a primary metric, a time window, and a minimum sample rule.
+
+## Operating Loop
+1. Define the variable being tested, not just the asset being written.
+2. Generate 2-10 variants only when the channel can support the sample size.
+3. Log outcomes consistently across variants.
+4. Promote only statistically credible winners into the playbook.
+5. Turn the winner into the next baseline before creating new work.
+
+## Scorecard Expectations
+- Weekly view should show channel health, pacing, current winners, and next experiments.
+- Flag channels that are under target before suggesting new creative.
+- Separate trends from confirmed winners; do not confuse early uplift with proof.
+
+## Guardrails
+- Do not run batch testing when distribution volume is too low.
+- Do not recommend new variants until the prior experiment has enough data or is explicitly abandoned.
+- Every suggestion must end with the next metric to inspect.

package/skills/marketing-outbound-engine.md

@@ -0,0 +1,27 @@
+---
+name: marketing-outbound-engine
+description: Cold outbound system for ICP definition, infrastructure readiness, recursive scoring, and sequence rollout
+context: fork
+paths: []
+category: marketing
+requires:
+  anyBins: ["python3", "python"]
+---
+
+# Marketing Outbound Engine
+
+## Discovery Order
+1. Determine whether this is a fresh outbound build or an existing campaign audit.
+2. Confirm infrastructure readiness before touching copy: sending accounts, warmup, domains, and capacity.
+3. Lock the ICP and anti-ICP.
+4. Collect real offer proof: URLs, metrics, case studies, and offer framing.
+
+## Copy Development
+- Use a recursive expert-panel loop until the sequence is genuinely strong.
+- Optimize for believable personalization, first-line pattern interrupt, concise body, and soft CTA.
+- Penalize spam triggers, link overload, and generic “spray and pray” claims.
+
+## Delivery Standard
+- Produce the final sequence plus an implementation doc, a stop list, a start list, and capacity math.
+- Separate “ready to ship” from “needs human approval”.
+- Never auto-push copy into the sending platform without explicit human signoff.

package/skills/marketing-seo-ops.md

@@ -0,0 +1,32 @@
+---
+name: marketing-seo-ops
+description: SEO operations workflow for keyword prioritization, striking-distance wins, competitor gaps, and trend capture
+context: fork
+paths: []
+category: marketing
+requires:
+  anyBins: ["python3", "python"]
+---
+
+# Marketing SEO Ops
+
+## Use This For
+- Keyword research, content briefs, decaying-page recovery, or GSC-based prioritization.
+- Competitor gap analysis and trend scouting.
+- Turning traffic data into a ranked execution queue.
+
+## Ranking Model
+- Score opportunities on impact and confidence, then rank by the product of both.
+- Impact should include business value, intent, and trend direction.
+- Confidence should include attainable ranking distance, difficulty, and topic authority.
+
+## Preferred Workflow
+1. Pull striking-distance terms first; these are the fastest wins.
+2. Compare current coverage against competitor gaps.
+3. Check trend signals before proposing net-new content.
+4. Separate BOFU, MOFU, and TOFU so execution matches business intent.
+5. Return a prioritized queue with clear rationale, not a flat keyword dump.
+
+## Output Standard
+- Recommend the next pages to update, the next pages to create, and the pages to prune or refresh.
+- Include the evidence behind each call: position band, demand, trend, and likely lift.

package/skills/mcp-marketplace.md

@@ -0,0 +1,51 @@
+---
+name: mcp-marketplace
+description: Discover, install, audit, and manage MCP (Model Context Protocol) servers from the community registry. Use when adding new tools or capabilities from external MCP sources.
+---
+
+# MCP Marketplace Discovery
+
+Use when: discovering, installing, auditing, or managing MCP (Model Context Protocol) servers
+from the community marketplace.
+
+## Features
+- **Registry Search**: Search for MCP servers by name, capability, or category
+- **Auto-Install**: npm/pip install + config injection into .wotann/mcp-servers.json
+- **Security Audit**: Scan MCP server code for: eval(), exec(), network exfil, prompt injection
+- **Version Pinning**: Lock MCP server versions for reproducible setups
+- **Health Monitoring**: Track MCP server response time, error rates, uptime
+
+## Registry Format
+```yaml
+name: github-mcp
+version: 2.1.0
+author: modelcontextprotocol
+description: GitHub API integration via MCP
+tools:
+  - create_issue
+  - search_code
+  - list_pull_requests
+security:
+  audited: true
+  last_audit: 2026-03-15
+  network_access: true
+  file_access: false
+install: npm install @modelcontextprotocol/github-mcp
+```
+
+## Security Scan Protocol
+1. Clone/download the MCP server source
+2. Scan for dangerous patterns: eval, exec, spawn, fetch to unknown hosts
+3. Check dependencies for known vulnerabilities (npm audit / pip audit)
+4. Verify tool schemas match advertised capabilities
+5. Rate risk: LOW / MEDIUM / HIGH / CRITICAL
+6. Auto-reject CRITICAL, warn on HIGH, inform on MEDIUM
+
+## Categories
+- Code Intelligence (GitHub, GitLab, Bitbucket)
+- Database (PostgreSQL, MongoDB, Redis)
+- Communication (Slack, Discord, Email)
+- Cloud (AWS, GCP, Azure)
+- Monitoring (DataDog, PagerDuty)
+- AI/ML (HuggingFace, Replicate)
+- Productivity (Notion, Linear, Jira)

package/skills/memory-stack.md

@@ -0,0 +1,24 @@
+---
+name: memory-stack
+description: 8-layer memory search, save, verify operations
+context: main
+paths: []
+---
+# Memory Stack
+## Layers
+0. Auto-capture (every tool call logged).
+1. Core blocks (user/feedback/project/reference).
+2. Working memory (current session state).
+3. Knowledge graph (entity relationships).
+4. Archival (long-term with temporal decay).
+5. Recall (skeptical verification before use).
+6. Team memory (shared across agents).
+7. Proactive context (predicted needs).
+## Tools
+- `memory_search(query)` — FTS5 + semantic search.
+- `memory_replace(block, key, value)` — Update a block entry.
+- `memory_verify(id)` — Mark as verified (higher confidence).
+- `memory_archive(id)` — Move to archival storage.
+## Rules
+- Verify before acting on recalled memories (skeptical memory).
+- Save decisions proactively (don't wait to be asked).

package/skills/microservices-architect.md

@@ -0,0 +1,60 @@
+---
+name: microservices-architect
+description: Service boundaries, communication patterns, saga, CQRS, resilience
+context: fork
+paths: []
+---
+
+# Microservices Architect
+
+## When to Use
+- Decomposing a monolith into services.
+- Designing a new service boundary or its API contract.
+- Choosing between sync (REST/gRPC) and async (events) communication.
+- Introducing distributed transactions, saga, or CQRS.
+- Reviewing an existing microservice estate for fragility.
+
+## Rules
+- Services own their data — no shared databases across services.
+- APIs are versioned and backward-compatible; consumers should never break.
+- Prefer async (events) over sync where eventual consistency is acceptable.
+- Each service deploys independently; no lock-step releases.
+- Every inter-service call has timeout, retry with jitter, and a circuit breaker.
+- Observability is not optional — every hop logs trace ID + latency.
+
+## Patterns
+- **Strangler Fig** for monolith-to-microservices migration.
+- **Saga** (orchestrated or choreographed) for multi-service transactions.
+- **CQRS + Event Sourcing** where read and write shapes diverge.
+- **API Gateway** + **BFF** (Backend-for-Frontend) for edge composition.
+- **Outbox pattern** to avoid dual-write inconsistencies.
+- **Circuit breaker + bulkhead** for fault isolation.
+
+## Example
+```ts
+// Outbox pattern — DB and message bus stay consistent via one transactional write.
+await db.transaction(async (tx) => {
+  const order = await tx.orders.insert(payload);
+  await tx.outbox.insert({
+    aggregate: "order",
+    type: "OrderCreated",
+    payload: order,
+    createdAt: new Date(),
+  });
+});
+// A separate dispatcher polls `outbox` and publishes to Kafka, marking rows sent.
+```
+
+## Checklist
+- [ ] Each service has a clear, documented bounded context.
+- [ ] APIs versioned (URL or header) with deprecation path.
+- [ ] All inter-service calls wrapped with timeout + retry + circuit breaker.
+- [ ] Events are idempotent on the consumer side.
+- [ ] End-to-end trace ID propagates across every boundary.
+
+## Common Pitfalls
+- **Distributed monolith** — microservices that must deploy together.
+- **Chatty APIs** — N+1 calls across services for one user action.
+- **Shared DB** — breaks service autonomy.
+- **Dual writes** without outbox — inconsistencies leak.
+- **Over-splitting early** — microservices before you know the real boundaries.

package/skills/mongodb-expert.md

@@ -0,0 +1,58 @@
+---
+name: mongodb-expert
+description: MongoDB aggregation, indexing, sharding, change streams
+context: fork
+paths: ["**/mongo*", "**/*.mongo.{js,ts}", "**/models/**/*.{js,ts}"]
+---
+
+# MongoDB Expert
+
+## When to Use
+- Designing or reviewing MongoDB schemas, collections, or documents.
+- Tuning slow queries or diagnosing aggregation pipeline cost.
+- Choosing between single-collection, bucketed, or sharded layouts.
+- Wiring change streams for event-driven flows or CDC.
+- Planning replica-set reads/writes, read-preferences, or read-concerns.
+
+## Rules
+- Design schemas around query patterns first; denormalize when it saves roundtrips.
+- Use compound indexes that mirror query predicate order (ESR rule: Equality, Sort, Range).
+- Prefer aggregation pipelines over application-side joins.
+- Use change streams (resumeToken persisted) for real-time reactions, not polling.
+- Pin `readConcern: "majority"` for critical reads; use `writeConcern: { w: "majority" }` for durable writes.
+- Always size the working set to fit in RAM before scaling out via sharding.
+
+## Patterns
+- **Bucketing** for time-series or unbounded arrays: one document per bucket (hour/day).
+- **Attribute pattern** for sparse fields: `{ attrs: [{ k, v }] }` with index on `attrs.k`.
+- **Outlier pattern** for power-users: move rare large arrays to a separate collection.
+- **Subset pattern**: embed the hot subset, reference the cold tail.
+- **Schema versioning**: `{ _v: 2, ... }` field so migrations can run lazily.
+
+## Example
+```js
+// Aggregation: top 5 authors by comment count in the last 7 days.
+db.comments.aggregate([
+  { $match: { createdAt: { $gte: new Date(Date.now() - 7*864e5) } } },
+  { $group: { _id: "$authorId", n: { $sum: 1 } } },
+  { $sort: { n: -1 } },
+  { $limit: 5 },
+  { $lookup: { from: "users", localField: "_id", foreignField: "_id", as: "u" } },
+  { $project: { name: { $arrayElemAt: ["$u.name", 0] }, n: 1 } },
+]);
+// Index: { createdAt: 1, authorId: 1 } supports the $match + $group prefix.
+```
+
+## Checklist
+- [ ] Every query predicate has a supporting index (verified via `.explain("executionStats")`).
+- [ ] No `COLLSCAN` stages in hot-path `.explain()` output.
+- [ ] No unbounded arrays; bucketing or outlier pattern applied.
+- [ ] Write concern is explicit; no implicit `w: 1` in critical paths.
+- [ ] Schema document includes a `_v` version for future migrations.
+
+## Common Pitfalls
+- **Index bloat** from adding indexes without removing redundant prefixes.
+- **Unbounded `$where` / `$regex`** that can't use indexes.
+- **Over-sharding** before exhausting vertical and replica-set options.
+- **Forgetting `$sort` before `$group`** when using `$first/$last` in aggregations.
+- **Assuming atomicity** across documents — use transactions or design around single-doc updates.

package/skills/monitoring-expert.md

@@ -0,0 +1,69 @@
+---
+name: monitoring-expert
+description: Observability, metrics, logs, traces, SLOs, alerting
+context: fork
+paths: ["**/prometheus*", "**/grafana*", "**/alertmanager*", "**/telemetry/**"]
+---
+
+# Monitoring Expert
+
+## When to Use
+- Instrumenting a new service with metrics, logs, and traces.
+- Defining SLOs and error budgets.
+- Reviewing and reducing alert fatigue.
+- Building a dashboard for a new feature.
+- Investigating a production incident.
+
+## Rules
+- Instrument **RED** signals (Rate, Errors, Duration) for every public endpoint.
+- Instrument **USE** signals (Utilization, Saturation, Errors) for every resource.
+- Every alert must be actionable — otherwise it is not an alert.
+- Log structured JSON; always include a `trace_id`.
+- Trace IDs propagate via W3C `traceparent` across processes.
+- Never alert on a symptom without a backing metric.
+
+## Patterns
+- **Four golden signals** (Google SRE): latency, traffic, errors, saturation.
+- **SLO + error budget** with burn-rate alerts, not raw thresholds.
+- **OpenTelemetry** for unified metrics + logs + traces.
+- **Sampling**: 1-10% of traces under load, 100% on errors.
+- **Runbook link** in every alert payload so on-call reaches context fast.
+
+## Example
+```ts
+// OpenTelemetry — custom span + counter.
+import { trace, metrics } from "@opentelemetry/api";
+const tracer = trace.getTracer("billing");
+const meter = metrics.getMeter("billing");
+const invoiceCounter = meter.createCounter("invoices_created_total");
+
+export async function createInvoice(payload: InvoiceInput) {
+  return tracer.startActiveSpan("createInvoice", async (span) => {
+    try {
+      const invoice = await db.insert(payload);
+      invoiceCounter.add(1, { tier: payload.tier });
+      span.setAttribute("invoice.id", invoice.id);
+      return invoice;
+    } catch (err) {
+      span.recordException(err as Error);
+      throw err;
+    } finally {
+      span.end();
+    }
+  });
+}
+```
+
+## Checklist
+- [ ] SLOs written down with explicit targets (e.g. 99.9% over 30 days).
+- [ ] Every alert has a runbook link and a named owner.
+- [ ] p50, p95, p99 latency tracked — not just average.
+- [ ] Logs are structured and sampled appropriately.
+- [ ] Dashboards load in < 5s and surface the most important first.
+
+## Common Pitfalls
+- **Alerting on CPU** — rarely maps to user-visible impact.
+- **Raw thresholds** instead of burn-rate alerts.
+- **40-panel dashboards** that nobody reads.
+- **Logs without trace IDs** — impossible to correlate a request journey.
+- **Tracing only the happy path** — errors lose all context.