constella 0.1.0

package/skills/engineering/frontend/accessibility-wcag/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: accessibility-wcag
+description: Meeting WCAG 2.2 success criteria and applying ARIA Authoring Practices for accessible UI; consult when building or auditing component accessibility.
+domain: engineering
+category: frontend
+tags: [accessibility, a11y, wcag, aria, w3c, wai]
+official_sources:
+  - https://www.w3.org/WAI/WCAG22/quickref/
+  - https://www.w3.org/WAI/ARIA/apg/
+  - https://github.com/w3c/wcag
+verified: 2026-06-16
+---
+
+# Accessibility (WCAG 2.2 & ARIA)
+
+## Overview
+WCAG (Web Content Accessibility Guidelines) is the W3C standard defining how to make web content accessible; the ARIA Authoring Practices Guide (APG) shows how to build accessible widgets with ARIA roles, states, and keyboard support. Read this when implementing interactive components, choosing semantics, or auditing a UI for conformance.
+
+## Official sources
+- WCAG 2.2 Quick Reference (How to Meet WCAG): https://www.w3.org/WAI/WCAG22/quickref/
+- ARIA Authoring Practices Guide (APG): https://www.w3.org/WAI/ARIA/apg/
+- Repo: https://github.com/w3c/wcag
+
+## Core concepts
+- **POUR principles.** WCAG organizes success criteria under four principles: Perceivable, Operable, Understandable, and Robust (w3.org/WAI/WCAG22/quickref).
+- **Conformance levels A / AA / AAA.** Each success criterion has a level; Level AA is the most commonly targeted baseline for sites and apps (w3.org/WAI/WCAG22/quickref).
+- **Techniques and failures.** Each criterion links sufficient techniques (ways to satisfy it), advisory techniques, and documented common failures to avoid (w3.org/WAI/WCAG22/quickref).
+- **Semantics first, ARIA second.** The APG covers ARIA roles, states, and properties for components that native HTML cannot express, but native HTML semantics are preferred where available (w3.org/WAI/ARIA/apg).
+- **Keyboard support.** APG patterns specify the expected keyboard interaction for each widget so it is operable without a mouse (w3.org/WAI/ARIA/apg).
+- **Landmark regions.** Use HTML sectioning elements and ARIA landmark roles to structure a page so assistive technology users can navigate it (w3.org/WAI/ARIA/apg/practices/landmark-regions).
+- **Accessible name and description.** Elements must expose a name (and optional description) that assistive technology can announce (w3.org/WAI/ARIA/apg).
+
+## Best practices
+- Target Level AA across the four POUR principles and use the Quick Reference's filters to track which criteria apply to your technologies (w3.org/WAI/WCAG22/quickref).
+- Reach for an established APG design pattern before inventing a custom widget; follow its required roles, states, and keyboard model exactly (w3.org/WAI/ARIA/apg).
+- Provide a meaningful accessible name for every interactive control and a landmark structure for every page (w3.org/WAI/ARIA/apg).
+- Validate against the sufficient techniques listed for each relevant success criterion rather than guessing (w3.org/WAI/WCAG22/quickref).
+
+## Common pitfalls
+- Adding ARIA roles to elements that already have native semantics → prefer the native HTML element; ARIA does not change behavior, only the exposed semantics (w3.org/WAI/ARIA/apg).
+- Building a custom widget (menu, dialog, tabs) without keyboard support → implement the keyboard interaction the matching APG pattern specifies (w3.org/WAI/ARIA/apg).
+
+## Examples
+```html
+<!-- Landmark + accessible name; native button needs no ARIA role. -->
+<nav aria-label="Primary">
+  <button type="button">Menu</button>
+</nav>
+```
+
+## Further reading
+- https://www.w3.org/WAI/ARIA/apg/patterns/ — full catalog of widget patterns
+- https://www.w3.org/WAI/standards-guidelines/wcag/ — WCAG standards overview
+
+## Related skills
+- ../frontend-architecture — where accessible components fit in the UI tree
+- ../state-management — managing widget state (open/selected) accessibly

package/skills/engineering/frontend/frontend-architecture/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: frontend-architecture
+description: Structuring component boundaries, data flow, and code-splitting in modern frontend apps; consult when designing or refactoring UI architecture.
+domain: engineering
+category: frontend
+tags: [components, data-flow, code-splitting, react, architecture, lazy-loading]
+official_sources:
+  - https://react.dev/learn
+  - https://www.patterns.dev/
+  - https://github.com/react/react
+verified: 2026-06-16
+---
+
+# Frontend Architecture
+
+## Overview
+Frontend architecture is how you split a UI into components, decide where data lives and how it flows, and control what code ships to the browser and when. Good structure keeps features local, props predictable, and bundles small. Read this when starting a new app, drawing component boundaries, or addressing slow initial loads.
+
+## Official sources
+- Docs: https://react.dev/learn
+- Patterns reference: https://www.patterns.dev/
+- Repo: https://github.com/react/react
+
+## Core concepts
+- **Components compose top-down.** A React component is a function returning markup; you nest components and pass data via props, building UI from small reusable pieces (react.dev/learn).
+- **One-way data flow.** Data flows down through props; child components do not mutate parent state directly, which makes data movement easy to trace (react.dev/learn).
+- **Lifting state up.** When two siblings need the same data, move that state to their closest common parent and pass it down, rather than duplicating it (react.dev/learn/sharing-state-between-components).
+- **Single source of truth.** State should not contain redundant or duplicated information; derive values during render instead of storing them (react.dev/learn/choosing-the-state-structure).
+- **Code-splitting with lazy loading.** `lazy` defers loading a component's code until it first renders, reducing the initial bundle; it must be paired with `<Suspense>` (react.dev/reference/react/lazy).
+- **Rendering / loading patterns.** patterns.dev catalogs reusable approaches such as bundle splitting, the PRPL pattern, and import-on-interaction to ship less JavaScript up front (patterns.dev).
+
+## Best practices
+- Push `'use client'` / interactive boundaries as deep into the tree as possible so static parts stay shippable and bundles stay small (react.dev/learn; patterns.dev performance patterns).
+- Keep state minimal and derived data computed in render, avoiding state you would have to keep in sync (react.dev/learn/choosing-the-state-structure).
+- Split routes and heavy, rarely-used components with `lazy` + `Suspense` so users only download what they need (react.dev/reference/react/lazy).
+- Co-locate state with the components that use it, lifting it only as far up as required by shared consumers (react.dev/learn/sharing-state-between-components).
+
+## Common pitfalls
+- Declaring a `lazy` component inside another component → declare it at module level; nesting it resets state on every re-render (react.dev/reference/react/lazy).
+- Storing redundant or duplicated state (e.g. a `fullName` alongside `firstName`/`lastName`) → compute it during render to avoid sync bugs (react.dev/learn/choosing-the-state-structure).
+- Prop-drilling shared data through many layers → reconsider component boundaries or use context where appropriate (react.dev/learn/passing-data-deeply-with-context).
+
+## Examples
+```jsx
+import { lazy, Suspense } from 'react';
+
+// Module-level: code is split and loaded on first render.
+const MarkdownPreview = lazy(() => import('./MarkdownPreview.js'));
+
+export default function Editor() {
+  return (
+    <Suspense fallback={<Loading />}>
+      <MarkdownPreview />
+    </Suspense>
+  );
+}
+```
+
+## Further reading
+- https://react.dev/learn/thinking-in-react — deriving component structure from a mockup
+- https://www.patterns.dev/ — rendering, design, and performance patterns
+
+## Related skills
+- ../state-management — choosing where state lives
+- ../rendering-strategies-ssr-csr — where components render

package/skills/engineering/frontend/rendering-strategies-ssr-csr/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: rendering-strategies-ssr-csr
+description: Trade-offs between SSR, CSR, static rendering, and streaming for web apps; consult when choosing where and when UI is rendered.
+domain: engineering
+category: frontend
+tags: [ssr, csr, ssg, streaming, hydration, rendering, nextjs]
+official_sources:
+  - https://web.dev/articles/rendering-on-the-web
+  - https://nextjs.org/docs/app/getting-started/server-and-client-components
+  - https://github.com/vercel/next.js
+verified: 2026-06-16
+---
+
+# Rendering Strategies (SSR / CSR / Static / Streaming)
+
+## Overview
+Where and when you render HTML — on the server, in the browser, at build time, or progressively streamed — affects first paint, interactivity, and the amount of JavaScript shipped. There is no single best choice; each strategy trades time-to-first-byte, first contentful paint, and interactivity differently. Read this when picking a rendering approach for a page or framework, or diagnosing slow loads.
+
+## Official sources
+- Google web.dev — Rendering on the Web: https://web.dev/articles/rendering-on-the-web
+- Next.js — Server and Client Components: https://nextjs.org/docs/app/getting-started/server-and-client-components
+- Repo (Next.js): https://github.com/vercel/next.js
+
+## Core concepts
+- **Server-side rendering (SSR).** Render the app on the server and send HTML; this gives fast first contentful paint and ships less JavaScript, but server work can delay time-to-first-byte (web.dev/articles/rendering-on-the-web).
+- **Client-side rendering (CSR).** Render in the browser with JavaScript modifying the DOM; large bundles can hurt interactivity (INP) (web.dev/articles/rendering-on-the-web).
+- **Static rendering (SSG).** Generate HTML at build time, one file per URL, for fast FCP and low blocking time; struggles when URLs are unpredictable (web.dev/articles/rendering-on-the-web).
+- **Hydration / rehydration.** Run client scripts to attach state and interactivity to server-rendered HTML; done poorly, a page can look interactive before it actually is (web.dev/articles/rendering-on-the-web).
+- **Streaming SSR.** Send HTML in chunks the browser renders progressively, improving perceived load (web.dev/articles/rendering-on-the-web).
+- **Server vs Client Components (Next.js).** Components default to the server for data fetching and smaller bundles; mark interactive ones with `'use client'`, and stream server-rendered chunks to the client (nextjs.org server-and-client-components).
+
+## Best practices
+- Measure where the bottleneck is (TTFB, FCP, INP) before choosing a strategy; the right answer depends on your content and audience (web.dev/articles/rendering-on-the-web).
+- Prefer server rendering for data-fetching and secret access, keeping API keys off the client and reducing shipped JavaScript (nextjs.org server-and-client-components).
+- Add `'use client'` to the smallest interactive components rather than large subtrees, so static parts stay server-rendered and bundles stay small (nextjs.org server-and-client-components).
+- Use streaming with `<Suspense>` boundaries so a fast shell renders while slower, dynamic content streams in (nextjs.org server-and-client-components).
+
+## Common pitfalls
+- Shipping a large CSR bundle for content that could be static or server-rendered → use SSR/SSG to cut JavaScript and improve FCP (web.dev/articles/rendering-on-the-web).
+- Marking large subtrees `'use client'` → every import in that file joins the client bundle; scope the directive to the interactive leaf (nextjs.org server-and-client-components).
+
+## Examples
+```tsx
+// Next.js App Router: Server Component fetches data; only the leaf is a Client Component.
+import LikeButton from './like-button'; // 'use client' lives in this file
+
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const post = await getPost(id); // runs on the server
+  return <article><h1>{post.title}</h1><LikeButton likes={post.likes} /></article>;
+}
+```
+
+## Further reading
+- https://web.dev/articles/rendering-on-the-web — full SSR/CSR/static/streaming trade-off guide
+- https://nextjs.org/docs/app/getting-started — Next.js App Router fundamentals
+
+## Related skills
+- ../frontend-architecture — code-splitting and component boundaries
+- ../state-management — hydrating and managing state across the server/client boundary

package/skills/engineering/frontend/state-management/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: state-management
+description: Choosing between local UI state, server/async state, and global state in React apps; consult when deciding where data should live and how it updates.
+domain: engineering
+category: frontend
+tags: [state, react, tanstack-query, server-state, context, reducers]
+official_sources:
+  - https://react.dev/learn/managing-state
+  - https://tanstack.com/query/latest
+  - https://github.com/TanStack/query
+verified: 2026-06-16
+---
+
+# State Management
+
+## Overview
+Frontend state falls into distinct kinds: local UI state (a component's own data), server/async state (remote data that is cached and can go stale), and shared/global state across components. Picking the right tool for each avoids over-engineering and sync bugs. Read this when deciding where a piece of data should live or which library, if any, to introduce.
+
+## Install / setup
+TanStack Query (React) — install command copied verbatim from the official installation page (tanstack.com/query/latest/docs/framework/react/installation):
+```bash
+npm i @tanstack/react-query
+```
+
+## Official sources
+- React state docs: https://react.dev/learn/managing-state
+- TanStack Query docs: https://tanstack.com/query/latest
+- Repo (TanStack Query): https://github.com/TanStack/query
+
+## Core concepts
+- **State drives the UI.** You describe UI as states and update state in response to input, letting React re-render rather than mutating the DOM imperatively (react.dev/learn/managing-state).
+- **Keep state structure lean.** Avoid redundant or duplicated state; compute derived values during render (react.dev/learn/choosing-the-state-structure).
+- **Lift state up to share it.** Move shared state to the closest common parent and pass it down via props (react.dev/learn/sharing-state-between-components).
+- **Reducers for complex logic.** `useReducer` consolidates many related state updates into one reducer, keeping event handlers clean (react.dev/learn/extracting-state-logic-into-a-reducer).
+- **Context for deep passing.** React context shares data deeply without prop-drilling and pairs with a reducer to scale up app state (react.dev/learn/scaling-up-with-reducer-and-context).
+- **Server state is different.** TanStack Query treats remote data as something with a cache and lifecycle — fetched, shared, cached, refetched, and sometimes intentionally stale — distinct from client state (tanstack.com/query/latest).
+
+## Best practices
+- Default to local component state; only lift it up or introduce context when multiple components genuinely need it (react.dev/learn/managing-state).
+- Use a dedicated server-state library like TanStack Query for fetching, caching, and synchronizing remote data instead of hand-rolling it in component state (tanstack.com/query/latest).
+- Reach for `useReducer` once a component juggles several interrelated state transitions (react.dev/learn/extracting-state-logic-into-a-reducer).
+- Don't store derived data in state — recompute it in render to prevent it from drifting out of sync (react.dev/learn/choosing-the-state-structure).
+
+## Common pitfalls
+- Caching server data in `useState`/context and manually refetching → use TanStack Query, which gives async data a cache and lifecycle (tanstack.com/query/latest).
+- Duplicating one source of truth across components → lift it to a common parent or context so there is a single owner (react.dev/learn/sharing-state-between-components).
+
+## Examples
+```jsx
+import { useQuery } from '@tanstack/react-query';
+
+function Todos() {
+  const { data, isPending, error } = useQuery({
+    queryKey: ['todos'],
+    queryFn: () => fetch('/api/todos').then((r) => r.json()),
+  });
+  if (isPending) return <p>Loading…</p>;
+  if (error) return <p>Failed to load</p>;
+  return <ul>{data.map((t) => <li key={t.id}>{t.title}</li>)}</ul>;
+}
+```
+
+## Further reading
+- https://react.dev/learn/choosing-the-state-structure — principles for shaping state
+- https://tanstack.com/query/latest/docs — caching, mutations, and invalidation
+
+## Related skills
+- ../frontend-architecture — component boundaries and data flow
+- ../rendering-strategies-ssr-csr — where state is hydrated and rendered

package/skills/engineering/performance/backend-performance/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: backend-performance
+description: Design resilient, high-throughput backends — timeouts, retries with backoff, connection pooling, concurrency limits, and avoiding N+1 queries.
+domain: engineering
+category: performance
+tags: [backend, concurrency, timeouts, retries, connection-pool, n+1, scalability]
+official_sources:
+  - https://aws.amazon.com/builders-library/
+  - https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/
+verified: 2026-06-16
+---
+
+# Backend Performance
+
+## Overview
+Backend performance is about sustaining throughput and low latency under real load and partial failure, not just making a single request fast. This skill covers concurrency control, connection management, retry/timeout discipline, and data-access patterns (especially the N+1 problem), grounded in the Amazon Builders' Library and SQL indexing literature. Read it when designing services that must stay responsive under contention or overload.
+
+## Official sources
+- Amazon Builders' Library (hub): https://aws.amazon.com/builders-library/
+- Timeouts, retries, backoff with jitter: https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/
+- Avoiding fallback in distributed systems: https://aws.amazon.com/builders-library/avoiding-fallback-in-distributed-systems/
+- SQL indexing / N+1 background: https://use-the-index-luke.com/
+
+## Core concepts
+- **Timeouts bound waiting.** Every remote call needs a timeout; the Builders' Library recommends setting it from downstream latency metrics (e.g. a high percentile like p99.9) so legitimate slow requests are tolerated but stuck calls fail fast.
+- **Retries are "selfish."** Per AWS, retries consume extra server resources and amplify load during overload; they help transient failures but can turn a brownout into an outage if applied blindly.
+- **Exponential backoff with jitter.** Spacing retries exponentially and adding randomness prevents synchronized "retry storms" where all clients hammer a recovering service at once.
+- **Connection pooling.** Reusing a bounded pool of connections (DB, HTTP) avoids per-request handshake cost and caps concurrency against downstreams; pool size is itself a concurrency limit.
+- **Concurrency limits / load shedding.** Bounding in-flight work and shedding excess load keeps latency stable; unbounded concurrency causes queue buildup and cascading latency under load.
+- **The N+1 query problem.** Fetching a list then issuing one query per item (1 + N) multiplies round-trips and table accesses; batch or join instead. use-the-index-luke explains how scattered per-row table access makes even indexed lookups slow.
+- **Avoid fallbacks as the happy path.** AWS argues fallback code is rarely exercised, hard to test, and often amplifies failures; prefer strengthening the primary path and letting callers retry.
+
+## Best practices
+- **Set timeouts everywhere and tune from data.** Derive timeout values from observed downstream latency percentiles rather than guessing; a missing timeout is an unbounded resource leak.
+- **Retry only transient/idempotent operations, with capped exponential backoff and jitter.** Add a retry budget/circuit breaker so retries cannot dominate traffic during incidents.
+- **Bound concurrency explicitly.** Size connection pools and worker concurrency to the downstream's capacity; shed or queue with limits instead of accepting unbounded work.
+- **Eliminate N+1 access.** Batch loads (join, `IN (...)`, or a dataloader) so a list view is O(1)–O(2) queries, not O(N); verify with query-count assertions in tests.
+- **Make work cancelable and propagate deadlines.** Pass a deadline/cancellation token down the call chain so a client timeout actually stops downstream work.
+
+## Common pitfalls
+- **No timeout on a remote call** → one slow dependency exhausts threads/connections; always bound the wait and fail fast.
+- **Naive immediate retries** → synchronized retry storms re-create the congestion that caused the failure; use exponential backoff with jitter and a retry budget.
+- **Hidden N+1 from lazy ORM relations** → looping over a collection triggers a query per element; eager-load or batch and assert query counts.
+- **Treating fallback paths as safe** → seldom-exercised fallbacks fail when finally triggered; per AWS, exercise them continuously or remove them and rely on retries.
+
+## Examples
+```python
+# Capped exponential backoff with full jitter for an idempotent call
+import random, time
+
+def call_with_retry(do, *, attempts=5, base=0.05, cap=2.0, timeout=1.0):
+    for attempt in range(attempts):
+        try:
+            return do(timeout=timeout)          # always bound the wait
+        except TransientError:
+            if attempt == attempts - 1:
+                raise
+            backoff = min(cap, base * 2 ** attempt)
+            time.sleep(random.uniform(0, backoff))  # full jitter
+```
+
+## Further reading
+- https://aws.amazon.com/builders-library/avoiding-fallback-in-distributed-systems/ — why fallbacks backfire
+- https://aws.amazon.com/builders-library/ — operational excellence essays (load shedding, fairness, caching)
+- ./reference.md — deeper patterns (loaded only when needed)
+
+## Related skills
+- ../database-query-optimization — fixing the queries behind N+1 and slow access
+- ../profiling-and-benchmarking — locating the real bottleneck before tuning

package/skills/engineering/performance/database-query-optimization/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: database-query-optimization
+description: Speed up SQL with proper indexing and EXPLAIN — read query plans, understand B-tree index lookups, and fix slow access paths.
+domain: engineering
+category: performance
+tags: [sql, indexing, explain, query-plan, postgresql, b-tree, optimization]
+official_sources:
+  - https://use-the-index-luke.com/
+  - https://www.postgresql.org/docs/current/using-explain.html
+verified: 2026-06-16
+---
+
+# Database Query Optimization
+
+## Overview
+Most SQL performance problems are access-path problems: the right index turns a full scan into a targeted lookup, and `EXPLAIN` reveals which path the planner actually chose. Read this when a query is slow, when adding indexes, or when you need to interpret a query plan rather than guess. Material is grounded in Markus Winand's "Use The Index, Luke" and the official PostgreSQL documentation.
+
+## Official sources
+- SQL indexing guide: https://use-the-index-luke.com/
+- Why indexes can be slow: https://use-the-index-luke.com/sql/anatomy/slow-indexes
+- PostgreSQL Using EXPLAIN: https://www.postgresql.org/docs/current/using-explain.html
+- PostgreSQL source (mirror): https://github.com/postgres/postgres
+
+## Core concepts
+- **A B-tree index has structure.** An index is a balanced tree whose leaf nodes form a doubly linked list of sorted entries; a lookup does a tree traversal to the right leaf, then optionally follows the leaf chain.
+- **An index lookup has three steps.** Per use-the-index-luke: tree traversal, following the leaf node chain, and accessing the table rows. The third step (one table access per matching row) is usually what makes an "indexed" query still slow.
+- **Scan types map to those steps.** `INDEX UNIQUE SCAN` is tree traversal only; `INDEX RANGE SCAN` traverses and walks the leaf chain; `TABLE ACCESS BY INDEX ROWID` fetches the actual rows.
+- **EXPLAIN shows the plan; ANALYZE runs it.** `EXPLAIN` prints the planner's chosen tree of nodes with estimated cost, rows, and width; `EXPLAIN ANALYZE` executes the query and reports actual time, row counts, and (with `BUFFERS`) buffer usage.
+- **Cost estimates drive plan choice.** PostgreSQL estimates each node's cost from table statistics; bad statistics lead to bad plans (e.g. choosing a seq scan over an index, or vice versa).
+- **Selectivity decides whether an index helps.** Indexes win when they select a small fraction of rows; for low-selectivity predicates a sequential scan can legitimately be faster than many scattered table accesses.
+
+## Best practices
+- **Index for the WHERE clause and join columns.** Create indexes that cover the predicates that filter rows; column order in a composite index matters because the tree is sorted left-to-right.
+- **Read the actual plan, not your assumptions.** Use `EXPLAIN (ANALYZE, BUFFERS)` to compare estimated vs actual rows; a large gap signals stale statistics or a misjudged predicate.
+- **Keep statistics fresh.** Ensure `ANALYZE`/autovacuum keeps planner statistics current so cost estimates stay accurate.
+- **Prefer covering / index-only access for hot queries.** Include the selected columns in the index so the table-access step (the expensive third step) can be skipped where supported.
+- **Avoid functions/wrapping on indexed columns in predicates.** Applying a function to a column (or an implicit cast) prevents the plain index from being used; index the expression instead if needed.
+
+## Common pitfalls
+- **"It has an index, so it's fast"** → an `INDEX RANGE SCAN` over many matches plus one table access per row can be slower than a scan; check selectivity and the plan.
+- **Trusting estimated rows** → estimates can be wrong; `EXPLAIN ANALYZE` shows the real row counts and timing to confirm.
+- **Wrong composite index column order** → a leading column that isn't in the predicate makes the index unusable for that filter; order columns by how they are queried.
+- **Wrapping indexed columns in functions** → `WHERE lower(email) = ...` skips a plain index on `email`; create a matching expression index or store normalized values.
+
+## Examples
+```sql
+-- Inspect the real plan, not just the estimate
+EXPLAIN (ANALYZE, BUFFERS)
+SELECT id, status
+FROM orders
+WHERE customer_id = 42 AND status = 'open';
+
+-- Composite index ordered to match the predicate (equality columns first)
+CREATE INDEX idx_orders_customer_status ON orders (customer_id, status);
+```
+
+## Further reading
+- https://use-the-index-luke.com/sql/anatomy/slow-indexes — the three steps of a lookup in detail
+- https://www.postgresql.org/docs/current/using-explain.html — full EXPLAIN/ANALYZE reference
+- ./reference.md — join strategies and planner internals (loaded only when needed)
+
+## Related skills
+- ../backend-performance — eliminating N+1 access patterns that no index can fix
+- ../profiling-and-benchmarking — measuring query latency before and after indexing

package/skills/engineering/performance/profiling-and-benchmarking/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: profiling-and-benchmarking
+description: Measure before optimizing — use CPU/memory profilers and benchmarks to find real bottlenecks instead of guessing; covers Node.js and Chrome DevTools.
+domain: engineering
+category: performance
+tags: [profiling, benchmarking, cpu-profile, flame-graph, nodejs, devtools, memory-leak]
+official_sources:
+  - https://nodejs.org/en/learn/getting-started/profiling
+  - https://developer.chrome.com/docs/devtools/performance
+verified: 2026-06-16
+---
+
+# Profiling and Benchmarking
+
+## Overview
+The first rule of optimization is to measure: profilers tell you where time and memory actually go, and benchmarks confirm whether a change helped. This skill covers sampling profilers, flame graphs, and runtime/memory analysis using the built-in Node.js profiler and the Chrome DevTools Performance panel. Read it before optimizing anything, so effort lands on the real bottleneck.
+
+## Official sources
+- Node.js profiling guide: https://nodejs.org/en/learn/getting-started/profiling
+- Chrome DevTools Performance panel: https://developer.chrome.com/docs/devtools/performance
+- Chrome DevTools memory problems: https://developer.chrome.com/docs/devtools/memory-problems
+- Node.js source (repo): https://github.com/nodejs/node
+
+## Core concepts
+- **Sampling profilers.** Node's `--prof` uses V8's built-in profiler to sample the call stack at intervals and record events as "ticks" in an `isolate-*.log`, processed with `--prof-process` into a human-readable summary.
+- **Bottom-up vs summary views.** The processed tick output groups time by Summary, C++, and a bottom-up profile, letting you trace which functions and their callers dominate CPU time.
+- **Flame graphs.** The DevTools Performance panel visualizes main-thread activity as a flame chart so you can spot wide (expensive) frames and long tasks.
+- **Runtime vs load performance.** Per Chrome, runtime performance is how a page behaves while running (Response, Animation, Idle phases of the RAIL model), distinct from initial load.
+- **Memory problem classes.** DevTools distinguishes memory leaks (steadily growing usage), memory bloat (using more than needed), and frequent garbage collection that pauses script execution.
+- **Benchmark vs profile.** A benchmark measures aggregate throughput/latency of a change; a profile attributes cost within a run. Use benchmarks to decide *whether* something is faster and profiles to learn *why*.
+
+## Best practices
+- **Measure before and after, with a baseline.** Establish a repeatable benchmark first; otherwise you cannot tell whether an optimization helped or hurt.
+- **Profile under production-like conditions.** Run Node profiling with `NODE_ENV=production` and realistic load, as the official guide demonstrates, so JIT and code paths match production.
+- **Find the dominant cost, then optimize that.** The Node guide's example showed synchronous `pbkdf2` consuming ~51.8% of CPU; switching to the async version raised throughput from 5.33 to 19.46 req/s — fix the biggest frame first.
+- **Use heap snapshots and the allocation timeline for leaks.** In DevTools, compare snapshots over time and watch for detached DOM nodes and steadily growing retained size.
+- **Keep benchmarks isolated and warmed up.** Exclude setup, warm the JIT, and run enough iterations to get stable numbers before comparing.
+
+## Common pitfalls
+- **Optimizing by intuition** → developers routinely guess the wrong hotspot; always confirm with a profile before changing code.
+- **Profiling a dev build or trivial workload** → results won't reflect production; profile production builds under representative load.
+- **Reporting a single run as a benchmark** → variance and JIT warmup distort one-shot numbers; run multiple warmed iterations and compare distributions.
+- **Confusing high GC frequency with a leak** → frequent GC may indicate excessive short-lived allocation (bloat), not retained memory; distinguish with the allocation timeline.
+
+## Examples
+```bash
+# Node.js: capture a CPU profile, then turn it into a readable report
+NODE_ENV=production node --prof app.js
+# ...generate load against the app, then stop it
+node --prof-process isolate-0xnnnnnnnnnnnn-v8.log > processed.txt
+```
+
+## Further reading
+- https://developer.chrome.com/docs/devtools/memory-problems — diagnosing leaks, bloat, and GC churn
+- https://nodejs.org/en/learn/getting-started/profiling — full Node.js profiling walkthrough
+- ./reference.md — flame-graph reading and benchmark harness tips (loaded only when needed)
+
+## Related skills
+- ../backend-performance — what to do once a bottleneck is found server-side
+- ../web-performance-core-vitals — field metrics that tell you what to profile on the front end

package/skills/engineering/performance/web-performance-core-vitals/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: web-performance-core-vitals
+description: Measure and optimize Core Web Vitals (LCP, INP, CLS) for real-user front-end performance; consult when tuning page load and interactivity.
+domain: engineering
+category: performance
+tags: [web-vitals, lcp, inp, cls, frontend, rum, performance]
+official_sources:
+  - https://web.dev/articles/vitals
+  - https://github.com/GoogleChrome/web-vitals
+verified: 2026-06-16
+---
+
+# Web Performance: Core Web Vitals
+
+## Overview
+Core Web Vitals are the subset of Web Vitals that Google considers essential signals of real-user experience: loading (LCP), interactivity (INP), and visual stability (CLS). Read this when you need to measure page performance against objective field thresholds and prioritize fixes that affect actual users rather than synthetic lab scores alone.
+
+## Official sources
+- Docs: https://web.dev/articles/vitals
+- Optimize LCP guide: https://web.dev/articles/optimize-lcp
+- MDN performance hub: https://developer.mozilla.org/en-US/docs/Web/Performance
+- Repo (measurement library): https://github.com/GoogleChrome/web-vitals
+- Install / download: https://www.npmjs.com/package/web-vitals
+
+## Install / setup
+```bash
+npm install web-vitals
+```
+
+## Core concepts
+- **The three Core Web Vitals.** LCP (Largest Contentful Paint) measures loading, INP (Interaction to Next Paint) measures interactivity, and CLS (Cumulative Layout Shift) measures visual stability.
+- **"Good" thresholds at the 75th percentile.** Per web.dev: LCP within 2.5 s, INP of 200 ms or less, CLS of 0.1 or less — assessed at the 75th percentile of page loads, split across mobile and desktop.
+- **Field (RUM) vs lab data.** Core Web Vitals are defined against real-user (field) data such as the Chrome User Experience Report; lab tools like Lighthouse approximate but cannot replace field measurement.
+- **LCP load breakdown.** web.dev decomposes LCP into time to first byte, resource load delay, resource load duration, and element render delay — optimizing LCP is largely about loading the LCP resource sooner and faster.
+- **Layout shift scoring.** CLS sums layout shift scores (impact fraction x distance fraction) from unexpected shifts; shifts within 500 ms of user input are excluded.
+- **Performance APIs.** Browsers expose timing via the Navigation Timing, Resource Timing, and Long Animation Frame APIs (see MDN), which the web-vitals library reads through `PerformanceObserver`.
+
+## Best practices
+- **Measure with the official library on real users.** Use `web-vitals` (`onLCP`, `onINP`, `onCLS`) with its `buffered` PerformanceObserver flag so metrics match Chrome's own reporting; send results to your analytics endpoint.
+- **Make the LCP resource discoverable early.** Per the optimize-LCP guide, include it in the initial HTML, set appropriate `fetchpriority`, and avoid loading it via JavaScript that delays discovery.
+- **Reserve space to prevent CLS.** Set explicit `width`/`height` (or `aspect-ratio`) on images and media, and avoid inserting content above existing content after load.
+- **Reduce main-thread work for INP.** Break up long tasks and minimize JavaScript executed during interactions so the next paint after an input happens within 200 ms.
+- **Cut TTFB.** Minimize redirects and serve cacheable HTML from CDN edge servers, since TTFB is the floor for LCP.
+
+## Common pitfalls
+- **Optimizing only lab scores** → Lighthouse is a lab approximation; ship against field/CrUX data because that is what Core Web Vitals are measured on.
+- **Treating averages as the target** → thresholds are evaluated at the 75th percentile across devices; a good average can still fail at p75 on slow mobile.
+- **Lazy-loading the LCP image** → deferring the largest above-the-fold element delays its load and inflates LCP; eager-load it instead.
+- **Ignoring INP because FID looked fine** → INP replaced FID as a Core Web Vital and considers all interactions across the page lifecycle, not just the first input.
+
+## Examples
+```js
+import { onLCP, onINP, onCLS } from 'web-vitals';
+
+function send(metric) {
+  // metric: { name, value, rating, delta, id }
+  navigator.sendBeacon('/analytics', JSON.stringify(metric));
+}
+
+onLCP(send);
+onINP(send);
+onCLS(send);
+```
+
+## Further reading
+- https://web.dev/articles/optimize-lcp — optimizing LCP step by step
+- https://web.dev/articles/cls — understanding and reducing layout shift
+- https://developer.mozilla.org/en-US/docs/Web/Performance — MDN performance guides and APIs
+
+## Related skills
+- ../profiling-and-benchmarking — measuring before optimizing, browser profilers
+- ../backend-performance — server-side TTFB and load handling that feeds LCP

package/skills/engineering/practices/clean-code/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: clean-code
+description: Writing readable, consistent code — naming, small focused functions, cohesion, and following a project style guide.
+domain: engineering
+category: practices
+tags: [clean-code, readability, naming, style-guide, functions]
+official_sources:
+  - https://google.github.io/styleguide/
+  - https://github.com/google/styleguide
+verified: 2026-06-16
+---
+
+# Clean Code
+
+## Overview
+Clean code is code optimized for the human reader, not just the compiler: clear names, small focused units, and a consistent style so a large codebase stays understandable as it grows. Consult this when naming things, splitting up large functions, or deciding which conventions to adopt for a project. The Google Style Guides are a concrete, widely-used reference for the "consistency" half of the problem.
+
+## Official sources
+- Docs: https://google.github.io/styleguide/
+- Repo: https://github.com/google/styleguide
+
+## Core concepts
+- **Consistency beats personal preference.** As the Google Style Guides note, a large codebase is much easier to understand when all its code follows a single consistent style; the guide itself is "sometimes arbitrary" by design, because agreeing on *a* convention matters more than the convention.
+- **A style guide is a set of conventions.** Each major project defines its own rules for formatting, naming, and structure (Google publishes per-language guides for C++, Java, Python, JavaScript, Go, and more).
+- **Readable names.** Names should reveal intent so the reader does not have to trace the implementation to understand what a variable, function, or class is for.
+- **Small, focused functions.** A function that does one thing at one level of abstraction is easier to name, test, and reuse than a long multi-purpose block.
+- **Cohesion.** Group code that changes together; a class or module should have a single, clear responsibility rather than a grab-bag of unrelated behavior.
+
+## Best practices
+- **Adopt and enforce a style guide.** Pick an existing published guide (e.g. Google's per-language guide) rather than inventing one, and enforce it with a formatter/linter so style stops being a review topic.
+- **Name for intent, not implementation.** Prefer descriptive names that a reviewer can understand without context (one of Google's stated code-review checks is whether names clearly communicate intent — see code-review-practices).
+- **Keep functions short and single-purpose.** Extract sub-steps into well-named helpers so each function reads top-to-bottom at one level of abstraction.
+- **Comment the "why", not the "what".** Use comments to explain rationale and non-obvious decisions; let clear names and structure express the "what".
+
+## Common pitfalls
+- **Bikeshedding over formatting in reviews** → automate formatting with a tool so humans review behavior and design, not whitespace.
+- **One giant function / "god" class** → split by responsibility into smaller cohesive units; low cohesion makes change risky and testing hard.
+- **Cryptic or misleading names** (`tmp`, `data2`, names that lie about behavior) → rename to reflect actual intent; a rename is a cheap, safe refactoring (see refactoring).
+
+## Examples
+```python
+# Unclear: what is processed, and what comes back?
+def proc(d):
+    r = []
+    for x in d:
+        if x[1] > 0:
+            r.append(x[0])
+    return r
+
+# Clean: intent-revealing names, one job
+def names_of_in_stock_products(products):
+    return [name for name, quantity in products if quantity > 0]
+```
+
+## Further reading
+- Google C++ Style Guide: https://google.github.io/styleguide/cppguide.html
+- Google Python Style Guide: https://google.github.io/styleguide/pyguide.html
+
+## Related skills
+- ../refactoring — how to safely improve unclean code
+- ../code-review-practices — what reviewers check for, including naming and clarity