@skill-graph/cli 0.5.6

package/marketplace/skills/http-semantics/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: http-semantics
+description: "Use when designing or reviewing HTTP-based systems where method semantics, status codes, idempotency, safe methods, conditional requests, content negotiation, caching headers, or representation metadata are load-bearing. Covers the RFC 9110/9111/9112 contract layer below any specific framework. Do NOT use for API surface shape and route taxonomy (use api-design), for WebSocket or SSE bidirectional streams (use streaming-architecture skill when available), for vendor-specific webhook signing (use webhook-integration), or for transport-level concerns like TLS or QUIC (use platform-level documentation)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/protocol\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-15\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-15\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"HTTP semantics\\\\\\\",\\\\\\\"RFC 9110\\\\\\\",\\\\\\\"idempotent methods\\\\\\\",\\\\\\\"safe methods\\\\\\\",\\\\\\\"HTTP status codes\\\\\\\",\\\\\\\"conditional requests\\\\\\\",\\\\\\\"content negotiation\\\\\\\",\\\\\\\"cache control\\\\\\\",\\\\\\\"HTTP caching\\\\\\\",\\\\\\\"representation metadata\\\\\\\"]\",\"triggers\":\"[\\\\\\\"what status code should this return\\\\\\\",\\\\\\\"is this method idempotent\\\\\\\",\\\\\\\"RFC 9110\\\\\\\",\\\\\\\"conditional request\\\\\\\",\\\\\\\"cache control header\\\\\\\"]\",\"examples\":\"[\\\\\\\"decide whether bulk-update should be PUT or PATCH\\\\\\\",\\\\\\\"explain why this endpoint should return 409 instead of 400\\\\\\\",\\\\\\\"review whether this DELETE handler is truly idempotent\\\\\\\",\\\\\\\"design the Vary header for this endpoint that varies on Accept-Language\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"design the JSON shape of the request and response bodies (use api-design)\\\\\\\",\\\\\\\"verify a Stripe webhook signature (use webhook-integration)\\\\\\\",\\\\\\\"decide between WebSocket and SSE for live updates (use streaming-architecture)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"api-design\\\\\\\",\\\\\\\"webhook-integration\\\\\\\",\\\\\\\"system-interface-contracts\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"api-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"api-design owns the surface shape (routes, request/response schemas, pagination); http-semantics owns the protocol-level method/status/header contract that any HTTP API builds on.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"webhook-integration\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"webhook-integration owns inbound provider mechanics (signing, retry, vendor-specific topics); http-semantics owns vendor-neutral HTTP method and status semantics.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"system-interface-contracts\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"system-interface-contracts owns cross-boundary contract shapes regardless of transport; http-semantics is HTTP-specific.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"api-design\\\\\\\",\\\\\\\"code-review\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"HTTP semantics is to web APIs what the rules of grammar are to written language — the framework provides the dictionary (routes, handlers, middleware) but the grammar is non-negotiable, and a sentence that follows the dictionary while violating the grammar is technically intelligible but causes downstream tooling (CDNs, proxies, client libraries) to misinterpret it.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"HTTP semantics is the IETF-standardized contract layer (RFC 9110, 9111, 9112) that defines method meanings, status code families, request/response metadata, conditional requests, content negotiation, and caching — independent of any specific framework or language. It is the wire-level meaning that every HTTP API inherits.\\\\\\\",\\\\\\\"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/http-semantics/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/http-semantics/SKILL.md
+---
+
+# HTTP Semantics
+
+## Coverage
+
+The IETF contract layer for HTTP-based systems: method semantics (RFC 9110 § 9), status code families (§ 15), request/response metadata (§ 6-8, 12), conditional requests (§ 13), content negotiation (§ 12), and the caching model (RFC 9111). Applies to any system using HTTP as a transport: REST APIs, GraphQL endpoints, webhook receivers, browser fetches, proxy behavior, CDN configuration.
+
+## Philosophy
+
+HTTP is older and more carefully specified than most of the frameworks running on top of it. RFC 9110 is the consolidated semantics reference (June 2022, obsoletes RFC 7230-7235); it represents 25+ years of distilled experience from browsers, proxies, CDNs, and load balancers. Most "weird HTTP behavior" stories come down to a framework default that doesn't match the spec.
+
+The discipline is to ground HTTP decisions in the RFC, not the framework. When the framework default conflicts with the spec, the spec wins for portability: anything outside your codebase (a CDN, a corporate proxy, a client library in a different language) will follow the RFC, not your framework's documentation.
+
+## Method Semantics (RFC 9110 § 9)
+
+| Method | Safe | Idempotent | Cacheable | Typical use |
+|---|---|---|---|---|
+| GET | yes | yes | yes | Retrieve a representation |
+| HEAD | yes | yes | yes | Retrieve metadata only |
+| POST | no | no | only with explicit freshness | Submit data; catch-all for non-fitting operations |
+| PUT | no | yes | no | Replace target resource with payload |
+| DELETE | no | yes | no | Remove target resource |
+| PATCH | no | not by default | no | Apply a partial modification (RFC 5789) |
+| OPTIONS | yes | yes | no | Discover capabilities |
+| TRACE | yes | yes | no | Loop-back diagnostic |
+| CONNECT | no | no | no | Establish a tunnel |
+
+**Idempotency rule (RFC 9110 § 9.2.2):** repeated requests have the same effect on resource state as a single request. The response code may differ across invocations (204 → 404 for DELETE); idempotency is about the post-condition, not the post-response.
+
+**Safe-method rule (§ 9.2.1):** safe methods do not modify resource state. Servers MUST NOT depend on side effects of safe methods (e.g., logging counters that affect business logic are not "side effects" in the sense of the spec).
+
+## Status Code Selection
+
+Use the **first digit** as the contract; use the **last two digits** as refinement. A proxy that doesn't understand a specific 4xx will treat it as a generic 4xx.
+
+| Family | When to use | Common errors |
+|---|---|---|
+| 2xx | Request fulfilled. 200 default; 201 for creation with Location header; 202 for async accepted; 204 for success with no body | Returning 200 with `{ error: ... }` body — wrong family |
+| 3xx | Client must take further action. 301/308 for permanent; 302/307 for temporary; 303 after a POST to direct to the result; 304 for cache validation hit | Returning 302 to authentication when 401 is correct |
+| 4xx | Client error. 400 for malformed request; 401 for missing/invalid credentials; 403 for valid credentials but insufficient authorization; 404 for not-found (or hidden); 405 for wrong method on valid target; 409 for state conflict; 410 for permanently gone; 412 for failed precondition; 415 for unsupported media type; 422 for valid syntax but unprocessable; 428 for required precondition; 429 for rate limit | Using 400 for everything; conflating 401 (who) with 403 (what allowed) |
+| 5xx | Server error. 500 default; 501 for not-implemented method; 502 for upstream bad response; 503 for temporary unavailability (with Retry-After); 504 for upstream timeout | Returning 500 when the cause is client input (should be 4xx) |
+
+## Conditional Requests (RFC 9110 § 13)
+
+Use conditional requests to make non-idempotent operations safe under retry and to enable cache validation.
+
+| Header | Pairs with | Semantic |
+|---|---|---|
+| If-Match | ETag | "Only apply if the resource still matches this version" — protects against lost-update on PUT/PATCH/DELETE |
+| If-None-Match | ETag | "Apply only if the resource has changed" — primary cache validation |
+| If-Modified-Since | Last-Modified | Date-based cache validation (lower precision than ETag) |
+| If-Unmodified-Since | Last-Modified | Date-based lost-update protection |
+
+A non-idempotent operation made conditional with If-Match becomes safe to retry: the server applies it once if the precondition holds, and returns 412 Precondition Failed every subsequent time.
+
+## Caching (RFC 9111)
+
+The freshness model has three orthogonal questions:
+
+1. **Is this response cacheable at all?** Default yes for safe + 2xx + no explicit no-store. Cache-Control: no-store opts out.
+2. **For how long is it fresh?** Cache-Control: max-age=N (seconds) is authoritative. Expires is the older alternative.
+3. **What request headers participate in cache-key construction?** Vary lists them. A response without Vary on an endpoint that varies by Accept-Language will be served to all languages from one cached entry.
+
+**Cache-Control directive cheat sheet:**
+
+| Directive | Where | Meaning |
+|---|---|---|
+| max-age=N | response | Fresh for N seconds |
+| s-maxage=N | response | Fresh in shared caches for N seconds (overrides max-age) |
+| no-cache | response | Must revalidate before reuse (still cacheable) |
+| no-store | response | Do not cache at all |
+| private | response | Cacheable only in single-user caches (browser, not CDN) |
+| public | response | Cacheable in shared caches even if normally not |
+| must-revalidate | response | Stale entries must be revalidated, not served |
+| stale-while-revalidate=N | response | Serve stale for N seconds while async revalidating |
+| stale-if-error=N | response | Serve stale for N seconds on origin error |
+
+## Content Negotiation (RFC 9110 § 12)
+
+Server-driven negotiation uses request Accept-* headers and response Vary header. Pattern:
+
+```
+Request:
+  Accept: application/json, text/html;q=0.9
+  Accept-Language: en, fr;q=0.8
+
+Response:
+  Content-Type: application/json
+  Content-Language: en
+  Vary: Accept, Accept-Language
+```
+
+The Vary response header is the contract for downstream caches: it lists the request headers the cache must match on. Forgetting Vary causes language-A users to see language-B responses cached by a CDN.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Method choice (GET/POST/PUT/PATCH/DELETE) is justified by the operation's safe/idempotent properties, not by convention.
+- [ ] Status codes use the correct family; first digit semantically matches the outcome.
+- [ ] Non-idempotent operations that need retry safety use If-Match + ETag (or an idempotency-key pattern).
+- [ ] Cached responses include Cache-Control with explicit max-age or no-store.
+- [ ] Responses that vary on request headers declare Vary correctly.
+- [ ] 401 is used for "who are you" failures; 403 for "you can't do that" failures; the two are not interchangeable.
+- [ ] DELETE handlers are spec-idempotent: server state is the same after one invocation as after many, regardless of the response code returned.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Designing the JSON request/response shape | `api-design` | api-design owns the surface; this skill owns the protocol layer below it |
+| Verifying a vendor webhook signature | `webhook-integration` | webhook-integration owns inbound provider mechanics |
+| Designing a WebSocket or SSE stream | `real-time-updates` or a streaming-architecture skill | Those skills own bidirectional / streaming patterns above HTTP |
+| Designing the cross-boundary contract regardless of transport | `system-interface-contracts` | system-interface-contracts owns the contract layer that may or may not be HTTP |
+| Designing a GraphQL schema or resolver chain | `api-design` or a graphql skill | This skill applies to HTTP semantics under any payload format, but schema design is api-design's surface |
+| Configuring TLS, HTTP/2, HTTP/3 transport | platform documentation | Transport syntax (RFC 9112/9113/9114) is below the semantics layer |
+
+## Key Sources
+
+- Fielding, R., & Reschke, J. (Eds.) (2022). [RFC 9110: HTTP Semantics](https://datatracker.ietf.org/doc/html/rfc9110). IETF. The consolidated semantics reference; obsoletes RFC 7230-7235.
+- Fielding, R., Nottingham, M., & Reschke, J. (Eds.) (2022). [RFC 9111: HTTP Caching](https://datatracker.ietf.org/doc/html/rfc9111). IETF. The caching model.
+- Fielding, R., Nottingham, M., & Reschke, J. (Eds.) (2022). [RFC 9112: HTTP/1.1](https://datatracker.ietf.org/doc/html/rfc9112). IETF. The HTTP/1.1 wire syntax.
+- Dusseault, L., & Snell, J. (Eds.) (2010). [RFC 5789: PATCH Method for HTTP](https://datatracker.ietf.org/doc/html/rfc5789). IETF. The PATCH method specification.
+- Fielding, R. T. (2000). [Architectural Styles and the Design of Network-based Software Architectures](https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm). Ph.D. dissertation, UC Irvine. The original REST definition.
+- MDN Web Docs. [HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP). Practical reference complementing the RFCs.

package/marketplace/skills/ideation/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: ideation
+description: "Use when generating a wide range of solution concepts before converging on a direction, running structured idea-generation sessions, breaking out of solution fixation, or moving from divergent to convergent selection with explicit criteria. Do NOT use for collaborative engineering domain discovery (event-storming), solo deep technical design, or making final go/no-go investment decisions — those require different methods."
+license: CC-BY-4.0
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"design\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-12\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-12\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"crazy 8s\\\\\\\",\\\\\\\"brainstorming\\\\\\\",\\\\\\\"SCAMPER\\\\\\\",\\\\\\\"worst possible idea\\\\\\\",\\\\\\\"headlines from the future\\\\\\\",\\\\\\\"dot voting\\\\\\\",\\\\\\\"NUF test\\\\\\\",\\\\\\\"divergent thinking\\\\\\\",\\\\\\\"convergent thinking\\\\\\\",\\\\\\\"ideation workshop\\\\\\\",\\\\\\\"impact effort matrix\\\\\\\",\\\\\\\"weighted decision matrix\\\\\\\",\\\\\\\"suspended judgment\\\\\\\",\\\\\\\"design sprint sketch\\\\\\\"]\",\"triggers\":\"[\\\\\\\"brainstorm\\\\\\\",\\\\\\\"ideation session\\\\\\\",\\\\\\\"crazy 8s\\\\\\\",\\\\\\\"generate concepts\\\\\\\",\\\\\\\"narrow down ideas\\\\\\\"]\",\"examples\":\"[\\\\\\\"Run a crazy-8s round on this how-might-we statement and produce a divergent set.\\\\\\\",\\\\\\\"Apply SCAMPER to this existing feature to generate variant concepts.\\\\\\\",\\\\\\\"Use dot voting and an impact/effort matrix to converge on three concepts to prototype.\\\\\\\",\\\\\\\"Help me set up a worst-possible-idea round to break the team out of solution fixation.\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"Decide whether to invest in this feature for the next quarter.\\\\\\\",\\\\\\\"Model the bounded contexts for the order-fulfillment domain.\\\\\\\",\\\\\\\"Write the production code for the selected concept.\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"problem-framing\\\\\\\",\\\\\\\"prototyping\\\\\\\",\\\\\\\"design-thinking\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"event-storming\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"event-storming is a collaborative engineering discovery practice for mapping domain events and aggregates. ideation generates user-facing concept variants and applies divergent/convergent selection — different purpose, different output, different participants.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"conceptual-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"conceptual-modeling produces a single best model of a domain. ideation deliberately produces many alternatives before selecting — opposite epistemic stance.\\\\\\\"}]}\",\"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/ideation/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/ideation/SKILL.md
+---
+
+# Ideation
+
+## Coverage
+Ideation covers the techniques that produce many concept variants in response to a well-framed problem, then converge on a subset worth pursuing. The practice has two distinct halves and treats them as separable activities. **Divergent techniques** include **Crazy 8s** (eight sketches in eight minutes, popularized by Google Ventures' Design Sprint), **brainwriting** (silent written generation that bypasses dominant voices), **SCAMPER** (Substitute / Combine / Adapt / Modify / Put-to-another-use / Eliminate / Reverse — Bob Eberle's adaptation of Alex Osborn's checklist), **worst-possible-idea** (deliberately bad concepts to disinhibit and reveal hidden assumptions), **headlines-from-the-future** (write the press release for the launched product), and **analogous inspiration** (how do other domains solve adjacent problems).
+
+**Convergent techniques** include **dot voting** (each participant gets N stickers to place on concepts they would invest in), the **NUF test** (Is it New, Useful, Feasible?), **impact / effort 2×2** plotting, **weighted decision matrices** for multi-criteria selection, and **assumption-testing prioritization** (which concepts, if true, would teach the team the most). Convergent methods make the selection criteria explicit before voting begins, so the choice is defensible rather than political.
+
+The skill includes the **facilitation mechanics** that keep the two halves separate: enforcing silence during divergent rounds so no idea is judged before it lands, time-boxing strictly so quantity is prioritized over polish, withholding feedback ("yes-and" rather than "yes-but"), and only opening evaluative discussion in the convergent phase. This separation is the single most-cited determinant of brainstorming productivity in the literature (going back to Osborn 1953, with the criticism / refinements from Diehl & Stroebe and others incorporated via brainwriting variants).
+
+## Philosophy
+Ideation is built on a counterintuitive claim: that quantity precedes quality. The case is empirical and structural — judging an idea costs cognitive effort, and judgment running in parallel with generation suppresses generation. Teams that judge as they ideate produce fewer ideas, and the ideas they produce skew toward the safe middle of the distribution. By splitting the modes, divergent rounds produce a wider range, and convergent rounds can then prune intelligently because the field is large enough that pruning is meaningful.
+
+The discipline is sceptical of "good enough" early ideas. The first three ideas a team generates are usually the obvious ones — the ones any competitor has also considered. The interesting ideas live in the second half of a forced-quantity round, where the obvious is exhausted and the team is pushed into less-trodden territory. Worst-possible-idea exercises serve the same function from the other direction: by deliberately violating norms, they expose which norms were holding the design back.
+
+## Verification
+- A divergent round produced at least 20 concept variants (or 8 per participant in a Crazy 8s round) before any convergence began.
+- The selection criteria for convergence were named in writing *before* voting started — not retrofitted to justify the popular choice.
+- The selected concepts are materially different from each other; if the three "winners" are variations on the same idea, the divergent round failed to spread.
+- At least one selected concept is uncomfortable or unfamiliar to the team — pure consensus often signals the convergent phase compressed the range.
+- The team can articulate, for each selected concept, what specific question it would help answer in the next stage (prototyping or testing).
+- Time-boxes were enforced; the session did not drift into open-ended discussion that re-merged the divergent and convergent modes.
+
+## Do NOT Use When
+- The problem has not been framed — return to **problem-framing** first; ideating on a fuzzy brief produces a fuzzy concept set.
+- The team needs to commit to a single direction with budget implications, not just narrow a creative field — pair ideation with a separate investment-decision process.
+- The task is modeling engineering domain events and aggregates — use **event-storming**.
+- The output should be a single best architecture or model — use **conceptual-modeling**, which seeks correctness rather than variety.
+- The decision is between two well-understood, already-specified options — a simple comparison is sufficient; full ideation is overhead.
+- The next step is to make the chosen concept real and learn from it — move to **prototyping**.

package/marketplace/skills/indexing-strategy/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: indexing-strategy
+description: "Use when designing indexes for a relational or NoSQL database: the index-as-precomputed-search-structure mental model, the catalog of structures (B-tree, hash, bitmap, GIN/GiST, BRIN, LSM-tree), the matching of structures to access patterns (equality, range, prefix, contains, geospatial), composite indexes and column order, covering indexes, partial / filtered indexes, the maintenance cost of every index (write amplification, storage, lock impact), and the rules for when to add an index, when not to, and when to drop one. Do NOT use for tuning a slow query (use query-optimization), choosing isolation levels (use transaction-isolation), schema design (use data-modeling), or distributed-data partitioning (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\":\"[\\\\\\\"indexing\\\\\\\",\\\\\\\"index\\\\\\\",\\\\\\\"B-tree\\\\\\\",\\\\\\\"hash index\\\\\\\",\\\\\\\"bitmap index\\\\\\\",\\\\\\\"GIN\\\\\\\",\\\\\\\"GiST\\\\\\\",\\\\\\\"BRIN\\\\\\\",\\\\\\\"LSM\\\\\\\",\\\\\\\"composite index\\\\\\\",\\\\\\\"covering index\\\\\\\",\\\\\\\"partial index\\\\\\\",\\\\\\\"filtered index\\\\\\\",\\\\\\\"index selectivity\\\\\\\"]\",\"triggers\":\"[\\\\\\\"should I add an index\\\\\\\",\\\\\\\"which columns to index\\\\\\\",\\\\\\\"B-tree vs hash\\\\\\\",\\\\\\\"is this index being used\\\\\\\",\\\\\\\"composite index column order\\\\\\\"]\",\"examples\":\"[\\\\\\\"design indexes for a table with high-volume reads on user_id and date-range queries\\\\\\\",\\\\\\\"decide between a B-tree index and a partial index for a small subset of rows\\\\\\\",\\\\\\\"diagnose a query that ignores an existing index — likely a selectivity or type-coercion issue\\\\\\\",\\\\\\\"explain why adding a sixth index to a write-heavy table is usually wrong\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"diagnose why this specific query is slow (use query-optimization)\\\\\\\",\\\\\\\"choose a database schema (use data-modeling)\\\\\\\",\\\\\\\"decide how to partition data across nodes (use sharding-strategy)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"query-optimization\\\\\\\",\\\\\\\"data-modeling\\\\\\\",\\\\\\\"schema-evolution\\\\\\\",\\\\\\\"transaction-isolation\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"query-optimization\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"query-optimization owns the diagnosis and tuning of specific slow queries; this skill owns the *design* of which indexes the database has. The two compose: query-optimization diagnoses; this skill is one of the responses.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"data-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"data-modeling owns the schema and access patterns; this skill owns the auxiliary search structures that make access patterns efficient. The schema determines what indexes can exist; the access patterns determine which should.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"schema-evolution\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"schema-evolution owns how the database changes shape over time; this skill owns the indexes that must change with it. Adding or removing an index is itself a schema change.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"query-optimization\\\\\\\",\\\\\\\"data-modeling\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"An index is to a database what the back-of-the-book index is to a reference manual — you do not flip through every page to find every mention of 'Postgres'; you go to the I section, find the page numbers, and jump. Adding an index for every word in the book is technically possible and obviously wrong; the printer would still have to update every index every time the text changed, and the book would now spend most of its pages on indexes rather than content.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Indexing strategy is the discipline of designing auxiliary data structures that let the database find rows quickly without scanning every row. An index is a precomputed lookup structure (B-tree, hash, bitmap, inverted index, LSM-tree, BRIN, GiST, GIN) that maps one or more column values to the rows containing those values. Every index speeds up some queries (those whose WHERE / JOIN / ORDER BY clauses match the index's structure) and slows down every write (the index must be updated on every INSERT, UPDATE that touches indexed columns, and DELETE). The strategic question is not 'which columns deserve an index' considered in isolation; it is the *whole-database* trade-off between read speed and write cost, given the actual access patterns the workload produces.\\\\\\\",\\\\\\\"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/indexing-strategy/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/indexing-strategy/SKILL.md
+---
+
+# Indexing Strategy
+
+## Coverage
+
+The discipline of designing auxiliary data structures that let the database find rows quickly without scanning every row. Covers the structure catalog (B-tree, hash, bitmap, GIN, GiST, BRIN, LSM-tree) and the access patterns each matches, composite indexes and column-order rules, covering indexes and INCLUDE clauses, partial / filtered indexes, expression indexes, the maintenance cost of every index (storage, write amplification, lock impact, planner overhead), and the strategic question of treating the index set as an optimized portfolio rather than a per-column checklist.
+
+## Philosophy
+
+Indexes are a write/read trade. Every index speeds up some queries and slows down every write. The strategic discipline is not "which columns deserve an index" considered in isolation; it is the whole-database trade-off between read speed and write cost, given the workload's actual access patterns.
+
+The wrong default is "add an index for every column ever filtered on." The wrong response to a slow query is always "add an index." The right discipline is to count the queries that would benefit, count the writes that would pay the cost, and check whether the index is actually used by the planner before keeping it.
+
+The structure catalog matters. A B-tree is the right default for the vast majority of access patterns. Specialized structures (GIN for arrays/JSON/full-text, BRIN for naturally-ordered large columns, R-tree/GiST for geospatial) serve specific patterns far better than B-tree. Knowing which structure matches which pattern is the design vocabulary.
+
+## Structure → Access Pattern Matrix
+
+| Pattern | Best structure | Why |
+|---|---|---|
+| Equality lookup (`col = x`) | B-tree, hash | Both serve; B-tree is more flexible |
+| Range (`col BETWEEN x AND y`) | B-tree | Hash doesn't support range |
+| Prefix match (`col LIKE 'foo%'`) | B-tree | Range over a prefix |
+| Contains (`'foo' = ANY(col)`, JSON contains) | GIN | Inverted index for many-keys-per-row |
+| Full-text search | GIN or specialized (Elasticsearch) | Inverted index |
+| Geospatial proximity | GiST / R-tree / PostGIS | Spatial structures |
+| Range types / `&&` overlap | GiST | Range-aware structure |
+| Naturally-ordered append-only (timestamps) | BRIN | Small summary index |
+| Write-optimized point-write workload | LSM-tree | Write throughput primary |
+| Low-cardinality AND-combination (data warehouse) | Bitmap | AND across columns efficient |
+| Low-cardinality high-update workload | None (use partial or skip) | Bitmap updates poorly |
+
+## Composite Index Column Order Rule
+
+For an index on (A, B, C), the index serves queries with leading-column prefixes:
+
+| Query | Uses index? |
+|---|---|
+| `WHERE A = x` | Yes |
+| `WHERE A = x AND B = y` | Yes |
+| `WHERE A = x AND B = y AND C = z` | Yes |
+| `WHERE A = x AND C = z` | Yes (A prefix), but skips B in scan |
+| `WHERE B = y` | No (no leading A) |
+| `WHERE C = z` | No |
+| `ORDER BY A, B, C` | Yes (sort avoided) |
+| `ORDER BY A DESC, B DESC` | Yes (Postgres can reverse scan) |
+| `ORDER BY B` | No |
+
+Column order rule: put the most-selective and most-filtered column first.
+
+## When To Add, Drop, Never Add
+
+| Situation | Decision |
+|---|---|
+| Query is frequent, slow, and matches no current index | Add an index |
+| Query is rare (monthly report); table is otherwise hot | Don't add — query can scan |
+| Index exists but is reported as unused by `pg_stat_user_indexes` for 3+ months | Drop it |
+| Column has low selectivity (boolean, status enum with two common values) | Use a partial index on the rarer value, or skip |
+| Column is part of a composite key with leading columns covered by another index | Skip; the existing index serves |
+| Column is a foreign key, joined frequently | Add an index (FK joins are common; the planner uses it) |
+| Column is a foreign key, never joined | Optional; some teams add for CASCADE operations |
+| Write-heavy table (audit log, event stream) | Minimal indexes — primary key only, occasionally one more |
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Index structure matches the access pattern (B-tree for ordered queries; GIN for contains; BRIN for naturally-ordered large columns; etc.). Default B-tree everywhere is not necessarily correct.
+- [ ] Composite indexes have intentional column order. Most-selective and most-filtered column first.
+- [ ] Index usage is monitored (`pg_stat_user_indexes` for Postgres, equivalents elsewhere). Unused indexes are dropped on a regular cadence.
+- [ ] Write-heavy tables have minimal indexes. The number of indexes is justified against the table's write rate.
+- [ ] Partial indexes are used where access patterns target a small subset of rows (e.g., `WHERE status = 'pending'`).
+- [ ] Covering indexes (INCLUDE clause or composite with projected columns) are used for read-hot queries where row fetch is the bottleneck.
+- [ ] EXPLAIN ANALYZE is used to verify the planner uses the added index. An index that exists but is ignored by the planner is pure cost.
+- [ ] Index creation in production uses CONCURRENTLY (Postgres) or equivalent non-blocking patterns. Production deployment is part of the design.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Diagnosing a specific slow query | `query-optimization` | query-optimization owns diagnosis; this skill is one of the responses |
+| Designing the table schema and entity relationships | `data-modeling` | data-modeling owns design; this skill owns the auxiliary structures |
+| Reasoning about how the schema changes over time | `schema-evolution` | schema-evolution owns versioning; this skill owns one type of schema element |
+| Choosing an isolation level | `transaction-isolation` | transaction-isolation owns concurrency; this skill owns retrieval |
+| Reasoning about horizontal partitioning | `sharding-strategy` | sharding owns partition; this owns within-shard retrieval |
+| Tuning OS / storage-layer performance | infrastructure / storage skills | storage I/O is a layer below indexing |
+
+## Key Sources
+
+- Winand, M. (2012, ongoing). [*Use The Index, Luke!*](https://use-the-index-luke.com/). The canonical practitioner guide to SQL indexing, with deep treatment of B-tree internals, composite indexes, and the planner's interaction with indexes.
+- PostgreSQL Global Development Group. ["PostgreSQL Documentation — Indexes"](https://www.postgresql.org/docs/current/indexes.html). Reference for Postgres's full index-type catalog including GIN, GiST, BRIN, hash, and the planner's interaction with each.
+- Petrov, A. (2019). *Database Internals: A Deep Dive into How Distributed Data Systems Work*. O'Reilly. Chapters on B-tree variants, LSM-trees, and storage structures; the modern reference on the structures underneath indexes.
+- Ramakrishnan, R., & Gehrke, J. (2002, 3rd ed.). *Database Management Systems*. McGraw-Hill. Classic textbook treatment of indexing structures, query execution, and the planner.
+- Garcia-Molina, H., Ullman, J. D., & Widom, J. (2008, 2nd ed.). *Database Systems: The Complete Book*. Pearson. Comprehensive reference on indexing theory and practice.
+- Microsoft. ["SQL Server Index Architecture and Design Guide"](https://learn.microsoft.com/en-us/sql/relational-databases/sql-server-index-design-guide). Reference for SQL Server's index design including covering, filtered, and columnstore indexes.
+- Oracle. ["Oracle Database Concepts — Indexes and Index-Organized Tables"](https://docs.oracle.com/database/121/CNCPT/indexiot.htm). Reference for Oracle's index structures including bitmap, function-based, and index-organized tables.
+- Lehman, P. L., & Yao, S. B. (1981). ["Efficient Locking for Concurrent Operations on B-Trees"](https://dl.acm.org/doi/10.1145/319628.319663). *ACM TODS*, 6(4). Foundational paper on concurrent B-tree operations; basis of modern B-tree implementations.
+- O'Neil, P., Cheng, E., Gawlick, D., & O'Neil, E. (1996). ["The Log-Structured Merge-Tree (LSM-tree)"](https://dl.acm.org/doi/10.1145/240858.240861). *Acta Informatica*. The foundational paper on LSM-trees, the structure underlying Cassandra, RocksDB, and many modern write-optimized stores.

package/marketplace/skills/information-architecture/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: information-architecture
+description: "Use when structuring information for findability: navigation, page hierarchy, docs architecture, sitemap shape, labeling systems, wayfinding, and content grouping. Do NOT use for formal category-governance work (use `taxonomy-design`), responsive page composition (use `layout-composition`), component/token architecture (use `design-system-architecture`), or sentence-level UI text (use `microcopy`)."
+license: MIT
+compatibility: "Portable IA guidance for apps, documentation, dashboards, admin tools, and skill libraries."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"design\",\"domain\":\"design/information-architecture\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-11\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-11\\\\\\\"}\",\"eval_artifacts\":\"present\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"information architecture\\\\\\\",\\\\\\\"navigation structure\\\\\\\",\\\\\\\"sitemap\\\\\\\",\\\\\\\"wayfinding\\\\\\\",\\\\\\\"page hierarchy\\\\\\\",\\\\\\\"docs architecture\\\\\\\",\\\\\\\"labeling system\\\\\\\",\\\\\\\"content grouping\\\\\\\",\\\\\\\"findability\\\\\\\",\\\\\\\"content model\\\\\\\"]\",\"examples\":\"[\\\\\\\"our docs have good content but nobody can find the setup instructions - how should the IA change?\\\\\\\",\\\\\\\"design the navigation and page hierarchy for this admin app\\\\\\\",\\\\\\\"these dashboard sections overlap and users do not know where to look first\\\\\\\",\\\\\\\"should this be a top-level nav item, a tab, a filter, or a page section?\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"make the category taxonomy and assignment rules for this skill library\\\\\\\",\\\\\\\"define design tokens, component APIs, and theming rules\\\\\\\",\\\\\\\"rewrite this tooltip and empty-state copy\\\\\\\",\\\\\\\"audit keyboard accessibility and ARIA semantics\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"taxonomy-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"taxonomy-design governs classification systems; information-architecture arranges user-facing information paths\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"design-system-architecture\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"design-system-architecture owns component and token systems; information-architecture owns navigation and content structure\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"layout-composition\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"layout-composition owns structure inside a page or screen; information-architecture owns cross-page organization and wayfinding\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"microcopy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"microcopy owns sentence-level UI text; information-architecture owns placement and hierarchy\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"a11y\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"a11y owns accessibility compliance; information-architecture can create structures that a11y later verifies\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"taxonomy-design\\\\\\\",\\\\\\\"task-analysis\\\\\\\",\\\\\\\"design-system-architecture\\\\\\\",\\\\\\\"layout-composition\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"task-analysis\\\\\\\",\\\\\\\"a11y\\\\\\\"]}\",\"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/information-architecture/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/information-architecture/SKILL.md
+---
+
+# Information Architecture
+
+## Coverage
+
+Structure information so users and agents can find, understand, and move through it. Covers navigation, sitemaps, hierarchy, page grouping, labeling systems, docs structure, cross-links, wayfinding cues, content models, and IA validation through real user tasks.
+
+## Philosophy
+
+Information architecture is not decoration. It is the contract between a user's goal and the system's structure. If the IA is wrong, good content and good components still feel confusing because the path to them is unclear.
+
+Good IA starts from tasks, then chooses structure. Do not promote every important thing to top-level navigation. Do not bury frequently used workflows under technically accurate but user-invisible categories.
+
+## Method
+
+1. Name the top user tasks and entry points.
+2. Inventory current content or screens.
+3. Group by user goal first, implementation detail second.
+4. Decide structure: nav item, page, tab, section, filter, or cross-link.
+5. Apply label discipline: recognizable user language, stable nouns, no internal jargon.
+6. Add wayfinding: current location, sibling options, next action, and escape path.
+7. Test against task scenarios and no-prior-knowledge discovery.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/information-architecture.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/information-architecture.json). The checklist below is the authoring gate for findability and structure decisions; the eval file is the grader surface.
+
+## Verification
+
+- [ ] Top tasks have obvious entry points
+- [ ] Labels use user language rather than implementation terms
+- [ ] Navigation levels are limited and predictable
+- [ ] Similar content has one canonical home plus cross-links where needed
+- [ ] Users can recover from a wrong turn without restarting
+- [ ] Empty states and low-data states still preserve structure
+- [ ] IA was tested against real task prompts
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `taxonomy-design` | You need classification governance, facets, or category assignment rules. |
+| `layout-composition` | You need responsive section order, grid/flex structure, or page-level scan pattern. |
+| `design-system-architecture` | You need token, theme, component API, or design-system governance. |
+| `microcopy` | The structure is settled and you need wording for labels, errors, or empty states. |
+| `a11y` | The primary task is accessibility compliance or assistive-technology behavior. |

package/marketplace/skills/integration-test-design/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: integration-test-design
+description: "Use when designing tests that verify the interaction between two or more units of a system — modules, services, layers, processes: the scope-and-boundary primitives that distinguish integration from unit and e2e tests, the test-pyramid (Cohn 2009) and test-trophy (Dodds) frameworks for how much integration testing belongs in the suite, the real-vs-faked-collaborator decision per dependency, the test-data lifecycle (per-test setup, transaction rollback, container reset), the difference between sociable-unit tests, integration tests, and contract tests, and the failure modes (over-broad scope that mimics e2e, over-narrow scope that mimics unit, shared mutable state that produces flakes). Do NOT use for testing one unit in isolation (use testing-strategy + test-doubles-design), full user-journey testing (use e2e-test-design), consumer-driven contract verification (use contract-testing), or test-suite quality measurement (use mutation-testing)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"quality\",\"domain\":\"quality/testing\",\"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\":\"[\\\\\\\"integration test\\\\\\\",\\\\\\\"integration testing\\\\\\\",\\\\\\\"test pyramid\\\\\\\",\\\\\\\"test trophy\\\\\\\",\\\\\\\"sociable test\\\\\\\",\\\\\\\"test data setup\\\\\\\",\\\\\\\"test transaction rollback\\\\\\\",\\\\\\\"test containers\\\\\\\",\\\\\\\"testcontainers\\\\\\\",\\\\\\\"boundary test\\\\\\\"]\",\"triggers\":\"[\\\\\\\"should this be a unit or integration test\\\\\\\",\\\\\\\"the integration test is flaky\\\\\\\",\\\\\\\"test pyramid vs test trophy\\\\\\\",\\\\\\\"real database in tests\\\\\\\",\\\\\\\"test data setup is taking over\\\\\\\"]\",\"examples\":\"[\\\\\\\"design an integration test for the order service that exercises real database and real message bus\\\\\\\",\\\\\\\"decide which dependencies to fake and which to use real in an integration test\\\\\\\",\\\\\\\"diagnose a flaky integration test — likely shared mutable state across tests\\\\\\\",\\\\\\\"explain why the test pyramid and test trophy disagree on integration test count\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"test a single function in isolation (use testing-strategy + test-doubles-design)\\\\\\\",\\\\\\\"test a full user journey through the UI (use e2e-test-design)\\\\\\\",\\\\\\\"verify a consumer-driven contract against a provider (use contract-testing)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"test-doubles-design\\\\\\\",\\\\\\\"test-driven-development\\\\\\\",\\\\\\\"e2e-test-design\\\\\\\",\\\\\\\"contract-testing\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"testing-strategy owns the strategic question of how much of each test level to invest in; this skill owns the design of integration-level tests specifically.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"test-doubles-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"test-doubles-design owns the construction of mocks/stubs/fakes; this skill owns the per-dependency real-vs-faked decision in integration scope. Integration tests use real collaborators where practical and fakes only at true external boundaries.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"e2e-test-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"e2e-test-design owns user-journey-scope tests that exercise the full stack including UI; this skill owns scope below that — interaction of units inside the system, often without UI.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"contract-testing\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"contract-testing owns consumer-driven contract verification between services; this skill owns the in-system interaction of modules. Contract tests verify the *interface*; integration tests verify the *implementation through* the interface.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"e2e-test-design\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"An integration test is to a software system what a fire-suppression drill in a specific corridor is to the whole building's safety plan — you are not testing whether each sprinkler head works in isolation (unit), nor whether everyone evacuates the entire building in fifteen minutes (e2e), you are testing whether the smoke detector in *this corridor* triggers the alarm panel which triggers the sprinkler which actually wets *that carpet*; the test's identity is the named boundary, and changing the named boundary changes the test's identity.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Integration test design is the discipline of designing tests that verify the interaction of two or more units of a system — modules within a process, services across processes, layers within an architecture — to catch defects that emerge only at the boundaries between those units. The unit of judgment is the *boundary*: whether type-mapped, serialized, transactional, contract-bound, or simply called across a function boundary, the integration test's value is exercising the *real* interaction between the parts rather than the *mocked* interaction a unit test would exercise. The scope choice — which units are real, which are faked, which are out of scope — is the central design decision and the source of most fragile integration test suites: too narrow and the test is a unit test in disguise; too broad and the test is an end-to-end test in disguise; in between, the test is what its name says.\\\\\\\",\\\\\\\"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/integration-test-design/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/integration-test-design/SKILL.md
+---
+
+# Integration-Test Design
+
+## Coverage
+
+The discipline of designing tests that verify the interaction between two or more units of a system — modules within a process, services across processes, layers within an architecture, services across organizational boundaries — to catch defects that emerge only at the boundaries. Covers the five primitives (boundary, scope, real-vs-faked-collaborator, test-data lifecycle, pyramid-or-trophy framing), the boundary-type taxonomy (module-to-module, layer-to-layer, service-to-database, service-to-message-bus, service-to-third-party, service-to-service), the test-data lifecycle patterns (full reset, transaction rollback, container reset, shared snapshot), and the pyramid (Cohn 2009) vs trophy (Dodds 2018) framings for how much integration testing the suite should contain. Includes Testcontainers and similar infrastructure as the modern enabler that makes integration testing cheap enough to do well.
+
+## Philosophy
+
+Integration tests verify the parts of a system that no individual unit can verify alone. The bugs they catch — type misalignment, serialization edge cases, transaction boundary errors, configuration mismatches, contract drift, ordering and concurrency issues — live at the boundaries between units. A test suite of comprehensive unit tests and zero integration tests has verified each unit and not the system; the seams are unverified.
+
+The discipline's central design decision is *scope*: for each test, which collaborators are real (exercised in their integration-bug-finding form) and which are faked (replaced because their realness adds cost without proportional defect-detection). The scope determines the test's identity. Too narrow (mocks at the boundary): the "integration test" is a unit test in disguise and misses the integration bugs. Too broad (real everything, including UI): the "integration test" is an e2e test in disguise and pays the e2e cost.
+
+Modern testing infrastructure — Testcontainers for containerized real dependencies, transaction rollback for fast isolation, parallel execution within and across CI jobs, recorded fakes for third parties — has shifted the cost of integration testing down enough that the test trophy framing (integration-heavy suite) has gained ground on the pyramid (unit-heavy suite). The right ratio for a given codebase depends on which suite costs are real and which are surmountable with infrastructure.
+
+## The Pyramid vs The Trophy
+
+| Framing | Suite shape | Year | Cost assumption | Best fit |
+|---|---|---|---|---|
+| Test Pyramid (Cohn) | Many unit / fewer integration / fewest e2e | 2009 | Integration tests expensive, slow, flaky | Codebases where integration infra is missing or costly |
+| Test Trophy (Dodds) | Many integration / fewer unit / fewer e2e / static-analysis stem | 2018 | Integration tests cheap with modern tooling; unit tests pin implementation details | Codebases with strong integration-test infrastructure |
+| Diamond | Many integration / few unit / few e2e | — | Same as trophy minus the static-analysis stem | Codebases where unit tests have lost most value vs the maintenance cost |
+
+Both pyramid and trophy agree on: unit tests for fast feedback on implementation logic, integration tests for boundary verification, e2e tests sparingly for full-stack confidence. The disagreement is about the ratio between unit and integration, which depends on what each costs in a given codebase.
+
+## Scope Choice — The Defining Decision
+
+For each test, name the scope explicitly. For each dependency in scope, decide real or faked.
+
+| Dependency | Real cost | Faked cost | Typical choice |
+|---|---|---|---|
+| In-process other modules | Free | Loses integration coverage | Real always |
+| Database | Containerized: low (Testcontainers reuse) | In-memory variant: low; loses some real-DB bugs | Real (containerized or in-memory variant) |
+| Message bus | Containerized: low | In-memory variant: loses delivery semantics | Real (containerized) for production-confidence tests |
+| Cache (Redis) | Containerized: low | In-memory fake: loses eviction/TTL bugs | Real (containerized) |
+| Third-party API (paid) | Per-call cost; rate limit | Recorded fake: free, may drift | Recorded fake for PR tests; real sandbox for nightly |
+| Third-party API (free, stable) | Network latency; availability | Recorded fake: free | Real for nightly; recorded for PR |
+| Email / SMS providers | Sends real messages — usually wrong | Capture fake: verifies the call was made | Capture fake; never real in tests |
+| Authentication / OAuth | Real provider often unavailable in test | Issued-token fake | Token fake |
+
+The decision rule: use real where the boundary's specific failure modes are integration-bug-finders (database, message bus); use fake where the dependency's realness adds cost (paid APIs) or unacceptable side effects (emails) without proportional defect-detection.
+
+## Test Data Lifecycle Patterns
+
+| Pattern | Speed | Isolation | When to use |
+|---|---|---|---|
+| Per-test full reset (drop / recreate) | Slowest (~seconds per test) | Strongest | Tests with destructive schema changes |
+| Per-test transaction rollback | Fast (milliseconds) | Strong (for transactional DBs) | Most database integration tests |
+| Per-suite seed + per-test mutation isolation | Fast | Medium | Read-heavy test suites with limited mutation |
+| Shared snapshot + no-mutation discipline | Fastest | Relies on team discipline | Pure read tests |
+| Container reset per test (Testcontainers) | Medium (container startup) | Strongest cross-process | Tests where transaction rollback isn't viable |
+
+The standard production setup is transaction rollback for the bulk of database integration tests, with container reset reserved for the minority where transaction rollback doesn't work (cross-database tests, tests that exercise the transaction system itself).
+
+## When To Use Real Dependencies vs Faked
+
+Quick decision table:
+
+| Question | If yes | If no |
+|---|---|---|
+| Is the bug class you want to catch at this boundary specific to the real dependency? | Use real | Consider faked |
+| Is the real dependency available in test environment? | Use real or sandbox | Use recorded fake |
+| Is the real dependency's per-test cost acceptable? | Use real | Use recorded fake |
+| Does the real dependency have unacceptable side effects (real emails, real charges)? | Use capture fake | n/a |
+| Does the team have infrastructure for the real dependency (Testcontainers, etc.)? | Use real | Build the infra or use recorded fake |
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Every integration test's scope is explicit: which collaborators are real, which are faked, what boundary the test exercises. Tests without explicit scope drift between unit and e2e.
+- [ ] Real database, real message bus, real cache are used where their failure modes are integration-bug-finders. Mocking these dependencies usually means the test is unit-scope.
+- [ ] Third-party APIs are faked (recorded responses) for fast PR tests and exercised real in scheduled (nightly/weekly) integration runs.
+- [ ] Test data lifecycle is one of the named patterns (transaction rollback / container reset / per-suite seed / shared no-mutation), not ad-hoc. Test independence is a property of the lifecycle, not a hope.
+- [ ] Flaky integration tests are diagnosed (shared mutable state, ordering dependency, time-of-day dependency, race condition), not accepted. A persistent flake is a bug in the test design.
+- [ ] The pyramid-or-trophy ratio is intentional and reviewed against the codebase's actual integration-test cost and integration-bug rate.
+- [ ] Integration tests are not used where contract tests would be more targeted. The two compose; one does not replace the other.
+- [ ] Integration tests run in CI on every PR (with appropriate scope), not relegated to "nightly only" except for the slowest tier (sandbox third parties, multi-service e2e).
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Testing a single function in isolation with all collaborators mocked | `testing-strategy` + `test-doubles-design` | unit-scope test; this skill is for inter-unit scope |
+| Testing a full user journey through the UI | `e2e-test-design` | user-journey scope; this skill is for internal seams |
+| Verifying that a service's external interface matches the consumer's expectations | `contract-testing` | contract scope; this skill verifies implementation through the interface |
+| Measuring whether the test suite catches defects | `mutation-testing` | quality measurement; this skill is the integration-test design itself |
+| Choosing the overall ratio of test levels | `testing-strategy` | strategy owns ratios; this skill owns integration-test internals |
+| Snapshot-capturing a complex output | `snapshot-testing` | snapshot technique; this skill is integration-test scope |
+
+## Key Sources
+
+- Cohn, M. (2009). *Succeeding with Agile: Software Development Using Scrum*. Addison-Wesley. The book that popularized the test pyramid as the standard recommended suite shape.
+- Fowler, M. (2012). ["The Practical Test Pyramid"](https://martinfowler.com/articles/practical-test-pyramid.html). The most-cited practitioner essay on the pyramid framing, with practical advice on integration-test scope and infrastructure.
+- Dodds, K. C. (2018). ["The Testing Trophy and Testing Classifications"](https://kentcdodds.com/blog/the-testing-trophy-and-testing-classifications). The essay introducing the test trophy as an alternative to the pyramid, arguing integration tests are the high-value tier.
+- Testcontainers. ["Testcontainers — Reference"](https://testcontainers.com/). The canonical reference for containerized real-dependency integration testing across many languages and dependency types.
+- Meszaros, G. (2007). *xUnit Test Patterns: Refactoring Test Code*. Addison-Wesley. Catalog of integration-test patterns including the test-data lifecycle patterns (Setup, Teardown, Shared Fixture, Transaction Rollback).
+- Fowler, M. ["UnitTest"](https://martinfowler.com/bliki/UnitTest.html) and ["IntegrationTest"](https://martinfowler.com/bliki/IntegrationTest.html). Reference pages defining the terms practitioners use; both note the hazy line between sociable unit tests and integration tests.
+- Vocke, H. (2018). ["The Practical Test Pyramid — Updated"](https://martinfowler.com/articles/practical-test-pyramid.html). Updated practitioner guidance on test-pyramid implementation, including integration-test infrastructure recommendations.
+- ThoughtWorks. ["Test Doubles" and "Test pyramid" in the Technology Radar](https://www.thoughtworks.com/radar). Industry-practitioner consensus on integration-test patterns evolving over years.