@coralai/sps-cli 0.42.0 → 0.44.0

package/skills/backend/references/observability.md

@@ -0,0 +1,190 @@
+# Observability
+
+Logs, metrics, traces, health. A request you can't trace is a bug you can't fix.
+
+## The three pillars
+
+| Signal | Answers | Cost | Cardinality |
+|---|---|---|---|
+| **Logs** | "What happened in this request?" | High (per-event) | Unlimited |
+| **Metrics** | "How much, how often, how fast, across the fleet?" | Low (aggregated) | Bounded (labels explode) |
+| **Traces** | "Where did time go in this distributed request?" | Medium (sampled) | Unlimited per trace |
+
+Pick the right signal for the question. Metrics for dashboards, logs for forensics, traces for latency breakdowns.
+
+## Structured logs — JSON, not prose
+
+Human-readable strings are unqueryable. Every log line is a JSON object with a stable schema.
+
+```json
+{
+  "ts": "2026-04-20T10:23:45.123Z",
+  "level": "info",
+  "service": "orders",
+  "env": "prod",
+  "request_id": "req_01HX...",
+  "trace_id": "0af7651916cd43dd...",
+  "user_id": "u_01HX...",
+  "msg": "order created",
+  "order_id": "ord_01HX...",
+  "amount_cents": 2599,
+  "duration_ms": 87
+}
+```
+
+Rules:
+- Always include `ts`, `level`, `service`, `env`.
+- Always include a request/trace id so you can stitch a request together across services.
+- Message is a short constant string — fixed values in `msg`, varying values in fields. `"order created"` not `"order ord_01HX created for $25.99"`.
+- Never log secrets, tokens, passwords, full PII. Redact at the logger, not the call site.
+
+## Log levels — use them honestly
+
+| Level | Means | Typical rate |
+|---|---|---|
+| ERROR | Something broke; a human should look | Low |
+| WARN | Unexpected, but handled (retry succeeded, fallback used) | Low |
+| INFO | State changes worth knowing at normal volume | Medium |
+| DEBUG | Details useful while investigating; off in prod | High (when on) |
+
+Abused levels poison the signal. If everything is INFO, nothing is INFO.
+
+## Correlation IDs
+
+Every request gets a unique id at the edge; it propagates through every log line and outbound call.
+
+```
+incoming request → generate request_id (or accept from X-Request-ID)
+                 → bind to logger context
+                 → forward on outbound calls (X-Request-ID, traceparent)
+```
+
+Distributed tracing (OpenTelemetry) gives you `trace_id` + `span_id` for free. Log both when you have them.
+
+## Metrics — RED + USE
+
+Two checklists that cover almost everything.
+
+### RED (per request-driven service)
+
+- **R**ate — requests per second
+- **E**rrors — failing requests per second (or error rate)
+- **D**uration — latency distribution (p50 / p95 / p99)
+
+### USE (per resource)
+
+- **U**tilization — how busy is it? (CPU%, thread pool in use / max)
+- **S**aturation — how much work is queued? (request queue depth)
+- **E**rrors — how many operations failed?
+
+Track these for every service and every critical dependency.
+
+## Latency — measure distributions, not averages
+
+Averages hide the worst cases. P95/P99 are where your users actually feel slowness.
+
+```
+# ✅
+http_request_duration_seconds{route="/orders", method="POST"}
+  → histogram with buckets (0.01, 0.05, 0.1, 0.5, 1, 5)
+  → alert on p99 > 1s for 5 min
+
+# ❌
+avg_response_time = sum(durations) / count(durations)
+  → a 10 s outlier buried in 999 fast ones looks fine
+```
+
+## Labels — finite cardinality
+
+Every unique label combination creates a new metric series. High-cardinality labels (user id, request id, email) will blow up storage and cost.
+
+| Label | OK? |
+|---|---|
+| route, method, status_code | Yes (small set) |
+| region, pod_name, env | Yes |
+| user_id, request_id, email, SKU | NO — use logs/traces for these |
+
+## Tracing
+
+A trace is a tree of spans representing one request's path through services. Each span has: operation name, start/end time, attributes, parent span.
+
+Auto-instrument with OpenTelemetry. Add manual spans around:
+- External HTTP calls (service, endpoint, status)
+- DB queries (operation, table; never the full raw query — cardinality)
+- Cache ops
+- Queue enqueue / dequeue
+- Expensive pure computations
+
+Sampling: head-based (1–10% of requests fully traced) or tail-based (keep traces where something went wrong). Keep tracer overhead < 1% of request latency.
+
+## SLOs — the contract
+
+An SLO is a number + a window. "99.9% of /orders responses succeed within 500 ms, measured over 28 days."
+
+Error budget = `1 − SLO`. Over 28 days, 99.9% allows ≈40 min of downtime. When you burn the budget, freeze risky changes and invest in reliability.
+
+Don't set SLOs to what your service does today. Set them to what your users need.
+
+## Alerts — page on symptoms, not causes
+
+Alert on "users are affected" (SLO burn rate, error rate spike, latency breach). Don't alert on "CPU is at 80%" — that's often fine.
+
+Every alert must be:
+- **Actionable** — there is something the oncall can do right now
+- **Unambiguous** — one cause for the page, not "anything could have fired this"
+- **Documented** — link to a runbook from the alert body
+
+If an alert fires and the oncall thinks "not my problem" or "auto-resolves in 5 min", it's a bad alert. Delete or tune it.
+
+## Runbooks
+
+One per alert. Structure:
+
+```
+# Alert: api-latency-p99-high
+
+## What this means
+p99 on /api/orders POST is > 1s for 5m.
+
+## Immediate checks
+1. Look at [dashboard-link]
+2. Check for recent deploy: [deploys-link]
+3. Check upstream health: [dep-status]
+
+## Common causes
+- DB slow query → check [slow-query-dashboard]
+- Cache outage → check redis metrics
+- Upstream payment provider → check provider status page
+
+## Mitigation
+- Roll back recent deploy if within 30 min window
+- Failover to secondary region
+- ...
+```
+
+## Health endpoints (minimal)
+
+```
+GET /health/live   → 200 if process can serve (don't check dependencies)
+GET /health/ready  → 200 only if dependencies are reachable (DB, cache, queue)
+```
+
+Live failing → orchestrator restarts the pod.
+Ready failing → orchestrator takes the pod out of the load balancer (but doesn't kill it).
+
+Never put business logic in health checks. They should be cheap and boring.
+
+## Anti-patterns
+
+| Anti-pattern | Why |
+|---|---|
+| String-formatted logs (`"user X did Y at Z"`) | Unqueryable |
+| Logging full request bodies | PII leak, storage blow-up |
+| Alerting on CPU / disk without symptom link | Pager fatigue; noise |
+| No request correlation id | Can't stitch a failure across services |
+| Logging at DEBUG in prod | Drowns the signal; storage cost |
+| `avg_latency` as the only latency metric | Hides the outliers that hurt users |
+| `status:500` as the only error signal | 200 with `{error: ...}` bodies exist and hurt |
+| Metrics labels with user id / email | Cardinality explosion |
+| Tracing everything, sampling nothing | Cost blowup; latency overhead |
+| Alerts without runbooks | Oncall guesses, takes too long |

package/skills/backend/references/resilience.md

@@ -0,0 +1,201 @@
+# Resilience
+
+Timeouts, retries, circuit breakers, idempotency, background jobs. Make failures cheap.
+
+## Timeouts — every outbound call
+
+No exceptions. A dependency that never answers will exhaust threads, sockets, and memory.
+
+```
+# Wrong: no timeout
+response = http.get("https://upstream/api")
+
+# Right: fail fast
+response = http.get("https://upstream/api", timeout=2.0)
+```
+
+Timeout budget, layered:
+
+```
+client            10s
+  └ gateway        8s
+     └ service    5s
+        └ dependency call  2s   ← must be smaller than parent budget
+```
+
+If the inner call's timeout ≥ the outer's, the outer never gets to return a clean 504 — it just hangs.
+
+## Retries — only for safe, transient failures
+
+**Retryable**:
+- Network timeouts
+- 5xx on GET/idempotent calls
+- 429 (with `Retry-After`)
+- Explicit DB "retry" errors (e.g., serialization failures)
+
+**NOT retryable**:
+- 4xx other than 429 (client bug; retry won't help)
+- Any non-idempotent call without an `Idempotency-Key`
+- "Connection reset" where the write may have landed
+
+### Exponential backoff with jitter
+
+Pure exponential backoff creates thundering herds when many clients fail together. Always add jitter.
+
+```
+attempt(n):
+    base = 100ms
+    max  = 10s
+    sleep = min(max, base * 2^n) * random(0.5, 1.5)
+```
+
+Bound the total attempts and total time; don't let retries outlive the user's patience.
+
+## Circuit breakers
+
+When a dependency is sick, stop hammering it. Three states:
+
+```
+  CLOSED (normal)
+    │  failures exceed threshold
+    ▼
+   OPEN (fail fast, short-circuit calls)
+    │  after cool-down, try one request
+    ▼
+ HALF_OPEN ──success──► CLOSED
+    │
+    └─failure──────────► OPEN
+```
+
+Thresholds to tune: error rate (e.g., >50% of last 20 calls), minimum sample size, cool-down time, half-open probe count.
+
+Open-circuit response: fall back to cache, degraded response, or fail fast with 503. Never silently return empty data.
+
+## Idempotency
+
+Any operation that might be retried must be safe to run twice.
+
+### Idempotency keys
+
+For non-GET HTTP writes, accept an `Idempotency-Key` header.
+
+```
+POST /payments
+Idempotency-Key: 7a8b9c...
+
+server:
+  stored = store.get(key)
+  if stored and stored.request_hash == hash(body):
+      return stored.response
+  if stored:
+      return 409   # same key, different body → conflict
+  response = execute()
+  store.set(key, (hash(body), response), ttl=24h)
+  return response
+```
+
+### Natural idempotency
+
+Often better than keys: design the operation so repeats are harmless.
+
+```
+# Not idempotent
+UPDATE balance SET amount = amount + 10 WHERE id = 1
+
+# Idempotent — absorbs double-apply
+INSERT INTO ledger (id, account, amount) VALUES (:tx_id, 1, 10)
+ON CONFLICT (id) DO NOTHING
+```
+
+## Graceful degradation
+
+When a non-critical dependency is down, return a usable response, not an error.
+
+```
+product = productRepo.get(id)
+try:
+    product.recommendations = recService.for(id, timeout=300ms)
+except (Timeout, ServiceError):
+    product.recommendations = []        # degrade, don't fail
+return product
+```
+
+Decide up front which pieces are essential vs. nice-to-have. Never degrade silently on essentials (payments, auth).
+
+## Background jobs
+
+For anything not strictly needed in the request path: send, enqueue, return.
+
+```
+# Request path
+handler(req):
+    order = orderRepo.save(newOrder)
+    queue.enqueue(SendOrderEmail(order.id))      # defer
+    queue.enqueue(UpdateSearchIndex(order.id))
+    return 201
+```
+
+Queue requirements:
+- **Durable** — enqueue survives broker restart (disk, replicated)
+- **At-least-once delivery** — so jobs must be idempotent
+- **Dead-letter queue** — after N failures, park the message and alert
+- **Visibility timeout** — consumer crashes → job requeues automatically
+
+Common choices: Postgres-backed (pgboss, solid-queue), Redis (BullMQ, Sidekiq), managed (SQS, Cloud Tasks), streaming (Kafka).
+
+## Scheduled jobs
+
+Two traps:
+1. **Lock per job** — multiple replicas must not run the same job twice. Use a DB advisory lock or a leader-election lib.
+2. **Overlap** — if a job runs longer than its interval, the next tick starts before the previous ends. Decide: skip, queue, or overlap — explicitly.
+
+Don't use `cron` on a single VM in production; it dies with the VM. Use a platform scheduler (Kubernetes CronJob, cloud scheduler) + idempotent job logic.
+
+## Health checks
+
+Two separate endpoints:
+
+```
+GET /health/live         # Am I running? (200 = process alive)
+GET /health/ready        # Can I take traffic? (checks DB, cache, queue connectivity)
+```
+
+Orchestrators (K8s, load balancers) need both. `/ready` failing for 30s → take the pod out of rotation, don't kill it.
+
+## Graceful shutdown
+
+On SIGTERM:
+1. Stop accepting new requests (`/ready` → 503).
+2. Finish in-flight requests (with a hard deadline, e.g., 30 s).
+3. Drain the job consumer.
+4. Close DB pools and sockets.
+5. Exit.
+
+Without this, a deploy drops requests and leaves half-processed jobs.
+
+## Bulkheads
+
+Isolate failure domains so one tenant / feature can't drown the others.
+
+- Separate thread pool / connection pool per downstream service
+- Separate queue / worker group per job class
+- Separate rate limit per tenant
+
+One noisy neighbor should degrade its own lane, not everyone's.
+
+## Timeouts for tasks, not just HTTP
+
+DB query timeouts (`statement_timeout` in Postgres), job max runtime, lock wait timeout — all finite. Anything unbounded will eventually hang something.
+
+## Anti-patterns
+
+| Anti-pattern | Why |
+|---|---|
+| Infinite retries | One bad day becomes a queue explosion |
+| Retries without backoff | Synchronized thundering herds |
+| Retry on POST without idempotency key | Duplicate payments, double-sends |
+| Shared retry budget across unrelated calls | One bad dep exhausts retries for healthy ones |
+| Catching all exceptions to mask failures | Bugs silently go to prod |
+| Fire-and-forget without a dead-letter queue | Failed jobs vanish with no alert |
+| "Run every N seconds" cron on a single machine | Loses work on reboot |
+| Waiting forever for a lock | Locks don't auto-expire unless you say so |

package/skills/backend/references/security.md

@@ -0,0 +1,186 @@
+# Security
+
+Authentication, authorization, input validation, rate limiting, secrets. The non-negotiables.
+
+## AuthN vs AuthZ
+
+| | Authentication | Authorization |
+|---|---|---|
+| Answers | Who are you? | What can you do? |
+| Failure code | 401 | 403 |
+| Mechanism | Session, token, signature | Role / policy / permission check |
+
+Never conflate these. A 401 says "tell me who you are"; a 403 says "I know who you are and you can't do this".
+
+## Session vs token
+
+| | Server session | Stateless token (JWT) |
+|---|---|---|
+| State | Server-side (DB / Redis) | In the token itself |
+| Revocation | Delete session row | Hard — need blocklist or short TTL |
+| Scale | Needs sticky / shared store | Stateless across servers |
+| Size on wire | Small (cookie id) | Large (signed payload) |
+| First-party web | Excellent | Overkill |
+| Service-to-service | Weak | Natural fit |
+
+For a browser-based web app, **server-side sessions with secure cookies** are usually the right answer. JWTs shine for APIs, federation, and service-to-service.
+
+## Cookies — secure defaults
+
+```
+Set-Cookie: session=abc...; Secure; HttpOnly; SameSite=Lax; Path=/
+```
+
+- **Secure** — HTTPS only.
+- **HttpOnly** — JS can't read it (blocks XSS-based token theft).
+- **SameSite=Lax** — default; blocks CSRF on cross-site POSTs. Use `Strict` for admin; `None` + `Secure` only for true cross-origin use cases.
+- **Path** — scope to where it's needed.
+- Don't store user data in the cookie payload; store an opaque session id.
+
+## JWT rules
+
+- Always check signature. Reject `alg: none`. Reject unexpected algorithms.
+- Verify `iss`, `aud`, `exp`, `nbf`.
+- Short lifetime (5–15 min) + rotating refresh token.
+- Don't put secrets inside; tokens are readable by anyone who has them.
+- Rotate signing keys; publish via JWKS.
+- Revocation: maintain a short jti blocklist in Redis for stolen-token cases.
+
+## Authorization models
+
+| Model | Use when |
+|---|---|
+| RBAC (roles) | Small fixed set of roles: admin, user, moderator |
+| ABAC (attributes) | Rules depend on attributes of user, resource, time, IP |
+| ReBAC (relationships) | "Can Alice read doc X?" answered via a graph (Google Zanzibar / OpenFGA) |
+| Policy-as-code (OPA, Cedar) | Complex rules that need to live outside the app |
+
+Start with RBAC. Graduate to ReBAC/ABAC when roles no longer express the rules. Never hard-code `if user.email == "admin@x.com"`.
+
+## Enforce authorization at the boundary
+
+Every handler starts with a permission check. No implicit trust.
+
+```
+handler(req):
+    user = requireAuth(req)
+    resource = repo.load(req.id)
+    if not user.can(READ, resource):
+        return 403 | 404           # 404 if the existence of the resource is itself secret
+    return resource
+```
+
+`403` vs `404`: return 404 if the existence of the resource is itself secret (e.g., private documents); return 403 otherwise.
+
+## Input validation
+
+Validate everything at the edge, once. Never trust "internal" callers.
+
+```
+schema:
+    email   : string, format=email
+    age     : int, 0 <= x <= 150
+    role    : enum(user, admin)
+
+handler(req):
+    cmd = schema.parse(req.body)      # rejects anything else
+    useCase.execute(cmd)
+```
+
+Rules:
+- Whitelist what you accept, not blacklist what you reject.
+- Reject unknown fields (guard against mass-assignment).
+- Bound all variable-size inputs (strings, arrays): `max_length`, `max_items`.
+- Parse into strong types at the boundary; don't pass raw dicts through the system.
+
+## Injection defenses
+
+- **SQL**: parameterized queries ONLY. Never string-concatenate. ORMs handle this if you use their query API, not raw strings.
+- **Command**: don't build shell commands from user input. If you must: use array-form `exec` (no shell) and whitelist args.
+- **LDAP / XPath / NoSQL**: same rule — parameterize.
+- **Template injection**: never render user input as a template (Jinja2, ERB, etc.).
+- **Path traversal**: canonicalize and assert the result is inside an allow-listed directory.
+- **Prototype pollution / mass assignment**: whitelist fields; never `Object.assign(user, req.body)`.
+
+## Passwords
+
+- **argon2id** (preferred) or **bcrypt** (with cost ≥ 12). Never SHA-* for passwords.
+- Never log passwords, even hashed.
+- Enforce length (≥ 12 chars), not character classes. Check against a breached-password list (HaveIBeenPwned API / offline list).
+- Account-level lockout on repeated failures, plus rate limiting per IP/account.
+
+## Secrets
+
+- Never in source control. `.env` files are .gitignored; production secrets come from a secret manager (Vault, AWS Secrets Manager, GCP Secret Manager, 1Password Connect).
+- Rotate on compromise AND on a schedule.
+- Scope per-service and per-environment. One stolen dev key should never reach prod.
+- Don't print secrets to logs. Redact at the logger config.
+
+## Rate limiting
+
+Apply at the edge (CDN/API gateway) AND per-endpoint in the app.
+
+Limits by identity:
+- Anonymous: by IP — coarse, bypassable with proxies.
+- Authenticated: by user id — reliable.
+- Authenticated + IP: both, for defense in depth.
+
+Algorithms:
+- **Token bucket**: allows short bursts; refill rate controls long-run.
+- **Fixed window**: simple, but bursty at boundaries.
+- **Sliding window**: smooth; costs more.
+
+Always include `Retry-After` on 429 responses.
+
+## CSRF
+
+Required if the client is a browser using cookies. Not required if you use `Authorization: Bearer` (attacker can't trigger the header).
+
+Defenses, pick one:
+- **SameSite=Lax cookie** (default-covers most cases).
+- **Double-submit cookie** — random token in cookie AND in a header; server checks they match.
+- **Synchronizer token** — per-session token in the form + server-side store.
+
+## CORS
+
+Set it to what you actually need. `Access-Control-Allow-Origin: *` with credentials is a silent vulnerability — browsers refuse, but a misconfigured gateway can still leak.
+
+```
+Access-Control-Allow-Origin: https://app.example.com
+Access-Control-Allow-Credentials: true
+Access-Control-Allow-Methods: GET, POST, PATCH, DELETE
+Access-Control-Allow-Headers: Authorization, Content-Type
+Access-Control-Max-Age: 86400
+```
+
+## Security headers (for any HTML-serving endpoint)
+
+```
+Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
+Content-Security-Policy: default-src 'self'; ...
+X-Content-Type-Options: nosniff
+Referrer-Policy: strict-origin-when-cross-origin
+Permissions-Policy: camera=(), microphone=(), geolocation=()
+```
+
+## Audit logging
+
+Every security-relevant event gets an immutable log entry:
+- login (success / fail), password change, role change, permission change
+- admin actions, data exports
+- access to sensitive resources
+
+Include: actor, action, target, timestamp, source IP, request id. Store separately from app logs so a compromised app can't tamper with them.
+
+## Anti-patterns
+
+| Anti-pattern | Why |
+|---|---|
+| Rolling your own crypto | Don't. Use the standard library / vetted lib. |
+| Comparing secrets with `==` | Timing attack; use constant-time compare |
+| Returning different errors for "user doesn't exist" vs "wrong password" | Username enumeration |
+| Trusting `X-Forwarded-For` without checking source | Spoofable; respect it only from trusted proxies |
+| One API key per team, shared over Slack | No revocation granularity |
+| Storing JWTs in localStorage | XSS steals them; use HttpOnly cookies |
+| "Security through obscurity" (weird endpoint paths) | Not a control |
+| Disabling TLS verification "temporarily" in prod | Never |

package/skills/backend-architect/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: backend-architect
+description: Persona skill — think like a backend architect. System boundaries, data flow, scaling, failure modes. Overlay on top of `backend` + language skills. For the patterns themselves, load `backend`.
+origin: agency-agents-fork + original (https://github.com/msitarzewski/agency-agents, MIT)
+---
+
+# Backend Architect
+
+Think like a backend architect. This skill is a **mindset overlay**, not a pattern catalogue — load `backend` for patterns.
+
+## When to load
+
+- Designing a new service / feature
+- Reviewing an architectural proposal
+- Debating storage / queue / cache choices
+- Reviewing a migration plan
+- Choosing between build vs. buy / in-house vs. managed
+
+## The posture
+
+1. **Draw the boundaries first.** Service A knows nothing of Service B's internals. Any leak is an eventual coupling bug.
+2. **Favor boring technology.** Postgres + a job queue solves 90% of problems. Reach for specialized tools only when boring can't.
+3. **Design for the failure cases.** What happens when the DB is slow, the queue is backed up, the API key rotates, the region goes down?
+4. **Measure before optimizing.** "Could be a bottleneck" is hypothesis, not evidence.
+5. **Data is the hard part.** Compute scales; data is where consistency, durability, and migrations bite.
+6. **Decisions > diagrams.** A clean ADR that records WHY this over that outlives any whiteboard.
+7. **Operational load is a product requirement.** If oncall hates it at 3am, it's not done.
+
+## The questions you always ask
+
+Before approving or shipping a design:
+
+- **What's the failure mode?** What breaks first, and what does the user see?
+- **What's the blast radius?** Does a bug in this service hurt just this feature, or take the whole site down?
+- **What's the rollback story?** How do we get back if this deploy is bad?
+- **How does this scale 10×?** Will this design hold at 10× the current load?
+- **Where's the data authority?** If two stores disagree, who wins?
+- **What's the consistency model?** Strong, eventual, read-your-writes — per data type?
+- **What invariants does the DB enforce vs. the app?** Every invariant the app "promises" is a race away from being wrong.
+- **What observability does a developer get at 3am?** Logs, metrics, traces for the failure mode.
+- **Is this idempotent?** Every write must be safe to retry.
+- **Is the contract stable?** What's the versioning plan for public interfaces?
+
+## The checklist
+
+For a new service or major feature, walk through:
+
+### Contract
+- [ ] API design: REST / GraphQL / gRPC chosen with reason.
+- [ ] Error shape and status codes standardized.
+- [ ] Versioning strategy.
+- [ ] Idempotency keys on non-GET writes.
+
+### Data
+- [ ] Schema reviewed for normalization, constraints, types.
+- [ ] Foreign keys declared, not just "promised".
+- [ ] Indexes match the real queries.
+- [ ] Migration plan is expand/contract.
+- [ ] Backup and restore tested.
+
+### Infra
+- [ ] Timeouts on every outbound call.
+- [ ] Retries only on idempotent ops with jitter.
+- [ ] Circuit breaker or fallback for dependencies.
+- [ ] Resource limits (CPU, memory, pool sizes) sized, not left as defaults.
+
+### Operations
+- [ ] Health check endpoints (/health/live, /health/ready).
+- [ ] Graceful shutdown on SIGTERM.
+- [ ] Structured logs with request / trace id.
+- [ ] Key metrics exposed (RED signals + saturation).
+- [ ] Alerts defined with runbooks.
+- [ ] Oncall documented in service catalogue.
+
+### Security
+- [ ] Auth check at the boundary.
+- [ ] Input validated at the edge.
+- [ ] Secrets pulled from secret manager, not config.
+- [ ] PII handling documented.
+- [ ] Rate limiting on public endpoints.
+
+### Rollout
+- [ ] Feature flag if behaviour-changing.
+- [ ] Deploy plan: dev → staging → canary → prod.
+- [ ] Rollback command documented.
+- [ ] Observability dashboards exist before release.
+
+## Tradeoffs you name explicitly
+
+- **Strong consistency vs. throughput** — pick per-data-type.
+- **Sync vs. async** — user waiting ≠ background reliability.
+- **Monolith vs. services** — don't split until scale / team pain demands.
+- **Build vs. buy** — buy the commodity; build where you compete.
+- **Flexibility vs. simplicity** — the "flexible" option usually has the higher total cost.
+
+## What you push back on
+
+- **Premature microservices.** Added complexity for no measurable benefit.
+- **Ad-hoc schema fields** shoved into JSON columns to "move fast". They become queryable and regret-worthy in months.
+- **"Reactive everything"** where a simple sync call would work.
+- **Home-rolled queues / sharding / consensus.** Almost always the wrong build.
+- **Decisions without ADRs.** The reason is always the first thing lost.
+
+## Forbidden patterns
+
+- Architecture diagrams without failure annotations
+- Proposals that skip "what happens if X is down"
+- Two-phase commit across service boundaries (usually a sign the services should be one)
+- Cross-service database joins ("just query the other team's DB")
+- Silent coupling — services that "happen to know" each other's internals
+- New services without owners, dashboards, and oncall
+- Technology choices made because "it's popular"
+
+## Pair with
+
+- [`backend`](../backend/SKILL.md) — the patterns.
+- [`database`](../database/SKILL.md) — schema / scaling details.
+- [`devops`](../devops/SKILL.md) — how it deploys and is operated.
+- [`architecture-decision-records`](../architecture-decision-records/SKILL.md) — recording the decisions.