Omar SobhandClaude Opus 4.7
7b23f61632
Hand-authored skill catalog anchored to real 2026-07 versions:
- Rust 1.97.1 (stable), edition 2024
- React 19.2.7, Server Components + Actions
- TailwindCSS 4.3.3 (CSS-first config, Oxide engine)
- three.js r185 (WebGPURenderer stable, BatchedMesh matured)
- React Native 0.86 / Expo SDK 54+ (New Architecture default)
- cargo-nextest 0.9.140, gitleaks 8.20+, cargo-audit 0.21+
- Postgres 17 (18 in beta, don't rely on)
- CUDA Blackwell, Metal Apple7+, ROCm CDNA3
Ships 15 skills across the categories:
foundation/ workspace-repo-commit-protocol
small-focused-commits
tdd-red-green-refactor
code-review-checklist
int-xx-marker-protocol
decompose-int-items
rust/ write-rust-current-edition
rust-error-handling
cargo-test-driven-development
rust-async-tokio-idioms
backend/ postgres-migrations-forward-only
postgres-index-selection
api-pagination-day-1
frontend/ react-19-server-components
tailwind-v4-idioms
component-4-state-model
mobile/ expo-managed-vs-bare
rn-flashlist-perf
gpu/ gpu-coalescing-and-occupancy
roofline-model
threejs/ threejs-perf-and-teardown
security/ cargo-audit-workflow
secret-scanning-gitleaks
skills_loader.rs walks skills/**/*.md, parses YAML frontmatter
(name, description, when_to_use, tags), upserts via
skills_catalog::upsert_builtin. Idempotent per boot — bumps version
+ appends skill_versions row ONLY when body changes. Deterministic
sha256-derived ids so builtins are stable across boots.
Dockerfile copies skills/ to /etc/clawmates/skills. Server boot
task spawns loader alongside team_template_loader.
Follow-ups (Slice 3.5c continuation, future PRs):
- 20-30 more skills (duckdb, shadcn composition, a11y, WebGPU
migration, metal frame capture, rocprof, deep gitea forge
integration, semgrep rulepacks)
- Bind skills to team template roles (add [role.skills] refs to
templates/teams/*.toml + wire template_role_skills population
in team_template_loader)
Co-Authored-By: Claude Opus 4.7 <[email protected]>
67 lines
2.8 KiB
Markdown
67 lines
2.8 KiB
Markdown
---
|
|
name: api-pagination-day-1
|
|
description: Every list endpoint paginates from the first version. Cursor-based over offset. Bounded max_limit. Includes total when cheap.
|
|
when_to_use: You're the api_designer role, or a coder adding any `GET /...` endpoint that returns a collection.
|
|
tags: [backend, api]
|
|
---
|
|
|
|
# List endpoints paginate from day 1
|
|
|
|
Unpaginated lists are a production incident waiting to happen. The one time the endpoint is called with a million-row table, the response body fills the load balancer's buffer, memory spikes, and everything downstream 503s.
|
|
|
|
## The pattern
|
|
|
|
```rust
|
|
#[derive(Deserialize)]
|
|
struct ListQuery {
|
|
#[serde(default = "default_limit")]
|
|
limit: u32,
|
|
/// Cursor from a prior page's `next_cursor`. Opaque to the client.
|
|
cursor: Option<String>,
|
|
}
|
|
fn default_limit() -> u32 { 50 }
|
|
const MAX_LIMIT: u32 = 500;
|
|
|
|
#[derive(Serialize)]
|
|
struct Page<T> {
|
|
items: Vec<T>,
|
|
next_cursor: Option<String>,
|
|
/// Present only when it's cheap to compute (COUNT(*) over a small
|
|
/// filtered set). Never for a full-table count.
|
|
#[serde(skip_serializing_if = "Option::is_none")]
|
|
total: Option<u64>,
|
|
}
|
|
```
|
|
|
|
## Cursor over offset
|
|
|
|
- **Offset (`LIMIT 50 OFFSET 500`)** — Postgres scans and discards the first 500 rows on every request. Cost grows with page number.
|
|
- **Cursor (`WHERE id > $cursor ORDER BY id LIMIT 50`)** — O(log n) always. The cursor is the last row's sort key, base64'd (or JWT-signed if you want tamper-detection).
|
|
|
|
For clawmates, the standard cursor shape is `base64(json({"id": "...", "ts": "..."}))` — includes id + the ORDER BY tiebreaker so pages are deterministic even under concurrent inserts.
|
|
|
|
## Bounds
|
|
|
|
- **`limit.clamp(1, MAX_LIMIT)`** — server-side clamp, not just server-side validation. Never trust the client to respect `max_limit`.
|
|
- **Return `413 Payload Too Large`** when a caller sends `limit=100000` if you'd rather they notice than have their traffic silently clamped.
|
|
|
|
## Sorting
|
|
|
|
- Every paginated endpoint has ONE canonical sort order.
|
|
- Cursor must include the sort key + a tie-breaker (usually `id`). Otherwise two rows with the same sort key can be missed or duplicated across pages.
|
|
|
|
## Total counts
|
|
|
|
- Cheap: `SELECT count(*) FROM t WHERE small_indexed_filter`. Include it.
|
|
- Expensive: unfiltered COUNT on a large table. **Don't run it.** Return `total: null` and let the UI show "50 of many".
|
|
|
|
## OpenAPI
|
|
|
|
The response schema declares `items`, `next_cursor`, and `total?`. Never return a bare array — you can't add a cursor later without a breaking change.
|
|
|
|
## Anti-patterns
|
|
|
|
- **`GET /foo` returning `[...]`** with no pagination shape. Every list route pays for future-proofing on day 1.
|
|
- **`page=N&per_page=M`** — offset-based. Ships until traffic bites you.
|
|
- **Cursor that includes an unsigned index into a mutable list** — reorders + inserts corrupt it. Cursor must be a stable identifier.
|