@skill-graph/cli 0.5.6

package/marketplace/skills/transaction-isolation/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: transaction-isolation
+description: "Use when reasoning about the I in ACID — the isolation level a database provides between concurrent transactions: the five SQL-standard levels (read uncommitted, read committed, repeatable read, serializable) plus snapshot isolation; the anomalies each level admits (dirty reads, non-repeatable reads, phantom reads, write skew, lost updates); the Berenson et al. 1995 critique that exposed the standard's looseness; the difference between locking-based and MVCC-based isolation; Postgres's Serializable Snapshot Isolation (SSI) as one rigorous implementation; how to choose an isolation level for a workload by enumerating the anomalies the workload cannot tolerate. Do NOT use for the broader ACID frame (use acid-fundamentals), distributed-replica consistency (use cap-theorem-tradeoffs), query performance tuning (use query-optimization), or schema design (use data-modeling)."
+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\":\"[\\\\\\\"isolation level\\\\\\\",\\\\\\\"read committed\\\\\\\",\\\\\\\"repeatable read\\\\\\\",\\\\\\\"serializable\\\\\\\",\\\\\\\"snapshot isolation\\\\\\\",\\\\\\\"SSI\\\\\\\",\\\\\\\"MVCC\\\\\\\",\\\\\\\"dirty read\\\\\\\",\\\\\\\"non-repeatable read\\\\\\\",\\\\\\\"phantom read\\\\\\\",\\\\\\\"write skew\\\\\\\",\\\\\\\"lost update\\\\\\\",\\\\\\\"Berenson\\\\\\\"]\",\"triggers\":\"[\\\\\\\"what isolation level do we need\\\\\\\",\\\\\\\"is read committed enough\\\\\\\",\\\\\\\"what's write skew\\\\\\\",\\\\\\\"MVCC vs locking\\\\\\\",\\\\\\\"Postgres serializable vs MySQL serializable\\\\\\\"]\",\"examples\":\"[\\\\\\\"choose an isolation level for a workload that has concurrent balance-decrement operations\\\\\\\",\\\\\\\"diagnose a data-correctness bug caused by an anomaly the chosen isolation level permits\\\\\\\",\\\\\\\"explain the difference between snapshot isolation and full serializability\\\\\\\",\\\\\\\"decide whether to use SELECT FOR UPDATE or upgrade isolation level\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"explain the four ACID properties (use acid-fundamentals)\\\\\\\",\\\\\\\"reason about distributed-replica consistency under partition (use cap-theorem-tradeoffs)\\\\\\\",\\\\\\\"tune a slow query (use query-optimization)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"acid-fundamentals\\\\\\\",\\\\\\\"cap-theorem-tradeoffs\\\\\\\",\\\\\\\"data-modeling\\\\\\\",\\\\\\\"query-optimization\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"acid-fundamentals\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"acid-fundamentals owns the four-property ACID frame as a whole; this skill owns the I axis specifically — the choice and semantics of isolation levels as a tunable. The two compose: acid-fundamentals names isolation as one of four guarantees; this skill makes the I axis operational.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"cap-theorem-tradeoffs\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"cap-theorem-tradeoffs owns distributed-replica agreement (CAP's C); this skill owns single-cluster transaction isolation (ACID's I). The two C/I letters concern different layers of the system.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"query-optimization\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"query-optimization owns the performance dimension of query execution; this skill owns the correctness dimension of concurrent execution. Optimizations that change locking behavior can shift anomaly exposure; the two interact.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"data-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"data-modeling owns schema and access-pattern design; this skill owns the concurrency-correctness contract under whichever schema and access pattern are chosen.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"acid-fundamentals\\\\\\\",\\\\\\\"query-optimization\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"An isolation level is to a database what a confidentiality regime is to a research lab — Read Uncommitted is the open whiteboard (anyone can read anyone's half-finished work); Read Committed is the rule that you only photograph your colleague's notebook after they have signed each page; Repeatable Read is a sealed envelope (you read once, you keep reading the same thing for the duration); Serializable is a locked vault (you take exclusive custody, others queue); Snapshot Isolation is a private photocopy (you read from your photocopy, others read from theirs, and only at commit time do the photocopies have to agree on the world they were taken from).\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Transaction isolation is the property — and the configurable choice — that determines whether concurrent transactions appear to execute serially or are permitted to observe each other's intermediate effects. The SQL standard defines four isolation levels (read uncommitted, read committed, repeatable read, serializable) by enumerating the anomalies each level may or may not permit (dirty reads, non-repeatable reads, phantom reads). Snapshot isolation, ubiquitous in modern MVCC databases, is a fifth practical level that the standard did not define. Stronger isolation eliminates more anomalies at the cost of concurrency (more transactions block or retry); weaker isolation admits anomalies that the application must handle, either by tolerating them, by upgrading the isolation level, or by using explicit locking. The discipline is choosing the isolation level by *naming the anomalies the application cannot tolerate*, not by reflex.\\\\\\\",\\\\\\\"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/transaction-isolation/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/transaction-isolation/SKILL.md
+---
+
+# Transaction Isolation
+
+## Coverage
+
+The I axis of ACID — the property and operational choice that determines what concurrent transactions can observe of each other. Covers the five practical levels (read uncommitted, read committed, repeatable read, snapshot isolation, serializable), the anomalies each admits (dirty reads, non-repeatable reads, phantom reads, lost updates, write skew, read-only-transaction anomalies), the Berenson et al. (1995) critique that exposed the SQL standard's looseness, the two dominant implementation mechanisms (two-phase locking and MVCC), Postgres's Serializable Snapshot Isolation (SSI), and the choice procedure: enumerate the anomalies the workload cannot tolerate, choose the lowest level that prevents them.
+
+## Philosophy
+
+Isolation is the most-mis-defaulted and most-mis-understood part of ACID. The standard's level names are not universal across databases; the level the team thinks they're running may not be the one the database actually provides; the workload's vulnerability to specific anomalies determines the required level — and most teams don't enumerate that vulnerability before choosing.
+
+The discipline is to make the choice explicit, per transaction, against a named anomaly set. "Default to serializable for safety" is over-conservative; "default to read committed for performance" is under-safe; "this workload has invariants across rows that are vulnerable to write skew under SI, so this transaction runs at serializable" is the discipline.
+
+The implementation matters as much as the level. A team running on Postgres at "serializable" is using SSI, with commit-time aborts that require retry-loop logic; a team running on MySQL InnoDB at "repeatable read" is getting gap-lock-prevented phantoms unlike the standard. Knowing the specific database's implementation of the chosen level is operational hygiene.
+
+## The Anomaly Catalog
+
+| Anomaly | What it is | Eliminated by |
+|---|---|---|
+| Dirty read | Reading uncommitted data from another transaction | Read committed and above |
+| Non-repeatable read | Same row, different values within transaction | Repeatable read and above |
+| Phantom read | Same range query, different result set | Serializable (and some RR implementations) |
+| Lost update | Read-modify-write race between two transactions | Serializable; mitigated by SELECT FOR UPDATE |
+| Write skew | Two transactions act on a snapshot; jointly violate an invariant | Serializable / SSI |
+| Read-only transaction anomaly | Read-only transaction produces inconsistent output | SSI |
+
+The discipline is reading this table for the workload at hand: which of these anomalies, if they occurred, would produce a correctness bug? Pick the lowest level that prevents those.
+
+## Level vs Implementation Matrix
+
+| Level (standard) | Postgres | MySQL InnoDB | SQL Server | Oracle |
+|---|---|---|---|---|
+| Read Uncommitted | Same as read committed | Available; dirty reads | Available | Same as read committed |
+| Read Committed | Default; MVCC | Available | Default | Default; MVCC |
+| Repeatable Read | MVCC; phantoms allowed | Default; gap locks prevent phantoms | Available; lock-based | Same as serializable |
+| Snapshot Isolation | Not directly named (RR is SI-like) | n/a | RCSI option | Default-equivalent |
+| Serializable | SSI (since 9.1) | Lock-based | Lock-based with range locks | Snapshot + checks |
+
+Naming is not consistent; reading the database's documentation is required.
+
+## The Choice Procedure
+
+1. **Enumerate the workload's anomaly vulnerabilities.** For each transaction class: which anomalies would produce a correctness bug if they occurred? (A balance-decrement is vulnerable to lost updates. A doctor-on-call check is vulnerable to write skew. A read-only report is vulnerable to non-repeatable reads if cross-table consistency matters.)
+
+2. **Find the lowest level that prevents the named anomalies.** Walk the anomaly catalog upward. Stop at the level that prevents all vulnerabilities.
+
+3. **Verify the database's implementation actually prevents what the standard says it should.** Read the specific database's documentation; don't assume the standard's table is what your database does.
+
+4. **Add explicit locking where the level alone is insufficient.** `SELECT FOR UPDATE`, advisory locks, and optimistic-concurrency tokens are tools for targeted correctness without raising the whole transaction's isolation level.
+
+5. **Handle the retry-required failure modes.** SSI can abort transactions at commit; the application must retry. Repeatable read can throw serialization errors; the application must handle. Higher isolation introduces new failure modes, not zero failure modes.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] The team can name the database's default isolation level and the level's implementation mechanism (MVCC, SSI, locking). Default assumption is not relied on.
+- [ ] For each transaction class, the team has enumerated the anomaly vulnerabilities and chosen an isolation level that prevents them. Levels are not picked by reflex.
+- [ ] Explicit locking (SELECT FOR UPDATE, advisory locks) is used where targeted correctness is needed without upgrading the whole transaction.
+- [ ] Application code that runs at SSI or repeatable-read with serialization errors has retry-on-conflict logic. Higher isolation's failure modes are handled, not ignored.
+- [ ] Write skew vulnerability is recognized for transactions that read X and write Y based on it under SI; either the level is upgraded to serializable or explicit locking guards the read set.
+- [ ] Read-only transactions that join multiple tables run at at least repeatable read or snapshot isolation when cross-table consistency matters.
+- [ ] The specific database's documentation has been consulted, not the SQL standard's level names. The team knows the specific anomaly set the level actually prevents.
+- [ ] Isolation-level changes in production are treated as behavior changes, not config changes. New failure modes are handled before the change rolls.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Explaining the broader ACID frame | `acid-fundamentals` | acid-fundamentals owns the four-property frame; this owns the I axis |
+| Reasoning about replica agreement across nodes | `cap-theorem-tradeoffs` | CAP is the distributed-systems frame; this is the single-cluster transactional frame |
+| Tuning a slow query's performance | `query-optimization` | query-optimization owns performance; this owns concurrency correctness |
+| Choosing an index for a query | `indexing-strategy` | indexing owns retrieval performance; this owns concurrent execution |
+| Designing schema and access patterns | `data-modeling` | data-modeling owns design; this owns the concurrency contract |
+| Coordinating across multiple transactions or services | sagas / distributed locks (out of this skill's scope) | cross-transaction coordination is a different problem |
+
+## Key Sources
+
+- Berenson, H., Bernstein, P., Gray, J., Melton, J., O'Neil, E., & O'Neil, P. (1995). ["A Critique of ANSI SQL Isolation Levels"](https://dl.acm.org/doi/10.1145/568271.223785). *SIGMOD 1995*. Foundational paper formalizing the anomalies and showing the SQL standard's looseness; required reading for serious treatment of isolation.
+- Adya, A. (1999). ["Weak Consistency: A Generalized Theory and Optimistic Implementations for Distributed Transactions"](http://pmg.csail.mit.edu/papers/adya-phd.pdf). PhD thesis, MIT. Extends Berenson et al. with a more rigorous framework; basis for modern isolation reasoning.
+- Cahill, M. J., Röhm, U., & Fekete, A. D. (2008). ["Serializable Isolation for Snapshot Databases"](https://dl.acm.org/doi/10.1145/1376616.1376690). *SIGMOD 2008*. The paper that introduced Serializable Snapshot Isolation (SSI); the basis of Postgres's serializable mode since 9.1.
+- Fekete, A., Liarokapis, D., O'Neil, E., O'Neil, P., & Shasha, D. (2005). ["Making Snapshot Isolation Serializable"](https://dl.acm.org/doi/10.1145/1071610.1071615). *ACM TODS*, 30(2). Precursor to the SSI paper; characterization of snapshot isolation's anomaly set.
+- PostgreSQL Global Development Group. ["PostgreSQL Documentation — Transaction Isolation"](https://www.postgresql.org/docs/current/transaction-iso.html). Canonical reference for Postgres's specific isolation implementation; covers SSI behavior and the abort-and-retry contract.
+- Kleppmann, M. (2017). *Designing Data-Intensive Applications*. O'Reilly. Chapter 7 (Transactions) — modern practitioner treatment of all isolation levels, anomalies, and the implementation strategies.
+- Gray, J., & Reuter, A. (1992). *Transaction Processing: Concepts and Techniques*. Morgan Kaufmann. The canonical textbook; deep treatment of locking and concurrency control.
+- Bernstein, P. A., & Goodman, N. (1981). ["Concurrency Control in Distributed Database Systems"](https://dl.acm.org/doi/10.1145/356842.356846). *ACM Computing Surveys*, 13(2). Foundational survey of concurrency-control techniques.
+- MySQL Reference Manual. ["Transaction Isolation Levels"](https://dev.mysql.com/doc/refman/8.0/en/innodb-transaction-isolation-levels.html). Reference for MySQL InnoDB's specific implementation; documents the gap-lock prevention of phantoms at RR.

package/marketplace/skills/type-safety/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: type-safety
+description: "Use when reasoning about types as a quality property of code: what guarantees the type system actually provides, the difference between sound and unsound systems, structural vs nominal typing, type narrowing and exhaustiveness, the runtime/compile-time boundary, and where validation must happen because the type system cannot. Covers TypeScript, Flow, Hindley-Milner languages, and gradual typing in general. Do NOT use for runtime input validation library choice (use api-design for API surface validation; use individual library docs for library mechanics), for SQL type mapping (use data-modeling), or for type system implementation (compilers — out of scope)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"quality\",\"domain\":\"quality/types\",\"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\":\"[\\\\\\\"type safety\\\\\\\",\\\\\\\"TypeScript\\\\\\\",\\\\\\\"sound type system\\\\\\\",\\\\\\\"unsound type system\\\\\\\",\\\\\\\"structural typing\\\\\\\",\\\\\\\"nominal typing\\\\\\\",\\\\\\\"type narrowing\\\\\\\",\\\\\\\"exhaustiveness check\\\\\\\",\\\\\\\"gradual typing\\\\\\\",\\\\\\\"runtime boundary\\\\\\\"]\",\"triggers\":\"[\\\\\\\"is this type-safe\\\\\\\",\\\\\\\"should this be `any` or `unknown`\\\\\\\",\\\\\\\"exhaustiveness check\\\\\\\",\\\\\\\"narrowing\\\\\\\",\\\\\\\"where does validation belong\\\\\\\"]\",\"examples\":\"[\\\\\\\"review whether this discriminated union has an exhaustiveness check at the switch\\\\\\\",\\\\\\\"decide whether to use `any` or `unknown` for this third-party JSON payload\\\\\\\",\\\\\\\"explain why TypeScript's `as` cast doesn't actually validate at runtime\\\\\\\",\\\\\\\"design where Zod (or any validator) parses at the application boundary\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"implement HMAC verification for an inbound webhook (use webhook-integration)\\\\\\\",\\\\\\\"design the JSON shape of an API endpoint (use api-design)\\\\\\\",\\\\\\\"choose between Postgres column types (use data-modeling)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"api-design\\\\\\\",\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"code-review\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"api-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"api-design owns the external request/response surface; type-safety owns the discipline of expressing internal program correctness as types.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"testing-strategy owns the runtime verification of behavior; type-safety owns the compile-time verification of structure. They cover different failure modes.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"data-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"data-modeling owns persistence and entity shape; type-safety owns the in-memory type contracts that consume that shape.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"code-review\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Type safety is to programs what a passport check is to international travel — the document (type annotation) certifies identity within the issuing country's records, but on the way through customs (the I/O boundary), the document is re-verified against the actual traveler, and any mismatch is rejected before they enter the trusted zone.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Type safety is the property of a program in which type errors — operations applied to values of the wrong kind — are detected before they cause incorrect behavior. A type system provides type safety to the extent that it formally rules out classes of errors at compile time. A sound type system rules out all errors of the kinds it tracks; an unsound system rules out some but allows others through escape hatches.\\\\\\\",\\\\\\\"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/type-safety/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/type-safety/SKILL.md
+---
+
+# Type Safety
+
+## Coverage
+
+The discipline of using a type system to rule out classes of runtime errors before they occur. Covers what soundness means and where TypeScript (and other gradual systems) is unsound, structural vs nominal typing, type narrowing and exhaustiveness checking, the runtime boundary problem, the difference between `any` and `unknown`, when to use type assertions (rarely) and when to validate (always at I/O boundaries), and the connection to runtime validation libraries.
+
+## Philosophy
+
+Types are claims about values; type-checking is proof-checking. A program that compiles is a program whose claims have been internally consistent — but a program is more than its compiler. Values that arrive from outside the program (HTTP responses, environment variables, parsed JSON, untrusted user input) have no type until you parse them, no matter what type annotation sits next to them.
+
+The discipline of type-safety is to take the compile-time guarantees seriously and to know exactly where they stop. A codebase that pretends `JSON.parse(x) as User` is safe has confused a syntactic claim with a semantic guarantee. A codebase that validates at the boundary and trusts the type inside has correctly aligned the two layers.
+
+In gradual systems like TypeScript, the discipline includes treating escape hatches (`any`, `as`, `// @ts-ignore`) as exceptional, justified, and rare — not as the default response to a type error.
+
+## Soundness — What the System Actually Promises
+
+| System | Soundness | Where it leaks |
+|---|---|---|
+| TypeScript | Unsound (by design) | `any`, `as`, function bivariance, ambient declarations, type assertions, `Object.keys()` typed as `string[]`, array `.find()` returning a `T` not `T \| undefined` (without strict flag), unchecked `noUncheckedIndexedAccess`, mutable arrays in covariant positions |
+| Flow | Unsound | Similar escape hatches; less broadly adopted |
+| Python + mypy | Unsound (gradual) | `Any`, `cast`, dynamic-only constructs |
+| Java | Sound for types, unsound for null | NullPointerException; generics erased at runtime |
+| C# | Mostly sound | Reflection, `dynamic` |
+| Go | Sound for types, structural interfaces | Empty interface (`interface{}`) is the escape hatch; type assertions panic on failure |
+| Rust | Sound (memory + types) | `unsafe` blocks are documented escape hatches |
+| Haskell | Sound (within purity) | `unsafePerformIO`, FFI |
+
+**Practical TypeScript stance:** Enable strict mode (`strict: true`), enable `noUncheckedIndexedAccess`, enable `noImplicitAny`. These flags close the most common leakage points. Without them, the system's guarantees are substantially weaker than developers assume.
+
+## Narrowing
+
+Narrowing is the type checker's mechanism for refining a broad type based on control-flow evidence. Use it instead of casts.
+
+```typescript
+function process(x: string | number | null) {
+  if (x === null) return;            // narrows to string | number
+  if (typeof x === 'string') {        // narrows to string
+    return x.toUpperCase();
+  }
+  // here x is narrowed to number
+  return x.toFixed(2);
+}
+```
+
+| Narrowing technique | Use when |
+|---|---|
+| `typeof x === '...'` | Distinguishing primitives |
+| `x instanceof Class` | Distinguishing class instances |
+| `'field' in x` | Distinguishing discriminated objects |
+| `x === literal` | Distinguishing literal types |
+| Discriminated union via tag field | Designed-in narrowing for ADTs |
+| User-defined type guards (`x is T`) | Custom predicates |
+| `Array.isArray(x)` | Array vs non-array |
+
+Discriminated unions are the strongest pattern:
+
+```typescript
+type Result =
+  | { ok: true; value: User }
+  | { ok: false; error: string };
+
+function handle(r: Result) {
+  if (r.ok) return r.value;  // narrows; `r.error` is not accessible here
+  return r.error;            // narrowed to the error branch
+}
+```
+
+## Exhaustiveness Checking
+
+Force the compiler to verify that all cases of a union are handled. The pattern uses an unreachable `never` branch.
+
+```typescript
+type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';
+
+function describe(m: Method): string {
+  switch (m) {
+    case 'GET':    return 'safe';
+    case 'POST':   return 'mutation';
+    case 'PUT':    return 'idempotent replacement';
+    case 'DELETE': return 'idempotent removal';
+    default: {
+      const _exhaustive: never = m;  // compile error if a case is missing
+      throw new Error(`unhandled: ${_exhaustive}`);
+    }
+  }
+}
+```
+
+When a new variant is added to `Method`, the `never` assignment fails to type-check — the compiler points at every missing branch. This converts a runtime "unhandled case" bug into a compile-time error.
+
+## The Runtime Boundary
+
+Type information stops at the runtime boundary. Values crossing in must be parsed; values crossing out are serialized.
+
+| Boundary | Risk | Discipline |
+|---|---|---|
+| `JSON.parse(networkResponse)` | Returns `any` (or `unknown` with stricter typing); no validation | Parse with a schema (Zod, io-ts) before trusting the type |
+| `process.env.X` | All env vars are `string \| undefined`, but TypeScript may type them as `string` via globals | Validate at startup with a typed env config object |
+| `localStorage.getItem(k)` | Returns `string \| null`, but the contents are untyped | Parse + validate before use |
+| `fetch(url).then(r => r.json())` | The promise resolves with `any` | Validate against an expected schema |
+| Database driver results | Library-typed; trust depends on the library's contract | Verify the library actually checks types at the boundary |
+| `Function(string)` / `eval` | Arbitrary code; arbitrary types | Avoid; if necessary, type the result as `unknown` |
+
+The pattern: **validate at the boundary; trust the type inside.**
+
+```typescript
+import { z } from 'zod';
+
+const UserSchema = z.object({
+  id: z.string(),
+  email: z.string().email(),
+  createdAt: z.coerce.date(),
+});
+
+type User = z.infer<typeof UserSchema>;
+
+async function fetchUser(id: string): Promise<User> {
+  const raw = await fetch(`/api/users/${id}`).then(r => r.json());
+  return UserSchema.parse(raw);  // throws on validation failure
+}
+// Inside the rest of the program, User is trusted.
+```
+
+## `any` vs `unknown` vs `never`
+
+| Type | Set of values | What you can do with it |
+|---|---|---|
+| `any` | All values | Anything (escape hatch — no checking) |
+| `unknown` | All values | Nothing until you narrow (safe escape hatch) |
+| `never` | No values | Nothing (used for exhaustiveness checks and unreachable code) |
+| `void` | Returned, not consumed | Function return only; the value is "no value worth using" |
+
+Rule: prefer `unknown` over `any` always. The cost is one narrowing step; the benefit is type-safety preserved.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] TypeScript strict mode is enabled (`"strict": true` in tsconfig).
+- [ ] `noUncheckedIndexedAccess` is enabled; array/object access produces `T | undefined`.
+- [ ] No `any` appears in committed code without an inline comment explaining why `unknown` is insufficient.
+- [ ] No `as Type` cast appears without an inline comment explaining why narrowing is insufficient.
+- [ ] Every I/O boundary parses with a runtime validator (Zod, io-ts, valibot, etc.) before the value is treated as typed.
+- [ ] Discriminated unions have an exhaustiveness check at every consumer site.
+- [ ] Public API boundaries (exported functions, route handlers, library entry points) have explicit return types — not just inferred.
+- [ ] `// @ts-ignore` and `// @ts-expect-error` are accompanied by a justification and a tracking comment.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Designing the JSON shape of an API endpoint | `api-design` | api-design owns the external surface contract; this skill owns internal type discipline |
+| Verifying behavior at runtime with tests | `testing-strategy` | testing-strategy owns runtime verification; this skill owns compile-time |
+| Designing database schema and column types | `data-modeling` | data-modeling owns persistence shape; this skill owns in-memory type contracts |
+| Choosing between Zod / io-ts / valibot | individual library docs + `api-design` | Library choice is a tactical decision below this skill |
+| Implementing the compiler / type-checker | language compiler implementation references | Out of scope — this skill is about *using* type systems, not building them |
+
+## Key Sources
+
+- Pierce, B. C. (2002). *Types and Programming Languages*. MIT Press. The canonical textbook. Chapters 1-3 cover untyped lambda calculus, simple types, and the soundness/progress/preservation framework that underpins every type system.
+- Siek, J. G., & Taha, W. (2006). "Gradual Typing for Functional Languages." *Scheme and Functional Programming 2006*. The original gradual typing paper.
+- Siek, J. G., & Vachharajani, M. (2008). "Gradual typing with unification-based inference." *Proceedings of the 2008 symposium on Dynamic languages*. Formalizes the soundness vs ergonomics trade-off in gradual systems.
+- Microsoft. [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html). The reference for TypeScript's type system, including the documented unsoundness in *Type Compatibility* and *Narrowing* chapters.
+- Anders Hejlsberg et al. [TypeScript Design Goals](https://github.com/microsoft/TypeScript/wiki/TypeScript-Design-Goals). Explicit acknowledgement that TypeScript trades soundness for ergonomics: "non-goals: apply a sound or 'provably correct' type system."
+- Curry, H. B., & Feys, R. (1958). *Combinatory Logic, Volume I*. Original work on the Curry-Howard correspondence — types as propositions, programs as proofs.

package/marketplace/skills/typography-system/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: typography-system
+description: "Use when designing a typography system — typeface selection and pairing, modular type scale, vertical rhythm, line-height and measure rules, and web font delivery (subsetting, font-display, variable fonts). Do NOT use for body copy writing, single-headline font pairing, or non-text design tokens."
+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\":\"[\\\\\\\"type scale\\\\\\\",\\\\\\\"typeface pairing\\\\\\\",\\\\\\\"vertical rhythm\\\\\\\",\\\\\\\"line height\\\\\\\",\\\\\\\"measure line length\\\\\\\",\\\\\\\"web font delivery\\\\\\\",\\\\\\\"variable fonts\\\\\\\",\\\\\\\"font-display swap\\\\\\\",\\\\\\\"font subsetting\\\\\\\",\\\\\\\"modular scale\\\\\\\",\\\\\\\"typographic tokens\\\\\\\",\\\\\\\"opentype features\\\\\\\"]\",\"triggers\":\"[\\\\\\\"typography system\\\\\\\",\\\\\\\"type scale\\\\\\\",\\\\\\\"font pairing\\\\\\\",\\\\\\\"variable fonts\\\\\\\",\\\\\\\"vertical rhythm\\\\\\\"]\",\"examples\":\"[\\\\\\\"Build a type scale with seven steps using a 1.25 ratio and assign each step to a semantic token (display, h1, body, caption)\\\\\\\",\\\\\\\"Pair a serif display face with a sans-serif text face and document when to use each\\\\\\\",\\\\\\\"Self-host a variable font with WOFF2 subsetting and font-display: swap\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"Write the headline copy for the landing page\\\\\\\",\\\\\\\"Pick the brand's primary color\\\\\\\",\\\\\\\"Decide where the headline component lives in the folder structure\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"visual-hierarchy\\\\\\\",\\\\\\\"visual-design-foundations\\\\\\\",\\\\\\\"theme-system-design\\\\\\\",\\\\\\\"layout-composition\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"visual-hierarchy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"visual-hierarchy decides how to deploy type as an ordering signal on a given surface; this skill defines the scale and faces that get deployed.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"theme-system-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"theme-system-design covers how typography tokens are layered and switched; this skill produces the typographic decisions inside them.\\\\\\\"}]}\",\"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/typography-system/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/typography-system/SKILL.md
+---
+
+# Typography System
+
+## Coverage
+A typography system has four components: a small set of typefaces (often one for display, one for text, optionally one monospaced), a modular scale of sizes, a set of weight and style variants per face, and rules for line-height, letter-spacing, and measure (characters per line). Each component is encoded as design tokens — font-family-text, font-size-100 through font-size-900, line-height-tight/normal/loose, letter-spacing-tight/normal — and consumed by components through semantic tokens (display, heading-1, body, caption).
+
+Type scales are usually built from a single ratio applied iteratively to a base size. Common ratios: 1.125 (major second, subtle, content-dense UIs), 1.2 (minor third), 1.25 (major third, common default), 1.333 (perfect fourth), 1.414 (augmented fourth), 1.5 (perfect fifth, loud), 1.618 (golden ratio, very loud). Most production systems use 5–9 steps; more steps dilute the visual distinction between adjacent levels.
+
+Line-height and measure are coupled. Longer measures need taller line-heights to keep the eye from skipping lines; shorter measures need tighter line-heights to avoid feeling sparse. The widely-cited target is 45–75 characters per line for body text, with line-height between 1.4 and 1.6 for body and 1.1–1.3 for display. Letter-spacing (CSS letter-spacing / tracking) generally tightens at large sizes (-0.02em or less at display sizes) and stays neutral at body sizes; uppercase text benefits from positive tracking (+0.05em or more) for legibility.
+
+Variable fonts (OpenType font-variations) deliver multiple weights, widths, and optical sizes in a single file via continuous axes (wght 100–900, wdth, opsz, etc.), exposed in CSS via font-variation-settings and font-weight: <number>. They reduce HTTP requests and enable weight as a continuous design decision. Web font delivery best practices: WOFF2 format (universally supported, ~30% smaller than WOFF); subset to Latin or the languages actually used (Google Fonts CSS API does this automatically; self-hosted fonts use pyftsubset or fonttools); font-display: swap to render fallback text immediately and swap in the web font when loaded; preload the most-used font files with <link rel="preload" as="font" crossorigin>; use size-adjust, ascent-override, descent-override, and line-gap-override on the fallback @font-face to match metrics and minimize cumulative layout shift.
+
+## Philosophy
+Restraint is the practice. One text face and one display face cover most product needs; a third is a deliberate choice that requires justification. Each additional typeface costs bandwidth, hierarchy clarity, and rendering consistency across operating systems.
+
+Typography is the densest carrier of brand. A wordmark, a heading face, and a body face shape voice more than any color does. Treat the choice of faces with the same seriousness as the choice of brand color, and treat the system around them — scale, rhythm, measure — as the structure that makes the choices work across surfaces.
+
+## Verification
+- The system uses at most three typefaces (display, text, monospace); each is justified by a use that the others cannot serve.
+- Type scale steps are derived from a single ratio applied to a base size; sizes are not picked individually.
+- Body text measure falls within 45–75 characters on the most common viewport widths; verified by inspecting actual rendered lines, not assumed.
+- Web fonts are served as WOFF2, subset to required glyphs, with font-display: swap and metrics-matched fallback @font-face to minimize layout shift.
+- Cumulative Layout Shift attributable to web font loading is below 0.1 on a representative page.
+- Variable fonts (where used) load a single file and access weight/width through font-variation-settings or numeric font-weight, not separate files per weight.
+- Headings and body share a consistent vertical rhythm; line-heights and margins snap to a baseline grid (typically a 4px or 8px subgrid).
+
+## Do NOT Use When
+- The task is writing copy. Typography systems shape how copy reads; they do not produce copy.
+- The decision is a one-off pairing for a single graphic or asset with no system implications.
+- The work is color, spacing, or motion tokens. Use color-system-design or visual-design-foundations.
+- The concern is how typography tokens reach components and switch between themes. Use theme-system-design.
+- You are debugging a single rendering issue (font kerning, ligature behavior in a specific browser) without a system change. That is browser-specific debugging.

package/marketplace/skills/usability-testing/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: usability-testing
+description: "Use when observing real users attempting tasks on a prototype or live product to surface usability issues — moderated or unmoderated, think-aloud protocol, task scenarios, severity rating, sample sizing per Nielsen's heuristics. Do NOT use for automated test suites, code coverage analysis, CI pipelines, unit/integration testing, or any engineering verification — those are testing-strategy concerns, not human-behavior observation."
+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\":\"[\\\\\\\"think aloud protocol\\\\\\\",\\\\\\\"task scenario\\\\\\\",\\\\\\\"moderated usability test\\\\\\\",\\\\\\\"unmoderated test\\\\\\\",\\\\\\\"severity rating\\\\\\\",\\\\\\\"five user rule\\\\\\\",\\\\\\\"formative testing\\\\\\\",\\\\\\\"summative testing\\\\\\\",\\\\\\\"hallway test\\\\\\\",\\\\\\\"moderator neutrality\\\\\\\",\\\\\\\"usability heuristics\\\\\\\",\\\\\\\"SUS score\\\\\\\",\\\\\\\"task success rate\\\\\\\",\\\\\\\"critical incident\\\\\\\"]\",\"triggers\":\"[\\\\\\\"usability test\\\\\\\",\\\\\\\"think aloud\\\\\\\",\\\\\\\"test this prototype\\\\\\\",\\\\\\\"task scenarios\\\\\\\",\\\\\\\"test with users\\\\\\\"]\",\"examples\":\"[\\\\\\\"Write three task scenarios for a usability test of this onboarding flow.\\\\\\\",\\\\\\\"How many participants do I need for a formative round on this prototype?\\\\\\\",\\\\\\\"Review my moderator script for neutrality and leading prompts.\\\\\\\",\\\\\\\"Rate the severity of these eight usability findings using Nielsen's scale.\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"Add unit tests for the order-total calculation function.\\\\\\\",\\\\\\\"Set up the CI pipeline for the new repo.\\\\\\\",\\\\\\\"Run a load test against the checkout API.\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"prototyping\\\\\\\",\\\\\\\"user-research\\\\\\\",\\\\\\\"research-synthesis\\\\\\\",\\\\\\\"design-thinking\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"testing-strategy is an engineering practice for automated test suites that verify code behavior against specifications. usability-testing is a research practice for observing humans interacting with artifacts. The shared word 'testing' is the only thing in common.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"a11y\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"a11y covers accessibility conformance criteria (WCAG, screen reader behavior, keyboard operability). usability-testing can include accessibility-focused sessions but its scope is broader and its method is empirical observation rather than spec conformance.\\\\\\\"}]}\",\"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/usability-testing/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/usability-testing/SKILL.md
+---
+
+# Usability Testing
+
+## Coverage
+Usability testing covers the evaluative research practice of watching people attempt realistic tasks on a prototype or product, then identifying the obstacles they encounter. The dominant method is the **think-aloud protocol** (Ericsson & Simon), where participants narrate their thoughts as they work, surfacing the mental model they are using and the points where it diverges from the design. Sessions are organized around **task scenarios** — short narratives that frame a goal without prescribing the steps ("you want to find out how much you owe in taxes this quarter") — and a **moderator** who maintains neutrality, resists answering questions, and prompts only with open-ended interventions like "what are you thinking now?" or "what did you expect to happen?".
+
+The skill covers **sample sizing**. The widely-cited Nielsen/Landauer "5-user rule" estimates that 5 users surface ~85% of major usability problems for a homogeneous user group on a discrete task, with steeply diminishing returns afterward. The rule has important limits: it applies per distinct user segment, per discrete task scope, and to **formative** (iterative diagnostic) testing — not to **summative** (benchmark) studies, which require much larger samples for valid statistical comparison. Misapplying the 5-user rule to summative claims is a common error.
+
+Findings are organized by **severity rating** (Nielsen's 0–4 scale: cosmetic, minor, major, catastrophic) so the team can triage. **Task success rate**, **time on task**, and standardized instruments like **SUS** (System Usability Scale, Brooke 1996) provide quantitative complements when needed. The practice distinguishes **moderated** sessions (richer data, higher cost, requires scheduling) from **unmoderated** tools (lower cost, scales to dozens of sessions, sacrifices the moderator's ability to follow up on surprises).
+
+The skill also covers what NOT to do in a session: leading prompts, defending the design, explaining how the design "is supposed to work" when the participant gets stuck, and over-fitting interpretations to a single dramatic finding from one participant.
+
+## Philosophy
+Usability testing is built on a humbling claim: designers and engineers cannot reliably predict where users will struggle. The mental models that make a design feel obvious to its creators are exactly the models a fresh user lacks, and only direct observation closes that gap. The discipline rejects "I think users will understand this" in favor of "we watched users; here is what happened." Each session that confirms the design entirely is mildly suspicious — either the tasks were too easy or the moderator was unintentionally helping.
+
+The practice is opinionated about moderator behavior. The moderator's job is to be uninteresting — to let the silence sit, to let the participant struggle long enough for the obstacle to become visible, to not rescue. This is hard because the social instinct is to help, and the design instinct is to defend. A moderator who explains the design after a participant gets stuck has destroyed the evidence; the obstacle the participant just encountered is the finding, and it cannot be re-observed in that session.
+
+## Verification
+- Tasks are written as goals, not as instructions — a participant could complete the task without seeing the design first; "find out how much you owe" not "click the Tax Summary tab and then click View Details."
+- The moderator script contains no leading prompts and no defensive explanations; the moderator's most common utterances are "what are you thinking?" and silence.
+- Findings are rated by severity, not just listed; the team can identify the catastrophic issues distinctly from cosmetic ones.
+- Sample size matches the claim type — 5 users for formative diagnostic findings is defensible; for summative or benchmark claims, sample size is justified separately.
+- At least one finding contradicts a designer or PM expectation; if every finding confirms prior beliefs, the tasks were likely too constrained or the moderation too helpful.
+- Recordings or detailed notes preserve specific participant behavior so synthesis works from observation, not from moderator impressions.
+
+## Do NOT Use When
+- The target is automated verification of code correctness — use **testing-strategy** for unit, integration, and end-to-end engineering tests.
+- The goal is to discover what users need before any artifact exists — use **user-research** for generative interviews and contextual studies.
+- The artifact has not yet been built or sketched — build a prototype first via **prototyping**, then test it.
+- The question requires statistical significance across a large population (benchmarking, A/B comparison) — usability testing surfaces issues; statistical comparison needs larger summative methods or experimentation.
+- The evaluation is purely about accessibility conformance to a specification — use **a11y** for WCAG/ARIA conformance review; usability testing complements this with empirical observation of assistive-tech users but is not a conformance audit.
+- The output should be themes from a corpus of completed sessions — move to **research-synthesis** for affinity mapping and insight extraction.

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

@@ -0,0 +1,43 @@
+---
+name: user-research
+description: "Use when planning or conducting generative qualitative research with real users — interviews, contextual inquiry, ethnographic observation, diary studies — to learn what people do, think, and need in their own context. Do NOT use for analytics review, survey statistics, A/B test interpretation, or agent-side intent classification — those are different research practices entirely."
+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\":\"[\\\\\\\"user interviews\\\\\\\",\\\\\\\"contextual inquiry\\\\\\\",\\\\\\\"ethnographic observation\\\\\\\",\\\\\\\"diary study\\\\\\\",\\\\\\\"generative research\\\\\\\",\\\\\\\"qualitative research\\\\\\\",\\\\\\\"interview guide\\\\\\\",\\\\\\\"leading questions\\\\\\\",\\\\\\\"master-apprentice model\\\\\\\",\\\\\\\"in-context observation\\\\\\\",\\\\\\\"field study\\\\\\\",\\\\\\\"listening for needs\\\\\\\",\\\\\\\"five whys interview\\\\\\\"]\",\"triggers\":\"[\\\\\\\"interview users\\\\\\\",\\\\\\\"user research plan\\\\\\\",\\\\\\\"what to ask users\\\\\\\",\\\\\\\"contextual inquiry\\\\\\\",\\\\\\\"diary study\\\\\\\"]\",\"examples\":\"[\\\\\\\"Draft an interview guide for SMB founders adopting their first accounting software.\\\\\\\",\\\\\\\"How do I observe ICU nurses on shift without disturbing the workflow?\\\\\\\",\\\\\\\"Review my interview script for leading questions and solution-prompts.\\\\\\\",\\\\\\\"Plan a two-week diary study for commuters using public transit apps.\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"Analyze last quarter's NPS results and produce a dashboard.\\\\\\\",\\\\\\\"Classify whether this agent request from the user is high-risk before executing.\\\\\\\",\\\\\\\"Set up an A/B test of two onboarding flows.\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"problem-framing\\\\\\\",\\\\\\\"research-synthesis\\\\\\\",\\\\\\\"usability-testing\\\\\\\",\\\\\\\"design-thinking\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"intent-recognition\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"intent-recognition classifies an agent request's risk level at runtime from the agent's perspective. user-research investigates real human users' goals, contexts, and needs through fieldwork — these are entirely different practices that share only the word 'intent'.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"usability-testing\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"usability-testing is evaluative — it watches users attempt tasks on an artifact to find usability defects. user-research is generative — it studies users before any artifact exists, to discover needs and context.\\\\\\\"}]}\",\"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/user-research/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/user-research/SKILL.md
+---
+
+# User Research
+
+## Coverage
+User research covers the generative qualitative methods that surface what people do, think, feel, and need — typically before a solution exists. The core methods are **semi-structured interviews** (Steve Portigal, Tomer Sharon), **contextual inquiry** with its master-apprentice stance (Beyer & Holtzblatt), **ethnographic observation** in the user's actual environment, **diary studies** for behaviors that unfold over days or weeks, and **intercept studies** for in-the-moment reactions. Each method trades off depth, naturalism, scale, and scheduling cost differently; choosing well depends on what kind of evidence the project needs.
+
+The skill includes the craft of **interview construction**: opening with broad context questions, moving to specific recent episodes ("tell me about the last time you…"), avoiding hypotheticals ("would you use…") and leading prompts ("don't you find it frustrating that…"), and using silence as a tool. The **critical incident technique** (Flanagan) and **5 Whys** laddering are used in-session to push past surface answers. The practice also includes what NOT to do: solution-prompting, confirmation seeking, anchoring on the interviewer's own hypothesis, interrupting, and steering toward a preferred narrative.
+
+Contextual methods extend interviews into the user's environment. **Contextual inquiry** treats the user as the master craftsperson and the researcher as an apprentice asking clarifying questions while the user works. **Fly-on-the-wall observation** removes the researcher's questions entirely. **Shadowing** follows a single user through their day. Each makes different trade-offs between naturalism (less intrusion → more authentic behavior) and depth (more questions → richer interpretation).
+
+Diary and longitudinal methods cover behaviors that do not surface in a single session. Daily prompts, photo diaries, and experience sampling (Csíkszentmihályi) capture in-context moments and reduce recall bias.
+
+## Philosophy
+User research is harder than it looks because the natural conversational instincts that make humans good company — finishing each other's sentences, offering sympathy, confirming what the other person seems to want to hear — actively destroy data quality. The discipline trains interviewers to do the opposite: leave silence intact, ask the participant to "say more about that" instead of paraphrasing, and treat surprise as the signal that the conversation is producing new information.
+
+The practice is grounded in a specific epistemological claim: people are unreliable narrators of their own behavior, especially when asked hypothetical or future-tense questions, but they are reasonably reliable when describing concrete recent episodes. This is why methods skew toward "tell me about the last time" over "would you ever" — episodic memory is more trustworthy than self-prediction. It is also why observation outranks interview when the project can afford it: what people do and what people say they do are routinely different.
+
+## Verification
+- The interview guide contains no leading, hypothetical, or solution-prompting questions; every question can be answered by describing a real past event.
+- Sessions are recorded (with consent) so synthesis works from primary data, not interviewer memory.
+- At least one finding from the research contradicts a hypothesis the team held going in — if every finding confirms prior beliefs, the questions were probably leading.
+- For contextual studies, observation happened in the user's real environment, not a lab simulation of it.
+- Sample composition is documented and matches the recruitment criteria — including who was excluded and why.
+- The researcher can name what they don't yet know after the session, not just what they confirmed.
+
+## Do NOT Use When
+- The question is quantitative (how many, what percentage, statistical significance) — use survey or analytics methods, not generative interviews.
+- A working artifact already exists and the question is "does this artifact work for users" — use **usability-testing**.
+- The team needs to make sense of research that has already been collected — use **research-synthesis**.
+- The "user" is an agent or system, not a human — interview methods do not transfer to non-humans.
+- The team has not yet agreed on what problem they are studying — return to **problem-framing** first, then design research to investigate the framed problem.
+- The need is to evaluate a feature against a hypothesis with a control group — use experimental methods (A/B, RCT), not interviews.