@skill-graph/cli 0.5.6

package/marketplace/skills/background-jobs/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: background-jobs
+description: "This skill provides background job patterns for web applications: job queue architecture, long-running sync operations, progress tracking and reporting, failure handling and retry, job prioritization, and concurrency management. Load when implementing async processing, building job queues, designing progress indicators for long operations, or handling failure recovery for background work."
+license: MIT
+compatibility: "Markdown, Git, agent-skill runtimes"
+allowed-tools: Read Grep Bash
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/async\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-03-29\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-03-29\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"background-jobs\\\\\\\",\\\\\\\"background\\\\\\\",\\\\\\\"jobs\\\\\\\"]\",\"triggers\":\"[\\\\\\\"background-jobs-skill\\\\\\\",\\\\\\\"job-queue-skill\\\\\\\",\\\\\\\"async-processing-skill\\\\\\\",\\\\\\\"long-running-task-skill\\\\\\\",\\\\\\\"worker-pattern-skill\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"cron-scheduling\\\\\\\"],\\\\\\\"boundary\\\\\\\":[\\\\\\\"real-time-updates\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":90,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/background-jobs/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/background-jobs/SKILL.md
+---
+# Background Jobs Skill
+
+## Domain Context
+
+**What is this skill?** This skill provides background job patterns for web applications: job queue architecture, long-running sync operations, progress tracking and reporting, failure handling and retry, job prioritization, and concurrency management. Load when implementing async processing, building job queues, designing progress indicators for long operations, or handling failure recovery for background work.
+> If it takes longer than 10 seconds, it does not belong in a request handler. Move it to a background job with progress tracking.
+
+## Coverage
+
+This skill covers job queue architecture (push-based vs pull-based, priority queues), long-running operation patterns (sync jobs, data migrations, bulk operations), progress tracking and reporting (percentage, stage-based, ETA estimation), failure handling and retry strategies (exponential backoff, dead letter queues, partial failure recovery), job prioritization and concurrency control, the decision framework for inline vs background execution, and user-facing progress communication patterns.
+
+## Philosophy
+
+Background jobs are the mechanism that separates a responsive user interface from reliable data processing. The web request lifecycle imposes hard time limits (Vercel: 60-300s, Lambda: 15min), but real-world operations — syncing 50,000 orders, generating monthly reports, reconciling financial data — can take minutes or hours. Agents frequently make two mistakes: putting long operations in request handlers (causing timeouts and poor UX) or moving operations to background jobs without progress tracking (leaving users staring at a spinner with no feedback). Both destroy user trust. This skill enforces the discipline of moving heavy work out of the request path while keeping the user informed of progress.
+
+## Architecture
+
+### Execution Model Decision
+
+| Question | If Yes | If No |
+|----------|--------|-------|
+| Does the user need the result immediately? | Keep inline (< 10s) | Background job |
+| Can the operation fail partially? | Background with checkpoint | Simple background |
+| Does the user need progress updates? | Background + progress tracking | Fire-and-forget |
+| Could the operation take > 60 seconds? | Always background | Inline may work |
+| Is the operation triggered by multiple sources? | Job queue with deduplication | Direct invocation OK |
+
+### Job Queue Architecture
+
+```
+Producer (API route, webhook, cron)
+  |
+  v
+Queue (database table, Redis, Inngest)
+  |
+  v
+Worker (Inngest function, serverless fn, dedicated process)
+  |
+  v
+Result Store (database, cache)
+  |
+  v
+Notification (SSE, polling, email)
+```
+
+**Queue implementation options for serverless environments:**
+
+| Option | Pros | Cons | Best For |
+|--------|------|------|----------|
+| **Inngest** | Step functions, retry, dashboard, concurrency control | Vendor dependency | Complex multi-step workflows |
+| **Database table** | No extra infra, transactional with app data | Polling required, no built-in retry | Simple job tracking |
+| **Vercel KV / Redis** | Fast, pub/sub capable | Separate data store, no built-in retry | High-throughput simple jobs |
+| **SQS / Cloud Tasks** | Managed, scalable, dead letter queues | Extra infrastructure, more complex | High-volume production systems |
+
+### Job State Machine
+
+Every background job follows this state lifecycle:
+
+```
+PENDING -> RUNNING -> COMPLETED
+                   -> FAILED -> RETRYING -> RUNNING
+                                         -> DEAD (max retries exceeded)
+           -> CANCELLED (user-initiated)
+```
+
+**Database schema pattern:**
+
+```sql
+CREATE TABLE background_jobs (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  org_id UUID NOT NULL REFERENCES organizations(id),
+  type VARCHAR(100) NOT NULL,           -- 'order-sync', 'report-generation'
+  status VARCHAR(20) NOT NULL DEFAULT 'pending',
+  priority INTEGER NOT NULL DEFAULT 5,  -- 1 = highest, 10 = lowest
+  payload JSONB NOT NULL DEFAULT '{}',
+  progress_pct SMALLINT DEFAULT 0,      -- 0-100
+  progress_message TEXT,                -- 'Processing order 1,234 of 5,000'
+  result JSONB,                         -- Output data on completion
+  error_message TEXT,                   -- Error details on failure
+  attempts INTEGER NOT NULL DEFAULT 0,
+  max_attempts INTEGER NOT NULL DEFAULT 3,
+  started_at TIMESTAMPTZ,
+  completed_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_jobs_status_priority ON background_jobs(status, priority)
+  WHERE status IN ('pending', 'running');
+```
+
+## Implementation Patterns
+
+### 1. Progress Tracking
+
+For any operation processing N items, track progress at regular intervals:
+
+```typescript
+async function processOrders(jobId: string, orders: Order[]) {
+  const total = orders.length;
+  for (let i = 0; i < total; i++) {
+    await processOrder(orders[i]);
+
+    // Update progress every 10 items or every 5 seconds (whichever comes first)
+    if (i % 10 === 0 || i === total - 1) {
+      await updateJobProgress(jobId, {
+        progress_pct: Math.round(((i + 1) / total) * 100),
+        progress_message: `Processing order ${i + 1} of ${total}`,
+      });
+    }
+  }
+}
+```
+
+**Progress reporting to the UI:**
+
+| Method | Latency | Complexity | Best For |
+|--------|---------|------------|----------|
+| **Polling** | 2-5s | Low | Simple progress bars, MVP |
+| **SSE** | Real-time | Medium | Dashboard live updates |
+| **WebSocket** | Real-time | High | Bidirectional control (pause/cancel) |
+
+### 2. Retry with Exponential Backoff
+
+```typescript
+function getRetryDelay(attempt: number): number {
+  // Base: 1s, 2s, 4s, 8s, 16s... capped at 5 minutes
+  const baseDelay = 1000;
+  const maxDelay = 5 * 60 * 1000;
+  const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+  // Add jitter to prevent thundering herd
+  return delay + Math.random() * 1000;
+}
+```
+
+**Retry decision matrix:**
+
+| Error Type | Retry? | Max Attempts | Example |
+|-----------|--------|--------------|---------|
+| Transient (network timeout, 503) | Yes | 3-5 | API rate limit, temporary outage |
+| Rate limit (429) | Yes, with backoff | 3 | Shopify API throttle |
+| Client error (400, 404) | No | 0 | Bad data, missing resource |
+| Auth error (401, 403) | No | 0 | Expired credentials |
+| Partial success | Resume from checkpoint | 3 | 3,000 of 5,000 orders processed |
+
+### 3. Checkpointing for Long Operations
+
+Operations processing thousands of items must checkpoint progress so retries resume from the last successful point, not restart from zero:
+
+```typescript
+async function syncAllOrders(jobId: string) {
+  // Resume from last checkpoint if retrying
+  const checkpoint = await getCheckpoint(jobId);
+  const cursor = checkpoint?.lastCursor || null;
+
+  let page = await fetchOrders({ after: cursor });
+  while (page.hasMore) {
+    await processOrderBatch(page.orders);
+    await saveCheckpoint(jobId, { lastCursor: page.cursor });
+    page = await fetchOrders({ after: page.cursor });
+  }
+}
+```
+
+### 4. Job Prioritization
+
+Not all background jobs are equal. A user-initiated export should complete before a scheduled overnight sync:
+
+| Priority | Level | Examples | Target Completion |
+|----------|-------|---------|-------------------|
+| 1 (Critical) | User-blocked | Data export, report generation user is waiting for | < 30 seconds |
+| 3 (High) | User-initiated | Bulk order sync after store connect | < 5 minutes |
+| 5 (Normal) | System | Scheduled daily sync, digest compilation | < 30 minutes |
+| 8 (Low) | Maintenance | Data cleanup, index rebuild | < 24 hours |
+
+### 5. Concurrency Control
+
+Prevent resource exhaustion by limiting concurrent job execution:
+
+```typescript
+// Inngest pattern
+export const orderSync = inngest.createFunction(
+  {
+    id: 'order-sync',
+    concurrency: {
+      limit: 5,           // Max 5 concurrent syncs across all orgs
+      key: 'event.data.orgId', // Max 1 sync per org
+    },
+  },
+  { event: 'orders/sync.requested' },
+  async ({ event, step }) => { /* ... */ }
+);
+```
+
+### 6. User-Facing Progress Communication
+
+| Job Duration | UX Pattern | Example |
+|-------------|------------|---------|
+| < 5s | Inline loading state | Button spinner |
+| 5-30s | Progress bar with percentage | "Syncing orders... 45%" |
+| 30s-5min | Progress bar + stage indicator | "Step 2 of 4: Calculating margins" |
+| > 5min | Background notification + email on complete | "We'll email you when your export is ready" |
+
+## Anti-Patterns
+
+1. **Long operations in request handlers.** Putting a 50,000-order sync in an API route handler. The request will timeout, the user gets an error, and partial work may corrupt data.
+
+2. **Fire-and-forget without tracking.** Dispatching a background job with no way to check its status. The user refreshes the page and has no idea if the operation completed, failed, or is still running.
+
+3. **Restarting from zero on retry.** A job that processed 4,000 of 5,000 orders before failing should resume from order 4,001, not restart. Without checkpointing, retries waste time and may cause duplicate processing.
+
+4. **No concurrency limits.** Allowing unlimited concurrent sync jobs. If 100 users trigger syncs simultaneously, the database connection pool is exhausted and all jobs fail.
+
+5. **Identical retry timing.** Retrying failed jobs at fixed intervals (e.g., every 5 seconds). When an external API is down, all retries hit simultaneously (thundering herd). Use exponential backoff with jitter.
+
+6. **Progress updates on every item.** Updating the progress database row for every single item in a 50,000-item batch. This creates 50,000 database writes. Update every N items or every T seconds.
+
+7. **Mixing job queue with business logic.** Putting order validation, margin calculation, and email sending in the job queue infrastructure code. The queue manages execution; business logic belongs in service functions.
+
+## Key Files
+
+When working in a project with background jobs:
+
+- Inngest function definitions — step functions with retry and concurrency
+- `background_jobs` table (if database-backed queue) — job tracking schema
+- API routes for job status polling — `GET /api/jobs/[id]/status`
+- SSE endpoints for real-time progress — `GET /api/jobs/[id]/progress`
+- Job type registry — mapping job types to handler functions
+
+## Verification
+
+After applying this skill, verify:
+- [ ] No request handler performs operations that could exceed 30 seconds
+- [ ] Every background job has a trackable status (pending/running/completed/failed)
+- [ ] Progress is reported to the user for operations exceeding 5 seconds
+- [ ] Retry logic uses exponential backoff with jitter
+- [ ] Long operations checkpoint progress for resumable retries
+- [ ] Concurrency limits prevent resource exhaustion
+- [ ] Failed jobs surface errors through monitoring, not silent swallowing
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Scheduling recurring jobs by time | `cron-scheduling` | Cron covers time-based triggers; this skill covers job execution patterns |
+| Inngest-specific event orchestration | `inngest-orchestration` | Inngest has its own patterns beyond generic job queues |
+| Data synchronization strategy | `data-sync` | Data sync covers the what (webhook, polling, reconciliation); this covers the how (queue, retry, progress) |
+| Real-time UI updates | `real-time-updates` | Real-time covers push-to-UI patterns; this covers backend job execution |
+
+---
+
+*Version 1.0.0 -- 2026-03-29. Initial creation.*

package/marketplace/skills/bounded-context-mapping/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: bounded-context-mapping
+description: "Use when drawing Domain-Driven Design boundaries: bounded contexts, context maps, ownership seams, upstream/downstream relationships, anti-corruption layers, shared kernels, and translation boundaries. Do NOT use for pre-DDD entity discovery (use `conceptual-modeling`), database schema design (use `data-modeling`), or HTTP endpoint design (use `api-design`)."
+license: MIT
+compatibility: "Portable DDD boundary-mapping discipline for monoliths, modular monoliths, services, event-driven systems, and agent workspaces."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"architecture/domain-boundaries\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-11\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-11\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"bounded context\\\\\\\",\\\\\\\"context map\\\\\\\",\\\\\\\"domain-driven design\\\\\\\",\\\\\\\"DDD boundary\\\\\\\",\\\\\\\"anti-corruption layer\\\\\\\",\\\\\\\"shared kernel\\\\\\\",\\\\\\\"upstream downstream\\\\\\\",\\\\\\\"conformist\\\\\\\",\\\\\\\"customer supplier\\\\\\\",\\\\\\\"domain boundary\\\\\\\"]\",\"examples\":\"[\\\\\\\"orders, fulfillment, payments, and support all use status differently - where should the bounded contexts be?\\\\\\\",\\\\\\\"map the upstream/downstream relationships before we split this module\\\\\\\",\\\\\\\"do we need an anti-corruption layer between our canonical order model and Shopify?\\\\\\\",\\\\\\\"which concepts belong to a shared kernel and which are context-local?\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"list entities, attributes, and cardinalities before any architecture decision\\\\\\\",\\\\\\\"create SQL tables, foreign keys, and indexes\\\\\\\",\\\\\\\"design REST routes and response envelopes\\\\\\\",\\\\\\\"write an ADR for the boundary decision after we already chose it\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"conceptual-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"conceptual-modeling discovers domain structure before DDD boundary ownership is assigned\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"data-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"data-modeling owns persistence structure after context boundaries inform ownership\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"api-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"api-design owns external endpoint shape; bounded-context-mapping owns domain ownership and translation boundaries\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"architecture-decision-records\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"architecture-decision-records records a chosen decision; bounded-context-mapping analyzes the boundary before the decision is recorded\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"event-storming\\\\\\\",\\\\\\\"system-interface-contracts\\\\\\\",\\\\\\\"conceptual-modeling\\\\\\\",\\\\\\\"architecture-decision-records\\\\\\\"],\\\\\\\"depends_on\\\\\\\":[\\\\\\\"conceptual-modeling\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"semantic-relations\\\\\\\",\\\\\\\"system-interface-contracts\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/bounded-context-mapping/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/bounded-context-mapping/SKILL.md
+---
+
+# Bounded Context Mapping
+
+## Coverage
+
+Map domain ownership boundaries and relationships between contexts. Covers bounded context naming, context maps, ubiquitous language separation, upstream/downstream relationships, shared kernel, conformist, customer/supplier, partnership, open host service, published language, anti-corruption layer, and boundary validation against real change scenarios.
+
+## Philosophy
+
+A bounded context is a language and ownership boundary, not a deployment unit. Splitting services without splitting language creates distributed coupling. Keeping one module while mixing incompatible meanings creates hidden domain bugs.
+
+The central question is: "Where does this word mean something different?" Those differences drive boundaries more reliably than folder layout, teams, or database tables.
+
+## Method
+
+1. Extract candidate terms and workflows from requirements, code, docs, and incidents.
+2. Mark terms whose meaning changes by actor or workflow.
+3. Group concepts that change together under the same business capability.
+4. Draw context boundaries around language consistency, not technical layers.
+5. Label relationships: upstream/downstream, partnership, shared kernel, conformist, or anti-corruption.
+6. Define translation points and ownership of canonical terms.
+7. Stress-test with change scenarios: who changes, who breaks, who must approve?
+
+## Verification
+
+- [ ] Each context has a coherent language that does not overload key terms
+- [ ] Cross-context communication uses explicit contracts or translation
+- [ ] Shared kernels are intentionally small and high-stability
+- [ ] Upstream/downstream power dynamics are named
+- [ ] Anti-corruption layers protect local language from external models
+- [ ] Boundary decisions were tested against real feature-change scenarios
+- [ ] No boundary is based only on folder, team, or database layout
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `conceptual-modeling` | You need to discover entities and relationships before assigning ownership boundaries. |
+| `data-modeling` | You need logical or physical data structures. |
+| `api-design` | You need HTTP route, request, response, status, or versioning design. |
+| `architecture-decision-records` | You need to record a decision that has already been made. |
+

package/marketplace/skills/cap-theorem-tradeoffs/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: cap-theorem-tradeoffs
+description: "Use when reasoning about the consistency-availability-partition-tolerance trade-off for distributed data systems: Brewer's CAP conjecture (2000), Gilbert & Lynch's 2002 formal proof, why P is not optional in any real distributed system, the CP-vs-AP dichotomy that follows, PACELC as the extension that names the latency-vs-consistency trade-off that exists even without partition, the relationship between CAP's C and ACID's C (different concepts with the same letter), and the choice procedure of naming what the system must guarantee under partition. Do NOT use for single-node transactional guarantees (use acid-fundamentals), choosing an isolation level (use transaction-isolation), the design of replication topologies (use replication-patterns), or sharding decisions (use sharding-strategy)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/data\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"CAP theorem\\\\\\\",\\\\\\\"Brewer\\\\\\\",\\\\\\\"Gilbert Lynch\\\\\\\",\\\\\\\"consistency availability partition\\\\\\\",\\\\\\\"CP system\\\\\\\",\\\\\\\"AP system\\\\\\\",\\\\\\\"PACELC\\\\\\\",\\\\\\\"eventual consistency\\\\\\\",\\\\\\\"linearizability\\\\\\\",\\\\\\\"distributed system\\\\\\\"]\",\"triggers\":\"[\\\\\\\"CAP theorem\\\\\\\",\\\\\\\"CP or AP\\\\\\\",\\\\\\\"what should we do on partition\\\\\\\",\\\\\\\"is this strongly consistent\\\\\\\",\\\\\\\"PACELC\\\\\\\"]\",\"examples\":\"[\\\\\\\"decide whether a new distributed service should be CP or AP given its workload\\\\\\\",\\\\\\\"explain why CAP's C and ACID's C are different concepts despite sharing the letter\\\\\\\",\\\\\\\"diagnose a system claiming 'CA' (consistency + availability without P) — likely confused, since P is not optional\\\\\\\",\\\\\\\"design the partition-mode behavior of a multi-region service\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"choose a transaction isolation level (use transaction-isolation)\\\\\\\",\\\\\\\"explain the four ACID properties (use acid-fundamentals)\\\\\\\",\\\\\\\"design the replication topology of a database (use replication-patterns)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"acid-fundamentals\\\\\\\",\\\\\\\"transaction-isolation\\\\\\\",\\\\\\\"replication-patterns\\\\\\\",\\\\\\\"sharding-strategy\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"acid-fundamentals\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"acid-fundamentals owns the single-system transactional frame; this skill owns the distributed-system frame. CAP's C (replica agreement) is not ACID's C (constraint satisfaction); conflating them is the most common misconception in this space.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"transaction-isolation\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"transaction-isolation owns single-cluster concurrency-correctness; this skill owns multi-replica consistency under network partition. The two layers can compose (a CP system may run at serializable isolation locally) but address different threats.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"replication-patterns\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"replication-patterns owns the design patterns for multi-replica systems (primary-replica, multi-primary, leaderless quorum); this skill owns the C/A/P trade-off that motivates choosing among them. The two compose: this is the theoretical frame; replication-patterns is the operational realization.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"sharding-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"sharding-strategy owns horizontal partitioning of data across nodes; this skill owns the C/A trade-off when those shards must coordinate or recover from network partition between them.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"acid-fundamentals\\\\\\\",\\\\\\\"replication-patterns\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"CAP is to a distributed database what the Heisenberg uncertainty principle is to physics — you cannot simultaneously have a fully consistent reading and a fully available reading when the network has partitioned, just as you cannot simultaneously measure a precise position and a precise momentum. The trade-off is not a limit of the engineering, it is a limit of the physics; pretending otherwise is the source of every 'CA' system that claims to defy CAP and chooses one side anyway on its first partition.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"CAP is the theorem (Brewer 2000 as a conjecture; Gilbert & Lynch 2002 as a formal proof) that, in a distributed data system, you cannot simultaneously guarantee all three of: Consistency (every read returns the most recent write or an error), Availability (every request receives a non-error response), Partition tolerance (the system continues despite arbitrary message loss between nodes). Since real-world networks can and do partition, P is not optional — the choice is between C and A *during a partition*. A CP system refuses to serve some requests during partition to preserve consistency; an AP system serves all requests but may return stale data. PACELC (Abadi 2010) extends CAP by naming the *Else* case: even without partition, the system must trade Latency against Consistency, because synchronous replication for strong consistency takes time. The discipline is choosing C-vs-A *intentionally per workload*, knowing that P is given by physics and that even outside partition, latency-vs-consistency is a continuous choice.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/cap-theorem-tradeoffs/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/cap-theorem-tradeoffs/SKILL.md
+---
+
+# CAP-Theorem Tradeoffs
+
+## Coverage
+
+The consistency-availability-partition-tolerance trade-off that physics imposes on distributed data systems. Covers Brewer's 2000 conjecture, Gilbert & Lynch's 2002 formal proof, why P is mandatory in real networks (the practical choice is CP vs AP, not "any two of three"), the PACELC extension (Abadi 2010) that names the latency-vs-consistency trade-off in the non-partition case, the CAP-C vs ACID-C confusion that is the most-common misconception in the space, the spectrum of consistency models from linearizability to eventual consistency, the four PACELC quadrants (PA/EL, PA/EC, PC/EL, PC/EC) and the systems that occupy each, and the partition-mode choice procedure.
+
+## Philosophy
+
+CAP is the frame that made distributed-systems design honest. Before Brewer's 2000 conjecture and Gilbert & Lynch's 2002 proof, the industry made contradictory claims about consistency, availability, and fault tolerance; after CAP, those claims have shape. Under partition — which physics guarantees will happen — you preserve consistency at the cost of availability, or availability at the cost of consistency.
+
+The discipline is making the choice *per workload* and *intentionally*. A banking core ledger is right to be CP. A shopping cart's session state is right to be AP. A multi-region content-delivery system is right to be AP with eventual consistency. A schema registry is right to be CP. The choice is the engineering team's responsibility; CAP names the trade-off; the design realizes the choice.
+
+PACELC is the frame that made CAP practical. Most systems spend the overwhelming majority of their time *not* partitioned; PACELC's E (else) case names the latency-vs-consistency trade-off in the common case, which is where most users' actual experience lives. A team that designs for CAP without PACELC has optimized for the rare event and ignored the daily one.
+
+## The CAP Theorem In One Diagram
+
+```
+                    During a network partition,
+                    pick at most TWO of:
+
+                    Consistency (C)
+                          /\
+                         /  \
+                        / CP \       Common: Spanner, etcd,
+                       /  ↓   \         MongoDB w/ majority,
+                      / refuse \             ZooKeeper
+                     /  some    \
+                    /  requests  \
+                   /              \
+                  /                \
+                 /                  \
+                /                    \
+               /         AP           \
+              /  serve all requests    \
+             /   accept stale reads     \    Common: Cassandra default,
+            /   diverge on writes        \      DynamoDB default,
+           /                              \              Riak
+          /                                \
+         /__________________________________\
+       Availability (A)        Partition tolerance (P)
+
+   "CA" is not a real choice — partitions happen.
+```
+
+## CAP-C vs ACID-C — A Worked Example
+
+A multi-region banking system with eventual consistency:
+
+| Scenario | CAP-C status | ACID-C status |
+|---|---|---|
+| Both replicas show balance = $500 (constraint: balance ≥ 0) | Consistent | Consistent |
+| Replica A shows $500, replica B shows $400 (constraint: balance ≥ 0) | INconsistent (CAP) | Consistent (no constraint violated) |
+| Both replicas show balance = -$100 (constraint: balance ≥ 0) | Consistent | INconsistent (constraint violated) |
+| Replica A shows balance = -$100, replica B shows $500 | INconsistent (CAP) | INconsistent (replica A violates) |
+
+The two C's measure different things. The system needs both to be operationally correct.
+
+## PACELC Quadrants
+
+| Quadrant | Partition behavior | Else (steady-state) behavior | Example systems |
+|---|---|---|---|
+| **PA/EL** | AP | Latency over consistency | Cassandra default, DynamoDB default, MongoDB default |
+| **PA/EC** | AP | Consistency over latency | Rare; often misconfiguration |
+| **PC/EL** | CP | Latency over consistency | Some real-world systems (mixed mode) |
+| **PC/EC** | CP | Consistency over latency | Spanner, Cosmos DB strong, MongoDB w/ majority-read |
+
+Choosing for the steady-state matters more than choosing for partition in most workloads.
+
+## The Choice Procedure
+
+1. **What does the system do if data goes stale by 10 seconds during a partition?** If the answer is "users see slightly old data; we reconcile later" — AP is viable. If the answer is "we lose money / corrupt records / fail an SLA" — CP is required.
+
+2. **What does the system do if 50% of requests fail for 60 seconds during a partition?** If "users retry; we lose some requests" — CP is viable. If "we churn users / lose orders / break business" — AP is required.
+
+3. **In the steady state, do we want low latency (EL) or strong consistency (EC)?** This is the dominant question for most workloads, since partition is rare. Strong consistency in the common case requires synchronous replication; eventual consistency in the common case allows asynchronous.
+
+4. **Does the workload need linearizability, or is causal consistency / read-your-writes enough?** Many workloads need weaker consistency than CAP's linearizability; the choice of consistency model affects the system's achievable throughput.
+
+5. **Is the system actually distributed?** Single-node or single-region tightly-coupled systems may not have CAP concerns at all. Avoid invoking CAP for systems where it doesn't apply.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] The team distinguishes CAP-C (replica agreement) from ACID-C (constraint satisfaction) in design discussions. Using "consistency" without qualifier produces confused decisions.
+- [ ] The system's CP-or-AP choice is explicit, documented, and tied to the workload's tolerance for stale data vs unavailability.
+- [ ] The PACELC quadrant is identified for the system. The steady-state latency-vs-consistency trade-off is treated as the dominant design decision, not as an afterthought to CAP.
+- [ ] Partition-mode behavior is tested, not assumed. The team has actually exercised partition (chaos engineering, network-partition simulation) and verified the system behaves as designed.
+- [ ] Reconciliation logic is in place for AP systems. Eventual consistency requires the team to have a defined convergence strategy (vector clocks, CRDTs, last-write-wins, anti-entropy) and to have tested it.
+- [ ] No system claims "CA" without challenge. CA is not a real choice; systems that claim it have not actually been tested under partition.
+- [ ] For tunable systems (Cassandra, DynamoDB), the per-operation consistency choice is intentional. The default settings are not assumed correct without verification per workload.
+- [ ] The consistency model is named (linearizability, causal, read-your-writes, eventual). "Strong consistency" without specification is imprecise.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Reasoning about single-node transactional guarantees | `acid-fundamentals` | acid-fundamentals owns single-system; this owns distributed |
+| Choosing an isolation level for concurrent transactions | `transaction-isolation` | transaction-isolation owns single-cluster concurrency |
+| Designing replication topology (primary-replica, multi-primary, etc.) | `replication-patterns` | replication-patterns owns the operational realization of CAP choices |
+| Sharding decisions for horizontal scaling | `sharding-strategy` | sharding owns horizontal partitioning; this owns the consistency frame across shards |
+| Tuning a query for performance | `query-optimization` | query-optimization owns retrieval performance |
+| Designing for high availability without distributed concerns | high-availability or reliability skills | HA on a single node is not a CAP concern |
+
+## Key Sources
+
+- Brewer, E. (2000). ["Towards Robust Distributed Systems" (PODC 2000 keynote)](https://www.cs.berkeley.edu/~brewer/cs262b-2004/PODC-keynote.pdf). The original CAP conjecture as Brewer presented it.
+- Gilbert, S., & Lynch, N. (2002). ["Brewer's Conjecture and the Feasibility of Consistent, Available, Partition-Tolerant Web Services"](https://www.glassbeam.com/sites/all/themes/glassbeam/images/blog/10.1.1.20.1495.pdf). *ACM SIGACT News*, 33(2), 51-59. The formal proof; the canonical academic reference.
+- Brewer, E. (2012). ["CAP Twelve Years Later: How the 'Rules' Have Changed"](https://ieeexplore.ieee.org/document/6133253). *IEEE Computer*, 45(2), 23-29. Brewer's retrospective; clarifies the misconceptions that grew up around the theorem.
+- Abadi, D. (2010). ["Problems with CAP, and Yahoo's little known NoSQL system"](http://dbmsmusings.blogspot.com/2010/04/problems-with-cap-and-yahoos-little.html) and (2012) ["Consistency Tradeoffs in Modern Distributed Database System Design: CAP is Only Part of the Story"](https://ieeexplore.ieee.org/document/6127847). *IEEE Computer*, 45(2), 37-42. The introduction of PACELC as the extended frame.
+- Kleppmann, M. (2017). *Designing Data-Intensive Applications*. O'Reilly. Chapter 9 (Consistency and Consensus) — modern practitioner treatment of CAP, PACELC, and the consistency model spectrum.
+- Bailis, P., Davidson, A., Fekete, A., Ghodsi, A., Hellerstein, J. M., & Stoica, I. (2014). ["Highly Available Transactions: Virtues and Limitations"](https://dl.acm.org/doi/10.14778/2732232.2732237). *VLDB 2014*. Modern academic treatment of the consistency models that sit between linearizability and eventual consistency.
+- Vogels, W. (2009). ["Eventually Consistent"](https://queue.acm.org/detail.cfm?id=1466448). *ACM Queue*, 6(6). The canonical practitioner essay on eventual consistency, written by Amazon's CTO.
+- Lipton, R. J., & Sandberg, J. S. (1988). ["PRAM: A Scalable Shared Memory"](https://www.cs.princeton.edu/research/techreps/TR-180-88). Princeton technical report. Early work on weak consistency models that inform CAP-era distributed databases.
+- Bailis, P., & Ghodsi, A. (2013). ["Eventual Consistency Today: Limitations, Extensions, and Beyond"](https://queue.acm.org/detail.cfm?id=2462076). *ACM Queue*. Modern survey of the eventual-consistency spectrum.