@skill-graph/cli 0.5.6

package/marketplace/skills/refactor/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: refactor
+description: "Use when reorganizing existing code without changing external behavior — extracting functions, reducing duplication, renaming for clarity, splitting modules, or tightening structure. Covers behavior preservation, duplication reduction, decomposition, naming improvements, structural reorganization, and before/after verification. Do NOT use for bug investigation, adding new product behavior, or writing documentation (even when the docs describe the refactored code)."
+license: MIT
+compatibility: "Markdown, Git, any codebase"
+allowed-tools: Read Grep Bash
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"workflow\",\"category\":\"engineering\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-04-18\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-04-18\\\\\\\"}\",\"eval_artifacts\":\"present\",\"eval_state\":\"passing\",\"routing_eval\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"refactor\\\\\\\",\\\\\\\"cleanup\\\\\\\",\\\\\\\"simplify\\\\\\\",\\\\\\\"extract function\\\\\\\",\\\\\\\"reduce duplication\\\\\\\",\\\\\\\"clean this up\\\\\\\",\\\\\\\"simplify this\\\\\\\",\\\\\\\"rename this\\\\\\\",\\\\\\\"split this file\\\\\\\",\\\\\\\"too long function\\\\\\\",\\\\\\\"duplicated logic\\\\\\\",\\\\\\\"decompose function\\\\\\\",\\\\\\\"decompose code\\\\\\\",\\\\\\\"decompose long\\\\\\\",\\\\\\\"split by responsibility\\\\\\\",\\\\\\\"behavior preserving\\\\\\\",\\\\\\\"rename module\\\\\\\",\\\\\\\"rename utils\\\\\\\",\\\\\\\"messy code\\\\\\\",\\\\\\\"messy suite\\\\\\\",\\\\\\\"extract helper\\\\\\\",\\\\\\\"extract duplicated\\\\\\\",\\\\\\\"consolidate logic\\\\\\\",\\\\\\\"tighten structure\\\\\\\",\\\\\\\"large component refactor\\\\\\\",\\\\\\\"make sure refactor preserves behavior\\\\\\\"]\",\"triggers\":\"[\\\\\\\"refactor-skill\\\\\\\"]\",\"examples\":\"[\\\\\\\"this 600-line function is hard to reason about — decompose it while keeping tests green\\\\\\\",\\\\\\\"extract the duplicated validation logic from these three handlers into a helper\\\\\\\",\\\\\\\"rename this module from `utils` to something that describes what it actually does\\\\\\\",\\\\\\\"split this file by responsibility; no behavior changes, tests must still pass\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"the test is failing after my edit — what did I break?\\\\\\\",\\\\\\\"write an architecture note explaining this pattern for new team members\\\\\\\",\\\\\\\"reproduce why this function retries three times on transient network errors\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"debugging\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"debugging chases an observed failure; refactor runs only with a green test suite and preserves behavior\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"tool-call-flow\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"tool-call-flow owns the protocol-level cycle of model→runtime tool invocation including retry encoding inside the cycle; refactor only restructures the surrounding code while preserving behavior. The anti_example about a function retrying three times is a tool-call/runtime concern, not a refactor concern.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"generative-ui\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"generative-ui owns the model-emits-typed-UI-spec pattern; refactor only restructures existing code while preserving behavior. The retries anti_example has token overlap with the model-output/runtime cycle vocabulary generative-ui discusses, so naming it here keeps the boundary explicit.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\"],\\\\\\\"depends_on\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"min_version\\\\\\\":\\\\\\\"^1.0.0\\\\\\\"}]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"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/refactor/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/refactor/SKILL.md
+---
+
+# Refactor
+
+## Coverage
+
+- Behavior preservation: identifying the external contract that must remain stable before any change
+- Duplication reduction: consolidating repeated logic without over-abstraction
+- Decomposition: extracting functions, modules, or types to improve readability and reuse
+- Naming improvements: renaming so identifiers carry their real meaning
+- Structure improvements: reorganizing file and module boundaries when the current layout obscures intent
+- Verification before and after: running the same behavioral checks on both sides of the change
+
+## Philosophy
+
+Refactoring pays off only when the shape of the code has diverged from the shape of the problem. Before that point it is risk without reward — every move invites a regression, and "cleaner" is a preference, not a justification. The honest test for a legitimate refactor is not "this feels better" but "the next concrete change will be materially easier because of this one." If you cannot name the next change, stop — you are rearranging, not refactoring, and the safest rearrangement is none.
+
+## Workflow
+
+Each step decides whether to continue, split, or stop. "Stop" is always a valid answer; speculative refactoring is a failure mode, not a signal of ambition.
+
+| Step | Ask | If yes | If no |
+|---|---|---|---|
+| 1. Contract | What externally observable behavior must stay the same? | Write it down as a test suite or explicit checklist | Stop — you cannot refactor what you cannot pin down |
+| 2. Next-change justification | Can you name one concrete pending change that becomes easier because of this refactor? | Go to step 3 | Stop — you are rearranging for taste, not improving the codebase |
+| 3. Smallest useful cut | What is the smallest structural change that moves toward the next-change goal? | Make only that change | Split into sequential cuts; do not change multiple abstraction layers at once |
+| 4. Behavior re-verify | Does the contract from step 1 still hold exactly? | Commit | Revert; the refactor was not behavior-preserving. Start over smaller |
+| 5. Stop condition | Have you made the next change materially easier than it would have been before? | Done | Do not keep going — refactoring beyond the next change is speculative waste |
+
+### When to back out
+
+- A green test from before the refactor is now red → revert immediately, then cut smaller.
+- The next-change goal shifted during the refactor → restart at step 2 with the new goal before continuing.
+- The refactor requires touching more than one abstraction layer in a single commit → split into per-layer commits and re-verify each.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/refactor.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/refactor.json). The `Verification` checklist below is the authoring gate for a completed refactor; the eval file is how this skill is graded by `scripts/skill-audit.js --graded`. Do not conflate them — the checklist is for the engineer, the eval is for the grader.
+
+## Verification
+
+- [ ] External behavior is unchanged — same tests green before and after
+- [ ] The named next change is now demonstrably easier, not merely "more possible"
+- [ ] No new abstraction was introduced speculatively (no "future-proofing" without a named consumer)
+- [ ] Each commit is a single structural change, not a bundle of rearrangements
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `debugging` | The task starts from a failing behavior, not from structural cleanup |
+| `documentation` | The task is rewriting docs — even docs about the refactored code — it belongs to a separate commit and skill |
+| `testing-strategy` | The task is designing a new test suite; the refactor's own tests should already exist before step 1 |

package/marketplace/skills/rendering-models/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: rendering-models
+description: "Use when reasoning about how a web UI is produced and delivered: client-side rendering, server-side rendering, static-site generation, incremental static regeneration, React Server Components, streaming SSR, edge rendering, and partial prerendering. Covers the time × place grid (build/request/stream/interaction × server/edge/client), the trade-offs between first-paint latency and time-to-interactive, the relationship between rendering and hydration, and how a route's content profile (dynamic / static / personalized) maps to a model. Do NOT use for organizing the frontend codebase (use frontend-architecture), the serialization frontier between server and client code (use client-server-boundary), the wire protocol itself (use http-semantics), or specific deploy-platform composition patterns (use vercel-composition-patterns)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/frontend\",\"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\":\"[\\\\\\\"rendering model\\\\\\\",\\\\\\\"CSR\\\\\\\",\\\\\\\"SSR\\\\\\\",\\\\\\\"SSG\\\\\\\",\\\\\\\"ISR\\\\\\\",\\\\\\\"React Server Components\\\\\\\",\\\\\\\"RSC\\\\\\\",\\\\\\\"streaming SSR\\\\\\\",\\\\\\\"edge rendering\\\\\\\",\\\\\\\"partial prerendering\\\\\\\",\\\\\\\"hydration\\\\\\\",\\\\\\\"time to interactive\\\\\\\",\\\\\\\"first contentful paint\\\\\\\"]\",\"triggers\":\"[\\\\\\\"should this page be server-rendered\\\\\\\",\\\\\\\"static or dynamic\\\\\\\",\\\\\\\"what's the difference between SSR and RSC\\\\\\\",\\\\\\\"why is this page slow to first paint\\\\\\\",\\\\\\\"should this be a client component\\\\\\\"]\",\"examples\":\"[\\\\\\\"decide whether a product page should be SSG with revalidation or SSR\\\\\\\",\\\\\\\"explain why a marketing page is fast but a dashboard is slow despite both 'server rendering'\\\\\\\",\\\\\\\"choose between streaming SSR and a loading skeleton\\\\\\\",\\\\\\\"diagnose why a server component re-renders on every navigation\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"organize the folder structure of a frontend codebase (use frontend-architecture)\\\\\\\",\\\\\\\"decide what types can cross the network boundary (use client-server-boundary)\\\\\\\",\\\\\\\"design HTTP cache headers (use http-semantics)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"frontend-architecture\\\\\\\",\\\\\\\"client-server-boundary\\\\\\\",\\\\\\\"http-semantics\\\\\\\",\\\\\\\"performance-engineering\\\\\\\",\\\\\\\"vercel-composition-patterns\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"frontend-architecture\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"frontend-architecture owns how the codebase is organized; rendering-models owns where and when the UI is produced. A route's architecture and its rendering model are independent decisions.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"client-server-boundary\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"client-server-boundary owns the serialization frontier (what can cross between server and client code). rendering-models owns the staging of work across build/request/stream/interaction.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"http-semantics\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"http-semantics owns the wire protocol (caching headers, status codes, content negotiation). rendering-models is upstream — it decides what HTML and JS exist; http-semantics decides how they are delivered and cached.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"performance-engineering\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"performance-engineering owns measurement, profiling, and optimization across the stack. rendering-models is one input — the choice of model bounds what performance numbers are achievable on a given route.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"performance-engineering\\\\\\\",\\\\\\\"frontend-architecture\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Rendering models are to web pages what cooking styles are to restaurant kitchens — the same ingredients (data, components, markup) get plated differently depending on whether the kitchen pre-cooks at dawn (SSG), cooks to order during service (SSR), streams courses out as they finish (streaming SSR), or hands raw ingredients to the diner to assemble themselves (CSR), and no one style is right for every menu item.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"A rendering model is the strategy by which a web user interface is produced and delivered, defined by two axes: when the work happens (build time, request time, response stream, or user interaction) and where it executes (server, edge, or client). The choice of model determines first-paint latency, time-to-interactive, server cost, cache behavior, and which content can be indexed by crawlers.\\\\\\\",\\\\\\\"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/rendering-models/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/rendering-models/SKILL.md
+---
+
+# Rendering Models
+
+## Coverage
+
+The taxonomy of how a web user interface is produced and delivered. Covers the time × place grid (build / request / stream / interaction × server / edge / client), the six named models in current use (CSR, SSR, SSG, ISR, RSC, streaming SSR) plus two recent additions (edge SSR, PPR), their trade-offs in FCP, LCP, TTI, INP, server cost, and crawlability, and the relationship between rendering and the downstream concerns of bundling, hydration, and HTTP delivery.
+
+## Philosophy
+
+A rendering model is a staging decision: at what moment, and in what location, does the work of producing the UI happen. The full work is the same — interpret data, compose a component tree, emit DOM, attach behavior — but moving each step between build, request, stream, and interaction has dramatic consequences for what the user experiences first, how the server scales, and whether the content is crawlable.
+
+The model choice is per-route, not per-application. A site that picks one model for everything will be wrong for most of its routes. The correct mental model is a grid of trade-offs, with each route landing at the position that matches its content profile (static / dynamic / personalized) and its performance constraints (FCP / TTI / cost).
+
+The goal of this skill is to make the trade-offs legible, not to pick a winner. The right model in 2026 for a marketing page is not the right model for a logged-in dashboard, and neither is the right model for a streaming chat UI.
+
+## The Time × Place Grid
+
+The grid below positions the named models on the two-axis space. Read each cell as "work happens at this time, in this place."
+
+| | Server (origin) | Edge | Client |
+|---|---|---|---|
+| **Build** | SSG | SSG (with edge cache) | — |
+| **Request** | SSR, RSC | Edge SSR, Edge RSC | — |
+| **Stream** | Streaming SSR, PPR | Edge streaming | — |
+| **Interaction** | — | — | CSR, hydration |
+
+The Client column is sparse because client-only models are rare in production — most pages mix at least one server-produced step (HTML or RSC payload) with client interaction.
+
+## Trade-off Profile
+
+The four user-facing performance numbers respond differently to each model.
+
+| Model | FCP | LCP | TTI | INP | Server cost | Crawl-friendly |
+|---|---|---|---|---|---|---|
+| CSR | Worst — empty shell | Worst — depends on client fetch | Worst — full JS execute | Worst — depends on bundle | Lowest | Conditional (depends on crawler JS support) |
+| SSR | Good — HTML served | Good | Worse — hydration cost | Worse if bundle is large | Highest | Yes |
+| SSG | Best — CDN cache | Best | Worse — hydration cost | Worse if bundle is large | Lowest at request | Yes |
+| ISR | Best (hot) / Good (cold) | Best (hot) / Good (cold) | Worse — hydration cost | Worse if bundle is large | Low (background regen) | Yes |
+| RSC | Good — server tree | Good | Better — less client JS | Better — less client JS | High | Yes |
+| Streaming SSR | Excellent — shell first | Good | Better — interactive in chunks | Same as SSR | High | Yes |
+| Edge SSR | Excellent — proximity | Good | Same as SSR | Same as SSR | Medium | Yes |
+| PPR | Excellent — static shell | Good — streamed | Better | Better | Low for shell, high for dynamic | Yes |
+
+"Worse if bundle is large" means hydration cost dominates: the model produced HTML quickly, but the page is not interactive until the client JS loads, parses, and executes.
+
+## When to Choose Each Model
+
+A heuristic matrix. Use it as a starting point; always validate with real measurements.
+
+| Route profile | First choice | Second choice |
+|---|---|---|
+| Marketing page (rarely changes, no personalization) | SSG | ISR if content updates daily |
+| Blog post (occasional updates) | SSG with on-demand revalidation | ISR with TTL |
+| Product detail (catalog + inventory) | ISR or PPR | SSR if catalog changes hourly |
+| Search results (per-query) | SSR or streaming SSR | Edge SSR if global users |
+| Logged-in dashboard (per-user data) | SSR or RSC | Streaming SSR if data is slow |
+| Real-time chart (high update rate) | CSR with server data | RSC + client island for the chart |
+| Admin panel (rarely visited, personal) | RSC | SSR |
+| Documentation site (static content + search) | SSG + client search | PPR if search is server-side |
+
+## Hydration — The Cost the Model Cannot Hide
+
+Every model except pure CSR-from-scratch produces HTML that the client must hydrate to be interactive. Hydration walks the existing DOM, reconciles it against the React (or other framework) component tree, and attaches event handlers. The cost is:
+
+- Proportional to the number of components.
+- Paid before the page is interactive.
+- Visible in INP and TTI metrics.
+
+Strategies that reduce hydration cost:
+
+- **RSC** — server components are omitted from the client bundle; only client components hydrate.
+- **Islands architecture** (Astro, Marko, Qwik) — only the marked-interactive parts hydrate; the rest is static HTML forever.
+- **Progressive hydration** — hydrate components as they enter the viewport or as the user interacts.
+- **Resumability** (Qwik) — the framework serializes the application state into HTML so the client never needs to re-execute initialization code.
+
+A page that uses any model with a 2MB client JS bundle will hydrate slowly regardless of how its HTML was produced. The HTML production speed and the hydration cost are independent.
+
+## Edge Rendering
+
+Edge runtimes (Cloudflare Workers, Vercel Edge, Deno Deploy, Fastly Compute@Edge) move SSR closer to the user. The trade-off:
+
+- **Pro** — geographic proximity reduces TTFB. Cold starts are faster than serverless functions (often single-digit ms).
+- **Con** — the runtime is constrained: typically Web Standard APIs (fetch, Request, Response, streams) but not full Node.js. Direct database connections are usually unavailable; data access happens via HTTP to an origin.
+- **Hybrid** — edge for the rendering step, origin for the data step. Works well when the data fetch is cacheable; less well when every request requires a fresh database round-trip from the edge.
+
+Edge SSR is most useful when (1) the audience is geographically distributed, (2) per-request rendering is needed, (3) the data layer is HTTP-accessible.
+
+## Partial Prerendering (PPR)
+
+PPR is the most recent addition to the taxonomy. It produces:
+
+1. A static shell at build time (the parts of the page that don't change per request).
+2. Streamed dynamic content at request time (the parts that do — user data, personalized blocks, inventory).
+
+The user sees the shell instantly (cache-served), and the dynamic holes fill in via streaming. The model is well-suited for routes where most of the layout is static but small regions are personal (a product page with a "recommended for you" block, a dashboard wrapper with per-user widgets).
+
+PPR is currently first-class in Next.js (App Router); the underlying pattern is general and can be implemented in any framework with streaming SSR and a CDN.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] The rendering model for each route is documented (per route, not per app).
+- [ ] The choice matches the route's content profile — static content uses build-time models; per-user content uses request-time models.
+- [ ] FCP, LCP, INP are measured for representative routes in real-user conditions (not lab-only Lighthouse scores).
+- [ ] Hydration cost is acknowledged separately from rendering cost — a "fast SSR" page with a 1MB bundle is not actually fast for the user.
+- [ ] Routes mixing server and client work use the appropriate marker (`'use client'` / `'use server'` in React + Next.js, or the equivalent in the chosen framework).
+- [ ] SSG and ISR caches are validated to invalidate correctly on content updates (stale-while-revalidate behavior matches expectations).
+- [ ] Edge-rendered routes confirm their data access path works at the edge (HTTP-accessible, not direct DB).
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Organizing the frontend codebase folder layout | `frontend-architecture` | frontend-architecture owns module boundaries and component layering; rendering-models owns where and when the UI is produced |
+| Deciding what types and values can cross between server and client code | `client-server-boundary` | client-server-boundary owns the serialization frontier and marker directives |
+| Designing HTTP caching headers, status codes, or content negotiation | `http-semantics` | http-semantics owns the wire protocol; rendering-models is upstream |
+| Setting performance thresholds and failure consequences | `performance-budgets` | performance-budgets owns the threshold-and-consequence contract; rendering-models is one input to what budgets are achievable |
+| Profiling a specific slow page and deciding what to fix | `performance-engineering` | performance-engineering owns the diagnostic and optimization activity |
+| Composing build pipelines, deploy configs, or platform-specific features | `vercel-composition-patterns` | platform composition is downstream of model choice |
+
+## Key Sources
+
+- React team. [React Server Components RFC](https://github.com/reactjs/rfcs/blob/main/text/0188-server-components.md). Proposed Dec 2020; integrated into React 18+ and Next.js App Router. The canonical specification of RSC's component-tree serialization model.
+- Vercel. [Next.js App Router documentation — Rendering](https://nextjs.org/docs/app/building-your-application/rendering). Reference for how the named models map to the framework's primitives.
+- Google Chrome Team. [web.dev — Rendering on the Web](https://web.dev/articles/rendering-on-the-web). Jason Miller and Addy Osmani's matrix of CSR / SSR / SSG / pre-rendering / streaming — the foundational document for the taxonomy.
+- Remix team. [Remix loaders and the server-first model](https://remix.run/docs/en/main/route/loader). Reference for the request-time data-loading pattern that informs SSR design beyond React.
+- Astro team. [Astro Islands](https://docs.astro.build/en/concepts/islands/). The canonical statement of islands architecture and selective hydration.
+- Google. [Core Web Vitals](https://web.dev/articles/vitals). The user-experience metrics (LCP, INP, CLS) that the model choice directly affects.
+- Google. [The RAIL Performance Model](https://web.dev/articles/rail). Older but still load-bearing: the interaction-class taxonomy (Response / Animation / Idle / Load) that frames why TTI matters.
+- Misko Hevery. ["Hydration is Pure Overhead"](https://www.builder.io/blog/hydration-is-pure-overhead). 2022 essay arguing that hydration cost is the dominant factor in TTI for modern SSR — motivates resumability and islands as alternative architectures.

package/marketplace/skills/replication-patterns/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: replication-patterns
+description: "Use when designing how a database keeps multiple copies of its data in agreement across nodes for availability, read scaling, and disaster recovery: the three foundational topologies (single-leader / primary-replica, multi-leader / multi-primary, leaderless / quorum), synchronous vs asynchronous replication and the replication-lag trade-off, log shipping vs statement replication vs trigger-based replication, the read-after-write consistency problem and its mitigations (sticky session, read-from-leader, monotonic reads), the failover model and split-brain risk, and the relationship to the CAP/PACELC choices the topology realizes. Do NOT use for horizontal partitioning across nodes (use sharding-strategy), the CAP theoretical frame itself (use cap-theorem-tradeoffs), single-node transactional guarantees (use acid-fundamentals), or query tuning (use query-optimization)."
+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\":\"[\\\\\\\"replication\\\\\\\",\\\\\\\"primary replica\\\\\\\",\\\\\\\"multi-leader\\\\\\\",\\\\\\\"leaderless\\\\\\\",\\\\\\\"quorum\\\\\\\",\\\\\\\"synchronous replication\\\\\\\",\\\\\\\"asynchronous replication\\\\\\\",\\\\\\\"replication lag\\\\\\\",\\\\\\\"read-after-write\\\\\\\",\\\\\\\"failover\\\\\\\",\\\\\\\"split brain\\\\\\\",\\\\\\\"log shipping\\\\\\\",\\\\\\\"WAL streaming\\\\\\\"]\",\"triggers\":\"[\\\\\\\"single-leader vs multi-leader\\\\\\\",\\\\\\\"synchronous vs async replication\\\\\\\",\\\\\\\"what happens on failover\\\\\\\",\\\\\\\"split brain\\\\\\\",\\\\\\\"read-after-write consistency\\\\\\\"]\",\"examples\":\"[\\\\\\\"design replication topology for a service with one region writing and three regions reading\\\\\\\",\\\\\\\"decide between synchronous and asynchronous replication given a target RPO\\\\\\\",\\\\\\\"diagnose stale reads after a write — likely replication lag without read-after-write handling\\\\\\\",\\\\\\\"explain the split-brain risk in multi-leader replication\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"horizontally partition data across nodes (use sharding-strategy)\\\\\\\",\\\\\\\"reason about the CAP theorem abstractly (use cap-theorem-tradeoffs)\\\\\\\",\\\\\\\"explain ACID properties (use acid-fundamentals)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"cap-theorem-tradeoffs\\\\\\\",\\\\\\\"acid-fundamentals\\\\\\\",\\\\\\\"sharding-strategy\\\\\\\",\\\\\\\"transaction-isolation\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"cap-theorem-tradeoffs\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"cap-theorem-tradeoffs owns the theoretical frame for the consistency-availability trade-off; this skill owns the operational topologies and protocols that realize a chosen position on that trade-off. The two compose: CAP names the choice; replication-patterns is one of the realizations.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"sharding-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"sharding-strategy owns horizontal partitioning of data across nodes (different nodes hold different data); this skill owns replication of the same data across nodes (multiple nodes hold the same data). The two often combine in production systems but answer different questions.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"acid-fundamentals\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"acid-fundamentals owns the single-system transactional model; this skill owns the multi-node replication patterns that distributed systems use to scale, replicate, and survive failure. Replication often relaxes some ACID properties (most notably durability and isolation in async modes).\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"cap-theorem-tradeoffs\\\\\\\",\\\\\\\"sharding-strategy\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Replication is to a database what mirror copies of a master photograph are to a museum's record — single-leader async is the photographer keeping the negative and printing copies as requested; single-leader sync is the conservator requiring two darkroom signatures before any print leaves the building; multi-leader is multiple authorized photographers in different cities each accepting submissions and reconciling at intervals; leaderless quorum is asking three of five archivists to vote on whether this print matches the master, accepting their verdict. Failover is replacing the negative-keeper when they retire; split brain is what happens when the agency forgets to revoke the old keeper's keys.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Replication is the discipline of keeping multiple copies of the same data on multiple nodes so that the system can serve reads from any copy, survive the failure of any node, or both. The three foundational topologies are single-leader (primary-replica; one node accepts writes, others receive a stream of changes), multi-leader (multi-primary; multiple nodes accept writes and reconcile), and leaderless (quorum; clients write to a quorum of nodes directly). Each topology has its own consistency, availability, conflict-handling, and operational properties; choosing among them is choosing the system's CAP/PACELC position and accepting the operational complexity that comes with it. Synchronous vs asynchronous replication is an orthogonal choice within each topology, trading durability/consistency against latency. The discipline is matching the topology and the synchrony choice to the workload's actual requirements for read scaling, write availability, recovery point objective (RPO), and recovery time objective (RTO).\\\\\\\",\\\\\\\"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/replication-patterns/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/replication-patterns/SKILL.md
+---
+
+# Replication Patterns
+
+## Coverage
+
+The catalog of replication topologies and the operational discipline that makes them work in production. Covers the three foundational topologies (single-leader / primary-replica, multi-leader / multi-primary, leaderless / quorum), the synchrony spectrum (sync, semi-sync, async, quorum-sync), the mechanism choices (statement-based, row-based, trigger-based, logical, physical), the read-after-write consistency problem and its mitigations (sticky session, read-from-leader, monotonic reads, version tokens), the failover model and quorum-based split-brain prevention, the conflict-resolution choices in multi-leader and leaderless systems (LWW, CRDTs, vector clocks, application merge), and the relationship to the CAP/PACELC choices the topology realizes.
+
+## Philosophy
+
+Replication is the discipline that gives a database fault tolerance, read scaling, and disaster recovery — at the cost of consistency-handling, conflict resolution, and operational complexity.
+
+The default starting point is single-leader with asynchronous replication: simple, well-understood, sufficient for most read-mostly workloads. The departures from this default — multi-leader, leaderless, synchronous, geographic — each address a specific requirement (multi-region writes, strong consistency under partition, RPO=0) and add proportional complexity.
+
+The most common production failures are not in the replication topology itself but in the application's handling of its consequences: stale reads producing user-visible bugs, split brain producing silent data divergence, failover producing unrehearsed surprises. The discipline is treating replication as an architecture the application is co-designed with, not a database feature that handles itself.
+
+## Topology Selection
+
+| Topology | Best for | Trade-offs |
+|---|---|---|
+| Single-leader, async | Read-heavy workloads with tolerance for stale reads | Replication lag; possible data loss on leader failure |
+| Single-leader, sync | Workloads requiring RPO=0 | Write latency; replica failure can block writes |
+| Multi-leader | Multi-region writes; active-active disaster recovery | Conflict resolution complexity |
+| Leaderless (quorum) | High availability with tunable consistency | Read latency = slowest of R; quorum-sizing decisions |
+| Synchronous via Raft/Paxos (Spanner, CockroachDB) | Strong consistency at scale | High write latency for distant replicas |
+
+The starting point for most workloads is single-leader async; depart from this default only when the workload requires it.
+
+## Synchronous vs Asynchronous Trade-off
+
+| Property | Synchronous | Asynchronous |
+|---|---|---|
+| Write latency | Higher (waits for replica) | Lower (acks immediately) |
+| RPO (data loss on failure) | Zero | Up to lag window |
+| Read consistency from replicas | Strong | Eventual |
+| Replica failure impact | Can block writes | None |
+| Use case | High-stakes financial transactions, strong-RPO systems | Most production read-replicas |
+
+Semi-sync (wait for one replica with timeout-to-async fallback) is the middle ground; production-default for many systems.
+
+## Read-After-Write Mitigations
+
+| Mitigation | How it works | Cost |
+|---|---|---|
+| Read-from-leader for a window after write | Client routes back to leader for N seconds | Loses read scaling for write-heavy users |
+| Sticky session | Client always reads from same replica | Replica failure invalidates session |
+| Monotonic reads | Client tracks last-seen version; replica must be ≥ that fresh | Requires version-token plumbing |
+| Wait-for-replica | Client waits until replica catches up | Adds latency to the read |
+| Accept stale reads | Application tolerates staleness | Only viable when stale data is OK |
+
+Every read-mostly workload with async replicas must choose one. Defaulting to "read from any replica" produces stale-data bugs.
+
+## Failover and Split-Brain Prevention
+
+| Mechanism | Split-brain risk | Used by |
+|---|---|---|
+| Manual operator failover | None (if procedure is correct) | Small / legacy systems |
+| Heuristic auto-failover (no quorum) | High under partition | Older Postgres tools (without proper consensus) |
+| Quorum-based promotion (Raft / Paxos) | Eliminated by majority requirement | Modern HA tools (Patroni, etcd, CockroachDB internal) |
+| STONITH fencing | Old leader killed; cannot continue writing | Pacemaker / Corosync HA |
+
+A system that must not split-brain uses quorum-based promotion. The cost is requiring an odd number of voting nodes ≥ 3.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] The replication topology is intentional and documented: single-leader / multi-leader / leaderless; sync / async / semi-sync; physical / logical / trigger-based.
+- [ ] Read-after-write consistency is handled explicitly. Sticky session, read-from-leader, monotonic reads, version tokens, or accept-stale is a named choice.
+- [ ] Replication lag is monitored. Lag thresholds trigger alerts before users notice.
+- [ ] Failover procedure is documented, tested, and rehearsed. Untested failover is failover that fails first time.
+- [ ] Split-brain prevention uses quorum-based promotion for any system requiring it. Heuristic failover is recognized as risky.
+- [ ] Backups exist separately from replication. Replica state and backup state are distinguished.
+- [ ] For multi-leader: the conflict resolution mechanism (LWW / CRDT / vector clocks / app merge) is defined and tested with concurrent-write scenarios.
+- [ ] For leaderless: W and R values are chosen for the workload's consistency-vs-latency target; W+R>N if strong consistency is required.
+- [ ] Cross-region replication latency is measured and accepted as part of the design budget.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Horizontally partitioning data across nodes | `sharding-strategy` | sharding partitions data; replication copies it |
+| Reasoning about the CAP/PACELC theoretical frame | `cap-theorem-tradeoffs` | CAP names the trade-off; this skill realizes it |
+| Single-node transactional guarantees | `acid-fundamentals` | ACID is the single-system frame |
+| Choosing isolation levels | `transaction-isolation` | transaction-isolation owns concurrency; this owns multi-node |
+| Indexing | `indexing-strategy` | indexing is within-node retrieval |
+| Tuning a slow query | `query-optimization` | query-optimization is per-query |
+
+## Key Sources
+
+- Kleppmann, M. (2017). *Designing Data-Intensive Applications*. O'Reilly. Chapter 5 (Replication) — modern comprehensive treatment of all three topologies with practical detail.
+- Lamport, L. (1998). ["The Part-Time Parliament"](https://lamport.azurewebsites.net/pubs/lamport-paxos.pdf). *ACM TOCS*, 16(2). The Paxos consensus algorithm; foundation of synchronous replication with split-brain prevention.
+- Ongaro, D., & Ousterhout, J. (2014). ["In Search of an Understandable Consensus Algorithm (Raft)"](https://raft.github.io/raft.pdf). *USENIX ATC 2014*. The Raft consensus algorithm; basis of etcd, CockroachDB, many modern HA systems.
+- DeCandia, G., Hastorun, D., Jampani, M., et al. (2007). ["Dynamo: Amazon's Highly Available Key-Value Store"](https://www.allthingsdistributed.com/files/amazon-dynamo-sosp2007.pdf). *SOSP 2007*. The foundational paper on leaderless (Dynamo-style) replication; basis of Cassandra, Riak, DynamoDB.
+- PostgreSQL Global Development Group. ["PostgreSQL Documentation — Replication"](https://www.postgresql.org/docs/current/runtime-config-replication.html) and ["Logical Replication"](https://www.postgresql.org/docs/current/logical-replication.html). Reference for Postgres physical streaming and logical replication.
+- MySQL Reference Manual. ["Replication"](https://dev.mysql.com/doc/refman/8.0/en/replication.html). MySQL replication including binlog formats, semi-sync, and group replication.
+- MongoDB Manual. ["Replication"](https://www.mongodb.com/docs/manual/replication/). MongoDB replica sets, automatic failover, and oplog-based replication.
+- Vogels, W. (2009). ["Eventually Consistent"](https://queue.acm.org/detail.cfm?id=1466448). *ACM Queue*. Practitioner essay on eventual consistency in replicated systems.
+- Shapiro, M., Preguiça, N., Baquero, C., & Zawirski, M. (2011). ["A Comprehensive Study of Convergent and Commutative Replicated Data Types"](https://hal.inria.fr/inria-00555588). CRDT foundational paper; basis for multi-leader conflict resolution without data loss.
+- Brewer, E. (2012). ["CAP Twelve Years Later"](https://ieeexplore.ieee.org/document/6133253). *IEEE Computer*. Brewer's retrospective on CAP, useful for understanding the consistency-availability trade-offs replication realizes.

package/marketplace/skills/research-synthesis/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: research-synthesis
+description: "Use when turning raw qualitative research output (interview transcripts, field notes, diary entries, observation logs) into themes, patterns, insight statements, and design-ready artifacts via affinity mapping, empathy maps, and jobs-to-be-done framing. Do NOT use for collecting new research, quantitative analysis, statistical inference, or summarizing a single document — synthesis specifically operates on a corpus of qualitative evidence."
+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\":\"[\\\\\\\"affinity mapping\\\\\\\",\\\\\\\"empathy map\\\\\\\",\\\\\\\"insight statement\\\\\\\",\\\\\\\"theme clustering\\\\\\\",\\\\\\\"jobs to be done synthesis\\\\\\\",\\\\\\\"qualitative coding\\\\\\\",\\\\\\\"research wall\\\\\\\",\\\\\\\"downloading research\\\\\\\",\\\\\\\"say think do feel\\\\\\\",\\\\\\\"persona drafting\\\\\\\",\\\\\\\"point of view\\\\\\\",\\\\\\\"sticky-note synthesis\\\\\\\",\\\\\\\"pattern extraction\\\\\\\"]\",\"triggers\":\"[\\\\\\\"synthesize research\\\\\\\",\\\\\\\"affinity map\\\\\\\",\\\\\\\"empathy map\\\\\\\",\\\\\\\"find themes in interviews\\\\\\\",\\\\\\\"insight statements\\\\\\\"]\",\"examples\":\"[\\\\\\\"Cluster these 14 interview transcripts into themes using affinity mapping.\\\\\\\",\\\\\\\"Build an empathy map for the 'first-time buyer' segment from these field notes.\\\\\\\",\\\\\\\"Turn this set of observations into three insight statements I can take into ideation.\\\\\\\",\\\\\\\"Draft a jobs-to-be-done statement from this user research corpus.\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"Run more interviews with five additional participants.\\\\\\\",\\\\\\\"Calculate the response rate of the survey.\\\\\\\",\\\\\\\"Summarize this single PDF document.\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"user-research\\\\\\\",\\\\\\\"journey-mapping\\\\\\\",\\\\\\\"problem-framing\\\\\\\",\\\\\\\"design-thinking\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"user-research\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"user-research collects primary qualitative data. research-synthesis transforms that data into design-ready themes. Both are needed, in that order.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"conceptual-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"conceptual-modeling synthesizes domain entities and their relationships for engineering. research-synthesis synthesizes human behavior and need patterns for design — different output shapes, different audiences.\\\\\\\"}]}\",\"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/research-synthesis/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/research-synthesis/SKILL.md
+---
+
+# Research Synthesis
+
+## Coverage
+Research synthesis covers the methods that turn raw qualitative material into structured insight a team can act on. The canonical technique is **affinity mapping** (Jiro Kawakita's KJ method), where individual observations are written on cards or sticky notes, posted on a wall, and clustered bottom-up into emergent themes — without imposing pre-existing categories. Adjacent methods include **empathy mapping** (XPLANE / Dave Gray, "Say / Think / Do / Feel" quadrants), **insight statement** writing (a tension or surprise condensed into one sentence), **jobs-to-be-done synthesis** (extracting the functional, emotional, and social jobs a user is hiring a product to do), and **persona drafting** when patterns are stable enough to warrant archetypes.
+
+The skill includes the mechanics of **downloading research** — getting raw observations off transcripts and onto a shared surface (physical wall or digital board) as atomic units, one observation per card, in the participant's words where possible. This is the unglamorous part of the work and it is non-negotiable: themes that emerge from a wall of evidence are defensible; themes that emerge from memory or impression are not.
+
+The practice distinguishes **descriptive themes** (what we heard) from **interpretive insights** (what it means) from **point-of-view statements** (what we will act on). Each layer requires the previous one as evidence. A common synthesis output is a small set of insight statements, each in the form of an observation + interpretation + implication ("Users batch-process invoices on Fridays because their bookkeeper visits on Mondays — current weekly cadence misses this rhythm"), which then feed directly into problem framing or ideation.
+
+## Philosophy
+Synthesis is where qualitative research either pays off or quietly fails. The temptation is to read transcripts, form an impression, and write a summary — but impression-based summaries reproduce the researcher's priors rather than the participants' patterns. Affinity mapping is deliberately slow and physical because the act of moving cards forces the researcher to keep evaluating whether two observations actually belong together, instead of subsuming them under a comfortable label.
+
+The discipline is wary of premature abstraction. A theme named too early ("users want simplicity") becomes a magnet that pulls unrelated observations into it. The IDEO field guide and the Stanford d.school bootleg both teach delaying naming as long as possible — clustering by proximity first, naming only when the cluster's shape is undeniable. The same caution applies to personas: a persona built before patterns have stabilized fossilizes a guess, then teams optimize for a fictional user instead of real ones.
+
+## Verification
+- Every theme on the affinity wall traces back to at least two specific cards (observations), and each card is attributable to a specific session or participant.
+- Themes were named *after* the clusters formed, not before — the researcher can recount the moment the cluster's identity became clear.
+- At least one insight contradicts something the team believed before the research started; if every insight is comfortable, the synthesis was likely too charitable to existing assumptions.
+- The output distinguishes observations, interpretations, and implications — they are not collapsed into a single bullet list.
+- A reader unfamiliar with the raw research can read the synthesis and predict, in rough strokes, what a participant said — meaning the synthesis preserves enough specificity to be falsifiable.
+- The synthesis is small enough to act on (typically 3–7 themes, not 20) — if everything is a theme, nothing is.
+
+## Do NOT Use When
+- No primary research has been conducted yet — run **user-research** first; there is nothing to synthesize.
+- The question is quantitative (counts, percentages, trends over time) — use statistical analysis rather than affinity methods.
+- The corpus is a single document or a small set of internal artifacts — synthesis methods are designed for cross-session pattern extraction, not document summarization.
+- The team needs to model an engineering domain (entities, events, contexts) — use **conceptual-modeling** or **event-storming**.
+- The output target is a temporal cross-touchpoint experience map — synthesize first, then move to **journey-mapping**.
+- The task is to validate a single hypothesis against a known artifact — use **usability-testing** instead.