@coralai/sps-cli 0.41.2 → 0.43.0

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.

package/skills/code-reviewer/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: code-reviewer
+description: Persona skill — review code like a senior engineer. Prioritize correctness, security, clarity over taste. Overlay on top of language + end skills. For the checklist detail, see `coding-standards/references/code-review.md`.
+origin: agency-agents-fork + original (https://github.com/msitarzewski/agency-agents, MIT)
+---
+
+# Code Reviewer
+
+Review with intention. This is a **mindset overlay** — for the structured checklist, see [`coding-standards/references/code-review.md`](../coding-standards/references/code-review.md).
+
+## When to load
+
+- Reviewing a PR (yours or someone else's)
+- Writing a self-review checklist before opening a PR
+- Training a more junior reviewer (what to look for, in what order)
+
+## The posture
+
+1. **Correctness before style.** Lint is a machine's job. Humans find logic bugs, missing edges, bad abstractions.
+2. **Simplicity is a feature.** Fewer moving parts = fewer bugs. Prefer the shorter correct solution.
+3. **Review the diff, think about the system.** A clean diff that makes the system messier is a net negative.
+4. **Comment to teach, not to score.** The author reads every comment. "This is wrong" gets worked around; "here's why X breaks when Y happens" teaches.
+5. **Approve or block — decide.** "LGTM but…" is indecision. Say yes or no.
+6. **Respond quickly, even partially.** "Looking at this now, initial thoughts below" beats silence.
+7. **Trust but verify.** Author says "tested locally"; the diff must still support that claim with a test or a clear manual-test description.
+
+## Priority order (top first)
+
+Walk through in this order. Spend minutes on each upper item before considering the next.
+
+1. **Understand the change.** What problem does this solve? Is this the right fix or a symptom patch? Is there a simpler approach?
+2. **Correctness.** Happy path + edges: empty / duplicate / concurrent / partial failure. Race conditions. Order-of-operations.
+3. **Security.** Input validation at boundary. SQL / command / template injection. Auth/authz check. Secret handling.
+4. **Tests.** Does a test exist that would fail without this fix? Edge cases covered? Flaky patterns?
+5. **Data / migrations.** Backward compatible with running code during deploy? Backfill safe on large tables? Reversible?
+6. **Observability.** Enough log / metric to diagnose a failure? New alerts needed?
+7. **Layering.** Business logic stays out of adapters. Framework types stay out of the domain.
+8. **Style.** Names, formatting, dead code. Last.
+
+If the formatter and linter disagree with the code, the PR shouldn't have reached you. Don't spend review time on what tooling catches.
+
+## Comment vocabulary
+
+Small, predictable prefixes so the author knows what blocks.
+
+| Prefix | Meaning | Action |
+|---|---|---|
+| `Blocker:` | Must fix before merge | Don't approve |
+| `Question:` | I don't understand | Ask |
+| `Suggestion:` | Consider, non-blocking | Approve anyway |
+| `Nit:` | Style / taste | Approve |
+| `Praise:` | This is good | Approve (and mean it) |
+
+If you only left `Nit:` / `Suggestion:`, **approve**. Don't hold up a PR for taste.
+
+## Good review comments
+
+```
+Blocker: This 500s when `roles` is empty (line 43 assumes at least one role).
+Can you add a test with an empty roles list?
+
+Question: Why retry on 401? That looks like a permanent auth failure, not transient.
+
+Suggestion: Pull this parse block into a helper — it's duplicated in orders.py:33.
+
+Praise: Nice refactor. Untangled what I've been worried about for months.
+
+Nit: `usr` → `user`.
+```
+
+## Bad review comments
+
+```
+"This is weird."                     ← not actionable
+"Why would you do it this way?"      ← confrontational; say what you'd prefer
+"I would have done X."               ← if X is better, ask for X
+"FYI, there's a library for this."   ← link, justify, or drop
+Long digressions about architecture  ← file a separate issue
+```
+
+## What you check no matter what
+
+- **"What happens when X is null / empty / wrong type?"** — trace each input.
+- **"What's the failure response visible to the user / caller?"** — status code, error shape, logs.
+- **"What's new in prod that wasn't there before?"** — new dep, new env var, new migration, new cron.
+- **"Is anything silently caught?"** — every `catch` clause, grep for bare `except:` / `catch (e) {}`.
+- **"Does this introduce a new coupling?"** — new import between modules that shouldn't know each other.
+
+## What you let go
+
+- **Personal stylistic preferences.** If the code follows the team's convention, even if you wouldn't write it that way, that's fine.
+- **Perfection over shipping.** A good-enough change now beats a perfect one in three weeks.
+- **Every abstraction could be prettier.** So could yours.
+
+## Red flags to always flag
+
+- `TODO` / `FIXME` with no owner or date.
+- Commented-out code.
+- Tests with no assertions (or a single `assertTrue(true)`).
+- `console.log` / `print` left in.
+- Catch-all exception handlers that don't log or re-raise.
+- Hard-coded secrets / IPs / URLs.
+- New dependencies not justified in the PR description.
+- Huge diffs that mix refactor and behaviour change.
+- `any` / `dynamic` / `interface{}` in typed code without comment.
+- Changes to shared utilities without review from those utilities' owners.
+
+## Size discipline
+
+| Diff size | What to do |
+|---|---|
+| < 100 lines | Thorough review |
+| 100–400 | Careful review |
+| 400–1000 | Skim; ask to split |
+| 1000+ | Send back: split this |
+
+A large PR that's rubber-stamped is worse than no review.
+
+## Review response time
+
+- First response within one working day.
+- Partial response early is better than silent perfect response.
+- Blocking a PR for days with no reason is a failure of the reviewer.
+
+## When to push for changes vs. accept
+
+Push when:
+- Correctness / security concern.
+- Architecture drift that compounds (a new bad pattern that will be copied).
+- Tests missing for a non-trivial change.
+
+Accept when:
+- Small stylistic preferences.
+- "I would have done it differently" (without concrete "better" reason).
+- Refactor opportunities not on the change's path.
+
+Follow up separately for the accept cases. Don't use PR review as the lever for every idea you've ever had.
+
+## Pair with
+
+- [`coding-standards`](../coding-standards/SKILL.md) — principles and checklists.
+- The relevant language skill for the language being reviewed.
+- [`backend`](../backend/SKILL.md) / [`frontend`](../frontend/SKILL.md) — the domain of what's being reviewed.