@skill-graph/cli 0.5.6

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

@@ -0,0 +1,265 @@
+---
+name: suspense-patterns
+description: "Use when designing or reviewing React Suspense usage: where to place Suspense boundaries to control loading granularity, the difference between Suspense for data fetching and Suspense for code splitting, how Suspense interacts with Server Components for streaming HTML, how error boundaries pair with Suspense (and why they must be distinct components), the relationship between Suspense and React's transition APIs (useTransition, startTransition), and the design rules that prevent waterfall fetches, layout shift, and SEO regressions. Covers React 18+ and 19's `use` hook for unwrapping Promises in Client Components. Do NOT use for general React rendering strategy choice (use rendering-models), for the underlying hook primitives (use hooks-patterns), for streaming protocols beyond Suspense (use streaming-architecture), or for Server Component design (use server-components-design)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/frontend\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"React Suspense\\\\\\\",\\\\\\\"Suspense boundary\\\\\\\",\\\\\\\"streaming HTML\\\\\\\",\\\\\\\"loading.tsx Next.js\\\\\\\",\\\\\\\"useTransition\\\\\\\",\\\\\\\"startTransition\\\\\\\",\\\\\\\"use hook React 19\\\\\\\",\\\\\\\"error boundary with Suspense\\\\\\\",\\\\\\\"Suspense waterfall\\\\\\\",\\\\\\\"parallel data fetching\\\\\\\",\\\\\\\"granular loading states\\\\\\\"]\",\"triggers\":\"[\\\\\\\"where should I put the Suspense boundary\\\\\\\",\\\\\\\"why is my page waiting for the slowest query\\\\\\\",\\\\\\\"how do I show partial loading states\\\\\\\",\\\\\\\"Suspense vs loading.tsx\\\\\\\",\\\\\\\"do I need useTransition here\\\\\\\",\\\\\\\"error boundary not catching\\\\\\\",\\\\\\\"data is waterfalling instead of parallel\\\\\\\"]\",\"examples\":\"[\\\\\\\"design a dashboard that streams three independent widgets in as their data resolves, with skeleton fallbacks for each\\\\\\\",\\\\\\\"decide whether a tab switch should use useTransition or a top-level Suspense fallback\\\\\\\",\\\\\\\"diagnose why a Suspense boundary is showing its fallback on every prop change\\\\\\\",\\\\\\\"pair a Suspense boundary with an ErrorBoundary so failed fetches show an error UI while successful ones stream in\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"choose between Server Components and Client Components (use server-components-design)\\\\\\\",\\\\\\\"design the dependency array for a useEffect that fetches data (use hooks-patterns)\\\\\\\",\\\\\\\"pick the streaming protocol for an LLM response (use streaming-architecture)\\\\\\\",\\\\\\\"decide between SSR and SSG for a marketing page (use rendering-models)\\\\\\\",\\\\\\\"design the streaming protocol itself — SSE, HTTP/2, chunked transfer-encoding (use streaming-architecture)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"server-components-design\\\\\\\",\\\\\\\"hooks-patterns\\\\\\\",\\\\\\\"streaming-architecture\\\\\\\",\\\\\\\"rendering-models\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"server-components-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"server-components-design owns the discipline of which work runs on the server side of the RSC boundary; suspense-patterns owns the orthogonal discipline of where to place Suspense boundaries within a tree (RSC or Client).\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"hooks-patterns\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"hooks-patterns covers state, effects, and the closure model on Client Components; suspense-patterns covers the boundary-level loading-state model that operates on whole subtrees.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"code-review\\\\\\\",\\\\\\\"rendering-models\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Suspense boundaries are to React's component tree what a restaurant's seating policy is to a multi-course meal — the policy decides whether courses arrive together (boundary around the whole meal, everyone waits for the slowest dish) or course-by-course (boundary per dish, each appears when ready). The component (the kitchen) just signals 'this course needs more time'; the boundary (the maître d') decides who waits for what and what placeholder shows in the meantime.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"A Suspense boundary is a React component that catches a thrown Promise (or, in RSC, an unresolved async render) from anywhere in its descendant tree and shows a fallback UI until the Promise resolves. It is a declarative loading-state mechanism: the consuming component requests data without knowing whether it is loading, and the ancestor Suspense boundary handles the rendering branch.\\\\\\\",\\\\\\\"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/suspense-patterns/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/suspense-patterns/SKILL.md
+---
+
+# Suspense Patterns
+
+## Coverage
+
+The discipline of placing and pairing Suspense boundaries: how a Suspense boundary catches a thrown Promise (or unresolved async RSC) and renders a fallback, how boundary *placement* determines what waits for what, how Suspense composes with error boundaries (and why they cannot be the same component), how `useTransition` and `startTransition` change the boundary's behavior on updates, how Suspense for code splitting (`React.lazy`) and Suspense for data fetching share the same mechanism, and how Next.js App Router's `loading.tsx` is a sugar for a route-level Suspense boundary. The skill covers React 18+ semantics throughout and the React 19 `use` hook that lets Client Components unwrap Promises directly.
+
+## Philosophy
+
+The classic React loading-state pattern was conditional rendering: each component owned an `isLoading` flag, returned a spinner or skeleton, and re-rendered when its data resolved. That pattern is local and imperative. It puts every component in the position of deciding *how* to communicate "I'm waiting" and *where* in its render output the placeholder goes. It does not compose; two sibling components loading in parallel produce two independent spinners with no coordinated layout.
+
+Suspense inverts the responsibility. The component that needs data *throws* a Promise (or, in the case of RSC, the renderer encounters an unresolved `await`). The Suspense boundary catches the throw and renders a fallback for the entire subtree. The component itself only has to declare "I need this data" — never "I might not have it yet." The boundary, declared once, owns the placeholder UI for everything below it. The semantics compose: nested Suspense boundaries let outer fallbacks resolve first while inner sections continue to wait.
+
+This is a different mental model than try/catch for asynchronicity. The thrown Promise is not an error — it is a signal that "this render cannot complete until this Promise resolves, please show the nearest Suspense fallback and try again when it does." React reconciles the wait at the boundary; the component code reads as if the data were already there.
+
+The design discipline of Suspense is therefore about **boundary placement**, not about loading-state plumbing. The questions are: *what content should appear together?* (one boundary around them all) and *what content should stream in independently?* (separate boundaries around each). The boundary is a hierarchy decision in the UI, not a state machine inside a component.
+
+## Boundary Placement — The Central Design Question
+
+A Suspense boundary catches *any* throw from *any* descendant. The boundary's job is to define a *grouping*: "these things appear together, and either they all show or the fallback shows."
+
+Three placement strategies, each correct in different contexts:
+
+**1. Page-level boundary.** One boundary near the root. The whole page shows a fallback until everything inside resolves.
+
+```tsx
+<Suspense fallback={<PageSkeleton />}>
+  <Header />
+  <Dashboard />
+  <Footer />
+</Suspense>
+```
+
+- **Use when**: the page's value is only meaningful when complete (an onboarding flow, a checkout summary).
+- **Cost**: the slowest part of the page determines the page's perceived load time.
+
+**2. Section-level boundaries.** A boundary around each independent section.
+
+```tsx
+<Header />
+<Suspense fallback={<ChartSkeleton />}>
+  <Chart />        {/* slow query */}
+</Suspense>
+<Suspense fallback={<TableSkeleton />}>
+  <Table />        {/* faster query */}
+</Suspense>
+<Footer />
+```
+
+- **Use when**: each section is independently meaningful and can stream in separately.
+- **Cost**: more visible layout activity as sections pop in.
+
+**3. Leaf-level boundaries.** A boundary on each loading-aware component itself.
+
+```tsx
+<UserList>
+  {users.map(user => (
+    <Suspense key={user.id} fallback={<UserCardSkeleton />}>
+      <UserCard userId={user.id} />
+    </Suspense>
+  ))}
+</UserList>
+```
+
+- **Use when**: you have many parallel slow operations whose orderings don't matter.
+- **Cost**: many small skeletons, potential layout thrash.
+
+The wrong placement is usually too coarse: a single boundary near the page root waits for everything, defeating the streaming benefit. Less commonly, a boundary too fine produces a busy "many spinners" UI. The right granularity matches the page's actual visual hierarchy.
+
+## Parallel vs Waterfall Fetching
+
+Suspense alone does not prevent waterfalls. A waterfall is when fetch B starts only after fetch A resolves, sequentially, when both could have started together.
+
+```tsx
+// WATERFALL — parent awaits, then child fetches
+async function ParentBad() {
+  const a = await fetchA()
+  return <ChildBad a={a} />   // ChildBad starts fetch B only after this point
+}
+
+// PARALLEL — both fetches kicked off at the same render level
+async function ParentGood() {
+  const aPromise = fetchA()
+  const bPromise = fetchB()
+  const [a, b] = await Promise.all([aPromise, bPromise])
+  return <Child a={a} b={b} />
+}
+
+// SUSPENSE-PARALLEL — siblings under separate Suspense boundaries
+function ParentStreaming() {
+  return (
+    <>
+      <Suspense fallback={<A_Skeleton />}><A /></Suspense>
+      <Suspense fallback={<B_Skeleton />}><B /></Suspense>
+    </>
+  )
+}
+```
+
+The pattern: kick off all independent fetches at the same level of the tree, then either `await Promise.all` if you need both before rendering, or wrap each child in its own Suspense boundary if they can stream in independently. A child that fetches its own data is fine — *as long as the parent doesn't `await` something the child depends on first*. Tree depth correlates with waterfall risk; flat trees with siblings starting requests in parallel correlate with optimal streaming.
+
+## Suspense and Error Boundaries
+
+A Suspense boundary catches *thrown Promises*, not thrown Errors. An error boundary catches *thrown Errors*, not Promises. They are different React mechanisms that solve adjacent problems and **must be different components**, but they almost always pair together.
+
+The canonical pair:
+
+```tsx
+<ErrorBoundary fallback={<ErrorUI />}>
+  <Suspense fallback={<LoadingUI />}>
+    <DataLoadingComponent />
+  </Suspense>
+</ErrorBoundary>
+```
+
+Order matters:
+
+- ErrorBoundary outside Suspense: the error UI replaces the entire group including any Suspense boundaries inside. A failed fetch shows the error UI; the loading state is no longer visible.
+- Suspense outside ErrorBoundary: while loading, the Suspense fallback shows. If the fetch fails, the Suspense fallback unmounts and the error UI takes its place inside.
+
+Most applications want ErrorBoundary on the outside so a failure replaces the loading state cleanly. Putting ErrorBoundary on the inside is appropriate when the loading state should remain visible and only a small portion of the subtree should swap to error UI.
+
+React does not ship a built-in `ErrorBoundary` for function components (as of React 19). Use `react-error-boundary` (Kent C. Dodds) or implement a class component. Server Components' errors are caught by Next.js's `error.tsx` file, which is essentially a route-scoped ErrorBoundary.
+
+## `useTransition`, `startTransition`, and "Stale" Boundaries
+
+By default, a Suspense boundary unmounts its children and shows the fallback whenever any descendant throws a Promise — even on subsequent updates (e.g., a tab switch that triggers a new fetch). This causes the "spinner flicker" anti-pattern: every interaction shows the loading state.
+
+`useTransition` (and `startTransition`) mark an update as non-urgent. React holds the previous render visible while the new render's data is loading, instead of unmounting to the fallback:
+
+```tsx
+function TabPanel({ activeTab }) {
+  return <Content tab={activeTab} />  // suspends on tab change
+}
+
+function Tabs() {
+  const [tab, setTab] = useState('a')
+  const [isPending, startTransition] = useTransition()
+  
+  return (
+    <>
+      <button onClick={() => startTransition(() => setTab('b'))}>
+        {isPending ? 'Loading…' : 'Tab B'}
+      </button>
+      <Suspense fallback={<Skeleton />}>
+        <TabPanel activeTab={tab} />
+      </Suspense>
+    </>
+  )
+}
+```
+
+On the *first* render, the Suspense fallback shows (no previous render to keep). On *subsequent* tab changes triggered through `startTransition`, the previous tab's content stays mounted while the new tab loads, and `isPending` indicates the transition is in flight. The fallback only shows when there is no prior committed render to preserve.
+
+Design rule: wrap user-initiated updates that may trigger Suspense in `startTransition` to avoid flickering fallbacks. Do not wrap initial-load updates in `startTransition`, since there is no previous content to preserve and the boundary will simply not show the fallback when you want it to.
+
+## Suspense in RSC and Next.js App Router
+
+In an RSC tree, Suspense controls streaming HTML granularity. The server flushes everything outside the boundary first, then streams in each boundary's content as it resolves:
+
+```tsx
+// app/dashboard/page.tsx — Server Component
+export default async function Dashboard() {
+  return (
+    <>
+      <Header />                       {/* renders and flushes immediately */}
+      <Suspense fallback={<Skeleton />}>
+        <SlowSection />                {/* streams in when data resolves */}
+      </Suspense>
+    </>
+  )
+}
+```
+
+Next.js App Router provides `loading.tsx` as sugar for a route-level Suspense boundary. A file at `app/dashboard/loading.tsx` is the fallback for an implicit `<Suspense>` wrapping `app/dashboard/page.tsx`. This is convention; identical semantics could be expressed with an explicit `<Suspense>` inside a layout.
+
+The interaction between RSC and Suspense is one of the biggest design wins of the App Router: server-rendered content can stream in chunks without giving up server-side rendering for the initial-paint content. The discipline of `server-components-design` (where to draw the server/client boundary) and `suspense-patterns` (where to draw the streaming boundary) compose together — they are orthogonal axes on the same tree.
+
+See `server-components-design` for the discipline of *what* runs on the server side of the RSC boundary; this skill covers *how to chunk the streaming output of that server tree*.
+
+## React 19's `use` Hook
+
+React 19 adds `use(promise)` — a hook (with relaxed rules: can be called conditionally) that unwraps a Promise during render. Inside a Suspense boundary, `use` is how Client Components participate in data-fetching Suspense without throwing manually:
+
+```tsx
+'use client'
+import { use } from 'react'
+
+function Comments({ commentsPromise }) {
+  const comments = use(commentsPromise)   // suspends until resolved
+  return <ul>{comments.map(c => <li key={c.id}>{c.text}</li>)}</ul>
+}
+
+// In a Server Component:
+export default function Post() {
+  const commentsPromise = fetchComments()    // not awaited — passed as Promise
+  return (
+    <Suspense fallback={<Spinner />}>
+      <Comments commentsPromise={commentsPromise} />
+    </Suspense>
+  )
+}
+```
+
+The Promise is created in the Server Component (which is free to start the fetch eagerly), passed across the boundary as a serializable Promise, and unwrapped in the Client Component via `use`. The Server Component doesn't block on the fetch; the Suspense boundary in the Server tree streams in the resolved content as soon as the Promise resolves on the client.
+
+Before React 19, Client Components could not directly consume Suspense for data fetching without a library that implements the throw-a-Promise convention (React Query's Suspense mode, SWR with `suspense: true`, Relay). `use` makes the pattern first-class.
+
+## Common Anti-Patterns
+
+| Anti-pattern | Why it's wrong | Fix |
+|---|---|---|
+| One Suspense boundary near the page root | Fallback replaces the entire page even though most is fast | Move boundaries closer to the slow data, one per independent slow section |
+| ErrorBoundary inside Suspense | Loading state lingers when fetch fails | Put ErrorBoundary outside Suspense (the common case) |
+| Awaiting parent data, then child fetches its own | Sequential waterfall | Kick off both fetches at the same level, pass Promises down or use Promise.all |
+| Suspense fallback shows on every interaction | Fallback flickers on updates | Wrap user-initiated updates in `startTransition` / `useTransition` |
+| Skeleton fallback that doesn't match the real content's layout | Layout shift when content arrives | Match skeleton dimensions to the real content (use same width/height/padding) |
+| Both Suspense and an `isLoading` prop in the same component | Duplicate loading-state plumbing | Pick one — Suspense throws or local state, not both |
+| Suspense around the whole `app/` layout | Every navigation shows the page-level fallback | Place fallback at the route segment level (`loading.tsx` per segment) |
+| Reading `searchParams` in a Server Component without Suspense | Whole route becomes dynamic with no streaming | Wrap the searchParams-reading subtree in Suspense so the rest can stream as static |
+
+## Verification
+
+After applying this skill, verify:
+
+- [ ] Every slow data dependency is wrapped in a Suspense boundary co-located near the data, not at a far ancestor.
+- [ ] Sibling sections that can stream independently have their own Suspense boundaries.
+- [ ] Each Suspense boundary has a matching ErrorBoundary; their nesting order matches the desired failure-mode UI.
+- [ ] User-initiated updates that may trigger Suspense are wrapped in `startTransition` to prevent fallback flicker.
+- [ ] Skeleton fallbacks match real-content dimensions to avoid layout shift.
+- [ ] No `isLoading` flag duplicates work that the Suspense boundary already handles.
+- [ ] Parallel fetches are kicked off as siblings (not parent/child), avoiding waterfalls.
+- [ ] In Next.js App Router, `loading.tsx` exists at the route segment that owns the slow data — not at a parent segment that includes fast content.
+
+## Grounding Sources
+
+- React docs — [`<Suspense>`](https://react.dev/reference/react/Suspense). The official reference for the boundary and its semantics.
+- React docs — [`useTransition`](https://react.dev/reference/react/useTransition) and [`startTransition`](https://react.dev/reference/react/startTransition). The transition APIs that prevent fallback flicker.
+- React docs — [`use`](https://react.dev/reference/react/use). The React 19 Promise-unwrapping hook for Client Components.
+- React 18 working group — [Suspense in React 18 design discussion](https://github.com/reactwg/react-18/discussions/47). The semantics and edge cases of the React 18 Suspense rewrite.
+- Next.js docs — [Loading UI and Streaming](https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming) and [`loading.tsx`](https://nextjs.org/docs/app/api-reference/file-conventions/loading) conventions. The route-segment Suspense sugar.
+- Dodds, K. C. — [react-error-boundary](https://github.com/bvaughn/react-error-boundary). The de facto error-boundary library for function components.
+- React docs — [Streaming](https://react.dev/reference/react-dom/server/renderToReadableStream). Server-side streaming primitives that Suspense rides on top of.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Choosing between SSR, SSG, ISR, and CSR rendering strategies | `rendering-models` | rendering-models owns the strategic decision; suspense-patterns is an in-tree mechanism that works with several of those strategies. |
+| Designing which work runs as Server Components vs Client Components | `server-components-design` | server-components-design owns the server/client tree split; suspense-patterns is orthogonal — Suspense boundaries can live in either kind of component. |
+| Hook discipline on Client Components (Rules of Hooks, useEffect, useMemo) | `hooks-patterns` | hooks-patterns covers the in-component logic primitives; Suspense operates at the tree level above hooks. |
+| Streaming protocols broader than React Suspense (SSE, WebSocket, AI streaming) | `streaming-architecture` | streaming-architecture is the general protocol concern; React Suspense streaming is one application of the broader streaming toolkit. |
+| Error-handling patterns (try/catch, error boundaries in isolation) | `code-review` and `react-error-boundary` library docs | This skill covers Suspense+ErrorBoundary *pairing*; isolated error-boundary discipline lives elsewhere. |

package/marketplace/skills/system-interface-contracts/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: system-interface-contracts
+description: "Use when defining or reviewing contracts between systems, modules, services, agents, jobs, events, APIs, or teams: ownership, inputs, outputs, invariants, compatibility, errors, idempotency, and versioning. Do NOT use for REST resource design alone (use `api-design`), async event contract detail (use `event-contract-design`), database schemas (use `data-modeling`), or post-failure debugging (use `debugging`)."
+license: MIT
+compatibility: "Portable contract-design discipline across code modules, services, queues, APIs, webhooks, jobs, and agent interfaces."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"architecture/contracts\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-11\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-11\\\\\\\"}\",\"eval_artifacts\":\"present\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"interface contract\\\\\\\",\\\\\\\"system boundary\\\\\\\",\\\\\\\"contract design\\\\\\\",\\\\\\\"compatibility contract\\\\\\\",\\\\\\\"input output invariant\\\\\\\",\\\\\\\"event schema\\\\\\\",\\\\\\\"module boundary\\\\\\\",\\\\\\\"idempotency contract\\\\\\\",\\\\\\\"versioning contract\\\\\\\",\\\\\\\"error contract\\\\\\\"]\",\"examples\":\"[\\\\\\\"define the contract between the ingestion job and the dashboard view layer\\\\\\\",\\\\\\\"what invariants must this event producer and consumer share?\\\\\\\",\\\\\\\"review this module boundary for missing ownership and compatibility rules\\\\\\\",\\\\\\\"we need an interface contract before several agents implement opposite sides of the boundary\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"design the REST endpoints, status codes, and pagination\\\\\\\",\\\\\\\"create database tables and constraints\\\\\\\",\\\\\\\"investigate why this existing integration is failing in production\\\\\\\",\\\\\\\"write an ADR after the interface decision has already been accepted\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"api-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"api-design owns REST/API surface shape; system-interface-contracts owns the broader boundary contract across any interface type\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"event-contract-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"event-contract-design owns asynchronous event envelopes, schemas, topics, and compatibility; system-interface-contracts owns the broader boundary discipline\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"data-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"data-modeling owns stored data structure; system-interface-contracts owns producer/consumer expectations and compatibility\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"debugging\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"debugging investigates a known failure; system-interface-contracts prevents ambiguous boundary behavior before failure\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"architecture-decision-records\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"architecture-decision-records records the adopted contract decision; this skill designs the contract\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"bounded-context-mapping\\\\\\\",\\\\\\\"api-design\\\\\\\",\\\\\\\"event-storming\\\\\\\",\\\\\\\"event-contract-design\\\\\\\",\\\\\\\"state-machine-modeling\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"code-review\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/system-interface-contracts/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/system-interface-contracts/SKILL.md
+---
+
+# System Interface Contracts
+
+## Coverage
+
+Design and audit contracts across boundaries: modules, services, event producers/consumers, background jobs, APIs, webhooks, databases, and agents. Covers ownership, data shape, required/optional fields, invariants, preconditions, postconditions, idempotency, ordering, error behavior, retries, compatibility, versioning, and verification.
+
+## Philosophy
+
+A boundary without a contract is a rumor. The implementation may work today because both sides accidentally agree, but the first independent change exposes the missing contract.
+
+Contracts should be specific enough to protect both sides from drift and small enough that teams can keep them true. The contract is not the implementation. It is the stable promise at the boundary.
+
+## Method
+
+1. Name the producer, consumer, owner, and direction of dependency.
+2. Define inputs, outputs, and allowed states.
+3. State invariants and forbidden states.
+4. Define error, retry, timeout, and idempotency behavior.
+5. Specify compatibility: additive changes, breaking changes, versioning, and deprecation.
+6. Identify observability required to prove the contract is being honored.
+7. Add contract tests or fixtures where possible.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/system-interface-contracts.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/system-interface-contracts.json). The checklist below is the authoring gate for system-boundary contracts; the eval file is the grader surface.
+
+## Verification
+
+- [ ] Each side has a named owner
+- [ ] Required and optional fields are explicit
+- [ ] Invariants and forbidden states are stated
+- [ ] Error and retry behavior is deterministic
+- [ ] Idempotency keys or deduplication rules exist where duplicate delivery is possible
+- [ ] Compatibility rules distinguish additive from breaking changes
+- [ ] Contract tests, fixtures, or examples exist for positive and negative cases
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `api-design` | You specifically need REST/resource endpoint shape, HTTP semantics, or API envelope design. |
+| `event-contract-design` | You specifically need asynchronous event envelope, schema, topic, replay, or consumer compatibility rules. |
+| `data-modeling` | You need persistence schema, keys, indexes, or data lifecycle. |
+| `debugging` | A boundary has already failed and the task is root-cause analysis. |
+| `architecture-decision-records` | The contract is chosen and needs a durable decision record. |

package/marketplace/skills/task-analysis/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: task-analysis
+description: "Use when auditing a route, defining a route contract, reviewing onboarding or setup flows, diagnosing why a page feels confusing, or when the user asks about top tasks, time-to-value, branching, dead ends, or task complexity. Provides goal-driven UX analysis that turns vague critique into explicit goal -> task -> subtask decomposition and a primary / secondary / supporting hierarchy contract for the first viewport. Do NOT use for control-pattern choice (use `interaction-patterns`), visual craft (use `visual-design-foundations`), responsive layout (use `layout-composition`), or accessibility-only QA (use `a11y`)."
+license: MIT
+compatibility: "Stack-agnostic. The actor / scenario / top-task model, the five friction dimensions, the breakpoint taxonomy, and the primary / secondary / supporting hierarchy apply to any UI under review; persona / journey YAML files are illustrative — substitute the equivalents (Notion, Confluence, in-repo Markdown, Figma annotations) of your team."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"workflow\",\"category\":\"foundations\",\"domain\":\"foundations/analysis\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-06\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-06\\\\\\\"}\",\"eval_artifacts\":\"present\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"top task analysis\\\\\\\",\\\\\\\"goal-driven UX review\\\\\\\",\\\\\\\"route audit workflow\\\\\\\",\\\\\\\"onboarding flow analysis\\\\\\\",\\\\\\\"task friction scoring\\\\\\\",\\\\\\\"five friction dimensions\\\\\\\",\\\\\\\"dead-end detection\\\\\\\",\\\\\\\"hidden next-step diagnosis\\\\\\\",\\\\\\\"hierarchy contract first viewport\\\\\\\",\\\\\\\"actor and scenario identification\\\\\\\",\\\\\\\"subtask sequencing skip paths\\\\\\\",\\\\\\\"flow breakpoint taxonomy\\\\\\\",\\\\\\\"mobile-only friction\\\\\\\",\\\\\\\"role-permission confusion\\\\\\\",\\\\\\\"time-to-value analysis\\\\\\\",\\\\\\\"task vs goal distinction\\\\\\\",\\\\\\\"excessive branching detection\\\\\\\",\\\\\\\"persona-journey route mapping\\\\\\\"]\",\"examples\":\"[\\\\\\\"this onboarding flow feels confusing — analyze the task structure\\\\\\\",\\\\\\\"audit this dashboard route for whether it supports the user's top task\\\\\\\",\\\\\\\"what should be above the fold on this page?\\\\\\\",\\\\\\\"users keep abandoning this wizard at step 3 — find the breakpoint\\\\\\\",\\\\\\\"decide what belongs in the first viewport for this analytics page\\\\\\\",\\\\\\\"diagnose why this multi-step setup has too many decisions\\\\\\\",\\\\\\\"the team disagrees on what the top task is for this route — settle it\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"review this PR for code quality\\\\\\\",\\\\\\\"audit this UI for WCAG 2.2 violations\\\\\\\",\\\\\\\"decide the CSS grid layout for this hero section\\\\\\\",\\\\\\\"pick the right colors for this status badge\\\\\\\",\\\\\\\"build the navigation taxonomy for the whole product\\\\\\\",\\\\\\\"should we use a dropdown or a stepper here\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"code-review\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"code-review judges the quality and correctness of a specific change at PR scope; task-analysis judges whether a route's structure supports the user's top task — same 'review this page' prompt routes by whether the lens is code or user goal\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"a11y\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"a11y is accessibility QA against WCAG / ARIA / keyboard / screen-reader contracts on an existing UI; task-analysis is goal-driven decomposition of what the UI must support — same 'review this UI' prompt routes by whether the trigger is accessibility compliance or user-task fit\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"layout-composition\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"layout-composition owns responsive section order, grids, and scan patterns; task-analysis stops at the first-viewport hierarchy contract\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"visual-design-foundations\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"visual-design-foundations owns visual craft; task-analysis owns whether the route supports the user's goal\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"interaction-patterns\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"interaction-patterns owns control-pattern selection; task-analysis identifies the decision or action that the pattern must support\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"interaction-feedback\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"interaction-feedback owns loading, progress, success, error, retry, and undo behavior; task-analysis identifies where feedback is needed\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"information-architecture\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"information-architecture owns navigation and page grouping across a product; task-analysis owns one route or flow\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"diagnosis\\\\\\\",\\\\\\\"pattern-recognition\\\\\\\",\\\\\\\"information-architecture\\\\\\\",\\\\\\\"layout-composition\\\\\\\",\\\\\\\"interaction-patterns\\\\\\\",\\\\\\\"interaction-feedback\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"a11y\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/task-analysis/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/task-analysis/SKILL.md
+---
+
+# Task Analysis
+
+## Coverage
+
+Goal-driven UX analysis for any route or flow: identifying the actor and scenario from persona / journey contracts, extracting the top task for a route, breaking tasks into sequential subtasks with skip paths and blocked states, scoring task friction across five dimensions (discoverability, cognitive load, effort, trust, recovery), identifying breakpoints (dead ends, hidden next steps, excessive branching, unclear success states, misleading value presentation, mobile-only friction, role / permission confusion), and producing the primary / secondary / supporting hierarchy contract for the first viewport that hands off to layout and composition skills. Applies to route audits, onboarding flow reviews, setup wizards, multi-step processes, and any page where "it feels confusing" needs a structured diagnosis. Includes a five-step analysis protocol, a structured output template, an anti-pattern list (Nielsen-first heuristic critique, "rendered correctly" as proof, ignoring skip paths, decorative polish over task completion, fictional persona detail), and a verification checklist that confirms the actor and scenario were named explicitly rather than assumed.
+
+## Philosophy
+
+UX quality is not about how a page looks — it is about whether the page supports the user's top task. Without task analysis, agents default to generic heuristic critique ("add more whitespace," "reduce clutter") that sounds professional but changes nothing about task completion.
+
+This skill exists because aesthetic-first design reviews produce recommendations that do not address why users abandon flows. Task analysis forces the question: what is the user trying to accomplish, and where does the route break that goal? Once the goal is explicit, every layout, copy, and interaction decision can be measured against task support rather than personal taste — and the conversation moves from subjective debate ("I think this looks better") to falsifiable claim ("this change reduces friction at the discoverability dimension for step 2").
+
+## Workflow
+
+Use the ordered phases, checklists, and guardrails in the sections below as the canonical workflow for this skill. When multiple subsections describe steps, follow them in the order presented.
+
+> If you cannot state the user's goal, top task, and next step, you are not analyzing the UX yet.
+
+### When to Activate
+
+Load this skill when:
+
+- auditing a route or flow
+- writing or updating route contracts
+- checking onboarding / setup / multi-step flows
+- diagnosing friction, dead ends, or too many clicks
+- deciding what belongs above the fold on a task-heavy page
+
+### Core Model
+
+Separate these concepts clearly:
+
+| Term         | Meaning                                  | Example                                            |
+| ------------ | ---------------------------------------- | -------------------------------------------------- |
+| **Goal**     | Why the user is here                     | "Know if my marketing campaign performed well"     |
+| **Task**     | Observable activity that serves the goal | Open the analytics report and read summary metrics |
+| **Subtask**  | Smaller step within the task             | Navigate to Analytics → select 7D → inspect summary |
+| **Scenario** | The specific situation / route context   | Marketing manager checking this week's results on mobile |
+
+Never confuse a UI interaction with a goal. Filling a form is not the goal; it is a task in service of the goal.
+
+### Inputs To Read First
+
+1. The route contract or page contract for the target route (if your team maintains one).
+2. The canonical persona definitions for your product.
+3. The canonical journey / scenario sequencing for your product.
+4. Any narrative route-flow documentation (user-journey docs, sitemaps).
+
+If these inputs are missing, state the missing source of truth instead of inventing task structure. If the inputs exist but disagree (the persona doc says one thing and the journey doc another), flag the discrepancy in your output rather than picking a winner silently.
+
+**Caution:** these sources may have drifted. Trust the most-recently-updated canonical source for the field in question and document any conflicts you encountered.
+
+### Analysis Protocol
+
+#### 1. Identify the actor and scenario
+
+Output:
+
+```text
+Actor: <persona_id>
+Scenario: <journey_id> — <scenario>
+Business objective: <activation | retention | expansion | operational_efficiency>
+```
+
+#### 2. Extract the top task
+
+For the target route, answer:
+
+- What is the primary task this route must support?
+- What would success look like in the smallest useful unit of time?
+- What information must be visible before the user can proceed confidently?
+
+Also name the hierarchy contract for the first viewport:
+
+- **Primary:** what must be seen first.
+- **Secondary:** what must frame or support the primary task.
+- **Supporting:** what can wait until the user asks for more detail.
+
+If you cannot name these three layers, you are not ready to decide what belongs above the fold. Once named, hand off to `layout-composition` to turn the hierarchy into actual section order, scan pattern, and component decisions.
+
+#### 3. Break the task into subtasks
+
+Represent the flow as ordered steps:
+
+```text
+Goal
+  → Task
+    → Subtask 1
+    → Subtask 2
+    → Branch / skip
+    → Completion state
+```
+
+Include skip paths, blocked states, and role-limited variants.
+
+#### 4. Score task friction
+
+For each subtask, evaluate:
+
+| Dimension           | Questions                                                        |
+| ------------------- | ---------------------------------------------------------------- |
+| **Discoverability** | Can the user find the next step quickly?                         |
+| **Cognitive load**  | Does the user need to remember hidden context or jargon?         |
+| **Effort**          | How many clicks / scrolls / decisions are required?              |
+| **Trust**           | Is uncertainty, incompleteness, or gating communicated honestly? |
+| **Recovery**        | If blocked, is the next step obvious and actionable?             |
+
+#### 5. Identify the breakpoints
+
+Flag the exact point where the journey degrades:
+
+- dead end
+- excessive branching
+- hidden next step
+- unclear success state
+- misleading value presentation
+- mobile-only friction
+- role / permission confusion
+
+### Output Template
+
+```markdown
+## Task Analysis
+
+- Actor: <persona>
+- Scenario: <journey>
+- Top task: <single-sentence task>
+- Success metric: <time-to-value or completion target>
+
+### Task Breakdown
+
+1. <subtask>
+2. <subtask>
+3. <subtask>
+
+### Friction Points
+
+- <point> — why it increases effort or confusion
+
+### Failure Modes
+
+- <documented route failure mode>
+
+### UX Implication
+
+- What must change in layout, copy, affordance, or state handling to support the task better
+```
+
+### Anti-Patterns
+
+- Starting with Nielsen heuristics before naming the top task.
+- Treating "rendered correctly" as proof the task is supported.
+- Ignoring skip paths or role-limited states.
+- Counting decorative polish as more important than task completion.
+- Using fictional persona detail instead of route / journey evidence.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/task-analysis.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/task-analysis.json). The checklist below is the authoring gate for route and flow analysis; the eval file is the grader surface.
+
+## Verification
+
+After applying task analysis, verify:
+
+- [ ] Actor and scenario are explicitly named (persona id + journey id), not assumed.
+- [ ] Top task is stated as a single sentence describing what the user is trying to accomplish.
+- [ ] Subtasks are listed in sequential order with skip paths and blocked states noted.
+- [ ] Friction scoring covers all five dimensions (discoverability, cognitive load, effort, trust, recovery).
+- [ ] Breakpoints identify the exact point where the journey degrades, not generic complaints.
+- [ ] Primary / secondary / supporting hierarchy contract is named for the first viewport.
+- [ ] Layout and composition decisions are deferred to `layout-composition`, not attempted here.
+- [ ] Recommendations are framed in terms of task support, not aesthetic preference.
+
+## Do NOT Use When
+
+| Instead, use | Why |
+|---|---|
+| `code-review` | Reviewing a specific PR or change for code quality and correctness. Code-review owns the per-change judgment; task-analysis owns the per-route user-goal decomposition. |
+| `a11y` | Auditing an existing UI against WCAG / ARIA / keyboard / screen-reader contracts. A11y owns the accessibility-compliance lens; task-analysis owns the user-goal-fit lens. |
+| `diagnosis` | Triaging an unknown software failure into a problem class before debugging begins. Diagnosis owns the per-incident triage; task-analysis owns the per-route user-task decomposition. |
+| `pattern-recognition` | Detecting recurring UX-friction patterns across many routes. Pattern-recognition owns the cross-route class analysis; task-analysis owns the within-route analysis of one route at a time. |
+| `documentation` | Writing or updating route-contract docs, page-template specs, or sitemap docs. Documentation owns the artifact format; task-analysis produces the content that goes into those artifacts. |
+| `layout-composition` | Deciding CSS grid layout, section ordering, breakpoints, or scan-pattern composition. Task-analysis stops at the hierarchy contract; layout-composition owns the visual structure decisions. |
+| `visual-design-foundations` | Reviewing visual polish (spacing, color, typography). Task-analysis is goal-first; visual-design-foundations owns visual craft. |
+| `interaction-patterns` | Choosing controls such as dropdowns, steppers, tabs, modals, or inline edit. Interaction-patterns owns pattern selection. |
+| `interaction-feedback` | Adding loading skeletons, empty states, progress indicators, retry, or undo behavior. Interaction-feedback owns UI-state patterns; task-analysis identifies where such patterns are needed without specifying which. |
+| `information-architecture` | Building the navigation taxonomy or page-group structure for an entire product. IA owns structural organization across pages; task-analysis owns per-page user-goal analysis. |

package/marketplace/skills/taxonomy-design/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: taxonomy-design
+description: "Use when designing a controlled classification system: category trees, facets, browse taxonomies, SKOS broader/narrower relationships, tagging rules, and duplicate-category cleanup. Do NOT use for formal ontology axioms with reasoning constraints (use `ontology-modeling`), broad knowledge-representation choice (use `knowledge-modeling`), or one-off edge typing (use `semantic-relations`)."
+license: MIT
+compatibility: "Portable taxonomy design discipline for skill libraries, product information architecture, documentation trees, and knowledge graphs."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.1.0\",\"type\":\"capability\",\"category\":\"foundations\",\"domain\":\"foundations/classification\",\"scope\":\"portable\",\"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\":\"[\\\\\\\"taxonomy design\\\\\\\",\\\\\\\"controlled vocabulary\\\\\\\",\\\\\\\"browse taxonomy\\\\\\\",\\\\\\\"category hierarchy\\\\\\\",\\\\\\\"facets\\\\\\\",\\\\\\\"tagging rules\\\\\\\",\\\\\\\"broader narrower\\\\\\\",\\\\\\\"SKOS hierarchy\\\\\\\",\\\\\\\"classification cleanup\\\\\\\",\\\\\\\"duplicate categories\\\\\\\",\\\\\\\"taxonomy governance\\\\\\\"]\",\"examples\":\"[\\\\\\\"our skill categories are drifting: some are by domain, some by activity, and some by tool - how should the taxonomy be redesigned?\\\\\\\",\\\\\\\"should these be tags, facets, or child categories?\\\\\\\",\\\\\\\"build a clean category tree for these concepts without making every related term a parent-child relation\\\\\\\",\\\\\\\"we have analytics, observability, telemetry, and monitoring as categories - which should merge and which should stay separate?\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"define OWL class restrictions and property domains for this knowledge base\\\\\\\",\\\\\\\"decide whether this knowledge should be represented as a graph, frame, rules, or hybrid\\\\\\\",\\\\\\\"type this single relation as meronymy, causality, synonymy, or thematic role\\\\\\\",\\\\\\\"write user-facing labels for this navigation item\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"ontology-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"ontology-modeling owns formal axioms and reasoning semantics; taxonomy-design owns human-governed classification\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"knowledge-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"knowledge-modeling chooses the representation paradigm; taxonomy-design works inside the classification paradigm once chosen\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"semantic-relations\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"semantic-relations types individual concept edges; taxonomy-design governs the category system and assignment rules\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"information-architecture\\\\\\\",\\\\\\\"skill-infrastructure\\\\\\\",\\\\\\\"context-graph\\\\\\\"],\\\\\\\"depends_on\\\\\\\":[\\\\\\\"semantic-relations\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"semantic-relations\\\\\\\",\\\\\\\"context-graph\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Taxonomy design is to a knowledge surface what a public library's call-number system is to its collection — the books haven't changed, but the system determines which books a researcher finds when looking under 'biology' versus 'medicine' versus 'public health.' A library that categorizes by acquisition date (the author's mental map) is unfindable; one that categorizes by subject with cross-references and facet headings (retrieval contract for the navigator) is searchable. Dewey Decimal is a hierarchy with facet-like subdivisions; Library of Congress is more faceted; both are taxonomies, both have explicit retrieval-task analyses behind their structure.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Taxonomy design is the discipline of constructing a controlled classification system — a category tree (possibly augmented by facets) that organizes a set of items so they can be browsed, found, and reasoned about. Drawing from Ranganathan's faceted classification, Aristotelian genus-species hierarchy, and the SKOS data model, it treats classification as a *retrieval contract* between the system that organizes and the readers who navigate, not as a private mental map of the author.\\\\\\\",\\\\\\\"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/taxonomy-design/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/taxonomy-design/SKILL.md
+---
+
+# Taxonomy Design
+
+## Coverage
+
+Design controlled classification systems for skills, docs, product catalogs, navigation trees, knowledge graphs, and tags. Covers hierarchy shape, facet selection, synonym control, category granularity, assignment rules, governance, and drift cleanup. Use SKOS-grade distinctions: broader/narrower for hierarchy, related for association, preferred labels for canonical terms, alternate labels for aliases.
+
+## Philosophy
+
+A taxonomy is a retrieval contract. It should make things findable by the people or agents who browse it, not mirror the author's private mental map. The main failure mode is mixing incompatible organizing principles: by audience, by tool, by lifecycle phase, by domain, and by risk all in the same tree.
+
+Prefer shallow, stable, mutually understandable structure. Add facets when one tree cannot express all valid access paths. Do not turn every semantic relation into a hierarchy.
+
+## Method
+
+1. Name the retrieval tasks: what questions must the taxonomy answer?
+2. Choose one primary organizing principle for the tree: domain, activity, artifact, lifecycle, or risk.
+3. Move secondary dimensions into facets or tags.
+4. Apply the substitution test to every parent-child pair: every child must be a kind of the parent.
+5. Define assignment rules for ambiguous cases.
+6. Add canonical labels and aliases; never let synonyms become sibling categories.
+7. Test with real items and real prompts; count "misc", duplicates, and uncertain assignments.
+
+## Verification
+
+- [ ] Every child category passes the IS-A substitution test against its parent
+- [ ] Sibling categories share the same organizing principle
+- [ ] Cross-cutting concerns are facets/tags, not duplicated branches
+- [ ] Canonical labels and aliases are explicit
+- [ ] Ambiguous assignment rules are written down
+- [ ] No category exists only because one item needed somewhere to go
+- [ ] Real items can be placed without using a catch-all bucket
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `ontology-modeling` | You need formal class/property axioms, RDF/OWL semantics, or automated reasoning. |
+| `knowledge-modeling` | You are still choosing between graph, frame, rule, concept-map, or hybrid representations. |
+| `semantic-relations` | You only need to type the relation between two concepts. |
+| `information-architecture` | You are arranging pages, navigation, labels, and wayfinding for a user-facing experience. |
+
+## Key Sources
+
+- Ranganathan, S. R. (1933/1962). *Colon Classification* and *Prolegomena to Library Classification* (3rd ed.). Asia Publishing House. The foundational statement of faceted classification and the PMEST formula (Personality / Matter / Energy / Space / Time); the alternative to strict hierarchical trees that all modern multi-criteria classification descends from.
+- W3C. [SKOS Simple Knowledge Organization System Reference](https://www.w3.org/TR/skos-reference/) (2009). The standard data model for taxonomies and thesauri: broader/narrower/related, prefLabel/altLabel, and the minimal formalism required for transmissible classification.
+- Bowker, G. C., & Star, S. L. (1999). *Sorting Things Out: Classification and Its Consequences*. MIT Press. The canonical critical study of how classifications shape what becomes thinkable; the source of the "boundary infrastructure" framing and the empirical evidence that taxonomies without explicit retrieval-task analysis become abandoned bureaucratic structure.
+- Hjørland, B. (2008). "What is Knowledge Organization (KO)?" *Knowledge Organization*, 35(2-3), 86-101. Authoritative survey of the field; situates taxonomy design within library and information science.
+- Aristotle. *Categories* (c. 350 BCE). The philosophical root of hierarchical classification: genus-species definitions, the predicables, and the structure that two and a half millennia of taxonomy work has built on or against.
+- Vander Wal, T. (2005). ["Folksonomy."](https://vanderwal.net/folksonomy.html) The coinage and definition of folksonomy; the alternative to controlled vocabulary and the trade-offs that come with emergent tagging.
+- Morville, P., & Rosenfeld, L. (2006). *Information Architecture for the World Wide Web* (3rd ed.). O'Reilly. The practitioner reference for taxonomy work in user-facing systems; the bridge from classification to navigation.
+- Glushko, R. J. (Ed.). (2013). *The Discipline of Organizing*. MIT Press. Cross-disciplinary synthesis treating classification as a design activity rather than a domain reflection; explicit attention to facet design and retrieval-task analysis.
+- Schema.org. [Type Hierarchy](https://schema.org/docs/full.html). A pragmatic large-scale web taxonomy; a real-world example of design choices, facet vs hierarchy decisions, and the costs of governance at scale.