@skill-graph/cli 0.5.6

package/marketplace/skills/mobile-responsive-ux/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: mobile-responsive-ux
+description: "This skill provides mobile-specific UX patterns for SaaS dashboards: touch-friendly targets (44px minimum), thumb-zone optimization, swipe gestures, condensed data display, bottom navigation, and pull-to-refresh. Load when designing for mobile users, implementing touch interactions, building responsive dashboard layouts, or optimizing for the Side Hustler persona who checks on mobile."
+license: MIT
+compatibility: "Markdown, Git, agent-skill runtimes"
+allowed-tools: Read Grep Bash
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"design\",\"domain\":\"design/display\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-03-29\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-03-29\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"mobile-responsive-ux\\\\\\\",\\\\\\\"mobile\\\\\\\",\\\\\\\"responsive\\\\\\\"]\",\"triggers\":\"[\\\\\\\"mobile-responsive-ux-skill\\\\\\\",\\\\\\\"mobile-ux-skill\\\\\\\",\\\\\\\"touch-target-skill\\\\\\\",\\\\\\\"thumb-zone-skill\\\\\\\",\\\\\\\"mobile-dashboard-skill\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[\\\\\\\"a11y\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":90,\\\\\\\"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/mobile-responsive-ux/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/mobile-responsive-ux/SKILL.md
+---
+# Mobile Responsive UX Skill
+
+## Domain Context
+
+**What is this skill?** This skill provides mobile-specific UX patterns for SaaS dashboards: touch-friendly targets (44px minimum), thumb-zone optimization, swipe gestures, condensed data display, bottom navigation, and pull-to-refresh. Load when designing for mobile users, implementing touch interactions, building responsive dashboard layouts, or optimizing for the Side Hustler persona who checks on mobile.
+> If a button works with a mouse but not with a thumb on a moving bus, it is not usable.
+
+## Coverage
+
+This skill covers touch target sizing (44px minimum per Apple HIG and WCAG 2.2), thumb-zone optimization (reachable areas on one-handed use), swipe gesture patterns (navigation, actions, dismissal), condensed data display for small screens (priority content, progressive disclosure), bottom navigation and bottom sheet patterns, pull-to-refresh implementation, mobile-specific input patterns (date pickers, number keyboards, autocomplete), and the SaaS dashboard mobile paradigm (quick-glance KPIs, not full desktop experience).
+
+## Philosophy
+
+Mobile is not a smaller desktop. Agents consistently make the mistake of "responsive" meaning "the same layout but narrower." A SaaS dashboard on mobile serves a fundamentally different purpose than on desktop. The desktop user is doing analytical work: filtering, comparing, exporting. The mobile user is doing a quick health check: "Am I making money today? Any problems?" These are different tasks requiring different interfaces. The 375px screen cannot show the same data table with 8 columns — and it should not try. This skill enforces the discipline of designing for the mobile use case, not just reflowing the desktop layout into a narrower viewport.
+
+## Architecture
+
+### Mobile Use Case Hierarchy
+
+| Priority | What Mobile Users Need | Design Implication |
+|----------|----------------------|-------------------|
+| 1 | Today's headline KPIs (revenue, margin, orders) | Large, glanceable numbers at the top |
+| 2 | Alert/notification status | Badge or indicator without scrolling |
+| 3 | Quick drill-down into a specific order | Search or recent orders list |
+| 4 | Period comparison (today vs yesterday) | Simple toggle, not a date range picker |
+| 5 | Full data exploration | Defer to desktop; show "View on desktop" prompt |
+
+### Touch Target Specifications
+
+| Standard | Minimum Size | Recommended Size | Spacing |
+|----------|-------------|-----------------|---------|
+| **Apple HIG** | 44 x 44 pt | 44 x 44 pt | 8pt between targets |
+| **Material Design** | 48 x 48 dp | 48 x 48 dp | 8dp between targets |
+| **WCAG 2.2 (Level AA)** | 24 x 24 CSS px | 44 x 44 CSS px | Adjacent targets must not overlap |
+
+**Rule:** All interactive elements on mobile must be at least 44 x 44 CSS pixels. This includes buttons, links, checkboxes, filter chips, table row actions, and dropdown triggers. If the visual element is smaller (e.g., a 16px icon), the tap target must extend beyond the visible element using padding.
+
+```css
+/* Touch target pattern — visual is 24px, tap target is 44px */
+.icon-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  padding: 10px;           /* Extends tap area to 44px */
+  margin: 0;
+  -webkit-tap-highlight-color: transparent;
+}
+```
+
+### Thumb Zone Map
+
+On one-handed phone use, the thumb has three zones of reachability:
+
+```
++----------------------------+
+|     HARD TO REACH          |  <- Top 20%: avoid primary actions
+|                            |
+|     STRETCH ZONE           |  <- Middle 30%: secondary actions OK
+|                            |
+|     NATURAL ZONE           |  <- Bottom 50%: primary actions here
++----------------------------+
+     [  Home / Nav Bar  ]
+```
+
+**Design rules based on thumb zone:**
+- **Primary actions** (confirm, save, navigate): bottom 50% of screen
+- **Secondary actions** (filter, sort, settings): middle 30%
+- **Rarely used actions** (help, account, advanced settings): top 20% or behind a menu
+- **Bottom navigation** for main sections: always in the natural zone
+- **Floating action buttons** (FAB): bottom-right corner for right-handed users
+
+## Implementation Patterns
+
+### 1. Bottom Navigation
+
+Replace the sidebar with bottom navigation on mobile. Maximum 5 items:
+
+```
++----------------------------+
+|                            |
+|     Page Content           |
+|                            |
++----------------------------+
+| Dashboard | Orders | More  |
+|    [icon] | [icon] | [icon]|
++----------------------------+
+```
+
+**Rules:**
+- Maximum 5 items in bottom navigation (Apple HIG)
+- Each item: icon + label (icon-only is ambiguous)
+- Active state: filled icon + color change + label
+- Badge for notification count on relevant tab
+- Bottom nav is always visible — never hidden by scroll
+
+### 2. Bottom Sheet for Complex Actions
+
+When the user needs to filter, sort, or perform multi-step actions on mobile, use a bottom sheet instead of a modal or dropdown:
+
+```
++----------------------------+
+|     Page Content           |
+|     (dimmed background)    |
++----------------------------+
+|  --- drag handle ---       |
+|  Filter Orders             |
+|                            |
+|  Status:  [All] [Pending]  |
+|  Channel: [All] [Shopify]  |
+|                            |
+|  [Apply Filters]           |
++----------------------------+
+```
+
+**Bottom sheet heights:**
+- **Peek:** 25% of viewport — shows summary or first action
+- **Half:** 50% — shows a form or short list
+- **Full:** 90% — shows a long list or complex form (always include close/back)
+
+### 3. Condensed Data Display
+
+Desktop data tables do not work on mobile. Replace with card-based layouts:
+
+**Desktop table row:**
+```
+| Order #1234 | Shopify | $45.99 | $12.50 | 27.2% | Shipped |
+```
+
+**Mobile card:**
+```
++----------------------------+
+| #1234          Shipped [>] |
+| Shopify                    |
+| Revenue: $45.99            |
+| Margin:  27.2%  ($12.50)   |
++----------------------------+
+```
+
+**Rules for mobile data display:**
+- Show 3-4 data points per card, not 8+ columns
+- Most important data (order number, status) at the top
+- Secondary data (channel, margin) below
+- Tap to expand or navigate to detail view
+- Never horizontal scroll a data table on mobile
+
+### 4. Swipe Gestures
+
+| Gesture | Action | Use Case |
+|---------|--------|----------|
+| Swipe left on list item | Reveal action buttons (delete, archive) | Order list, notification list |
+| Swipe right on list item | Quick action (mark as read, flag) | Notification list |
+| Swipe down from top | Pull-to-refresh | Any data list |
+| Swipe between tabs | Navigate tab content | Dashboard sections |
+
+**Rules:**
+- Swipe actions must have a visual counterpart (button accessible without swiping)
+- Swipe-to-delete requires confirmation (do not delete on swipe alone)
+- Swipe velocity and distance thresholds must feel natural (> 30% of item width to trigger)
+- Never use swipe as the only way to access an action — always provide a tap alternative
+
+### 5. Pull-to-Refresh
+
+```typescript
+// Implementation pattern
+function PullToRefresh({ onRefresh, children }: Props) {
+  const [pulling, setPulling] = useState(false);
+  const [refreshing, setRefreshing] = useState(false);
+  const startY = useRef(0);
+
+  // Pull indicator appears after 60px downward drag
+  // Trigger refresh after 100px drag distance
+  // Show spinner during refresh, snap back on complete
+
+  return (
+    <div onTouchStart={handleTouchStart} onTouchMove={handleTouchMove} onTouchEnd={handleTouchEnd}>
+      {refreshing && <RefreshSpinner />}
+      {children}
+    </div>
+  );
+}
+```
+
+**Rules:**
+- Only trigger when scrolled to the top of the content
+- Show a visual indicator during the pull (spinner or progress)
+- Haptic feedback on trigger threshold (where supported)
+- Disable during active data loading to prevent double-fetch
+
+### 6. Mobile Input Optimization
+
+| Input Type | Mobile Optimization | HTML Attribute |
+|-----------|--------------------|-|
+| Phone number | Numeric keyboard | `type="tel"` |
+| Email | Email keyboard (@ visible) | `type="email"` |
+| Currency amount | Decimal keyboard | `type="text" inputmode="decimal"` |
+| Date | Native date picker | `type="date"` (or custom bottom sheet picker) |
+| Search | Search keyboard (enter = search) | `type="search"` |
+| Quantity | Stepper control (+/-) instead of free text | Custom component |
+
+### 7. Mobile-Specific KPI Display
+
+On mobile, KPI cards should be 2-up (2 per row) instead of the 4-up desktop layout:
+
+```
++---------------------------+
+| Revenue      | Orders     |
+| $4,523       | 47         |
+| +12% vs yday | -3% vs yday|
++---------------------------+
+| Margin       | Avg Order  |
+| 28.4%        | $96.23     |
+| +2.1pp       | +$4.50     |
++---------------------------+
+```
+
+**Rules:**
+- 2-up layout at < 640px (never 1-up for KPIs — wastes vertical space)
+- Large primary number (24-28px font)
+- Smaller comparison below (12-14px)
+- Tap KPI card to drill down to detail view
+- No chart within KPI card on mobile — charts belong in their own section below
+
+## Anti-Patterns
+
+1. **Horizontal scrolling data tables.** Shrinking a 8-column desktop table and letting the user scroll horizontally. On mobile, horizontal scroll is disorienting and most users do not discover scrollable content. Use card layouts instead.
+
+2. **Desktop modals on mobile.** A centered modal with small close button works on desktop but obscures content and has poor touch targets on mobile. Use bottom sheets instead of modals.
+
+3. **Tiny tap targets.** A 24px icon button without extended padding. Fingers are 44-57px wide; anything smaller causes mis-taps and frustration.
+
+4. **Top-of-screen primary actions.** Putting the main CTA ("Save", "Submit", "Next") at the top of the screen where the thumb cannot reach during one-handed use. Primary actions go at the bottom.
+
+5. **Hover-dependent interactions.** Tooltips, hover menus, and hover-triggered dropdowns do not exist on touch devices. Every hover interaction must have a touch equivalent (tap, long-press, or inline display).
+
+6. **Same density on mobile and desktop.** Showing the same amount of data in the same density on a 375px screen. Mobile needs progressive disclosure: show the headline, tap to see details.
+
+7. **Full date range picker on mobile.** A dual-calendar date range selector from a desktop library. On mobile, use preset ranges ("Today", "This Week", "This Month") with a custom option that opens a bottom sheet.
+
+## Key Files
+
+When working in a project with mobile responsive UX:
+
+- CSS breakpoint definitions — `_tokens.scss` or equivalent
+- Responsive wrapper components — `MobileOnly`, `DesktopOnly`
+- Bottom navigation component — mobile navigation bar
+- Touch gesture utilities — swipe handlers, pull-to-refresh
+- KPI card components — responsive grid layout
+
+## Verification
+
+After applying this skill, verify:
+- [ ] All interactive elements are at least 44 x 44 CSS px on mobile
+- [ ] Primary actions are positioned in the bottom 50% of the screen
+- [ ] Data tables are replaced with card layouts below 640px
+- [ ] Bottom navigation has maximum 5 items with icon + label
+- [ ] No hover-only interactions exist — all have touch equivalents
+- [ ] KPI cards use 2-up layout on mobile
+- [ ] Pull-to-refresh is implemented for data lists
+- [ ] Test on a real device (not just browser DevTools resize)
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| CSS breakpoint implementation details | `breakpoint-strategy` | Breakpoints cover the CSS system; this skill covers the UX design at each breakpoint |
+| General responsive layout patterns | `responsive` | Responsive covers layout reflow; this skill covers mobile-specific interaction patterns |
+| Accessibility for touch interfaces | `a11y` | Accessibility covers WCAG compliance broadly; this skill covers mobile-specific ergonomics |
+| Data table design patterns | `data-table-ux` | Data table UX covers the table component; this skill covers how tables transform on mobile |
+
+---
+
+*Version 1.0.0 -- 2026-03-29. Initial creation.*

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

@@ -0,0 +1,112 @@
+---
+name: mutation-testing
+description: "Use when reasoning about mutation testing as a behavioral signal of test-suite quality: the mutant-operator vocabulary (replace operator, negate condition, flip Boolean, remove statement, alter constant), the mutation-score metric (killed mutants / total non-equivalent mutants), why mutation testing is a stronger signal than code coverage (coverage measures execution; mutation measures whether the tests would catch a defect), the equivalent-mutant problem (mutants that produce no observable behavior change despite syntactic difference), selective and incremental mutation strategies that make the technique practical for large codebases (PIT, Stryker), and the relationship between mutation testing and TDD. Do NOT use for the structural signal of how much code tests reach (use test-coverage-strategy), the construction of test doubles (use test-doubles-design), the strategic question of what to test at which level (use testing-strategy), or generic fault injection at runtime (use chaos-engineering)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"quality\",\"domain\":\"quality/testing\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"mutation testing\\\\\\\",\\\\\\\"mutation score\\\\\\\",\\\\\\\"mutant\\\\\\\",\\\\\\\"mutant operator\\\\\\\",\\\\\\\"PIT\\\\\\\",\\\\\\\"Stryker\\\\\\\",\\\\\\\"DeMillo\\\\\\\",\\\\\\\"equivalent mutant\\\\\\\",\\\\\\\"killed mutant\\\\\\\",\\\\\\\"selective mutation\\\\\\\",\\\\\\\"higher-order mutant\\\\\\\",\\\\\\\"test effectiveness\\\\\\\"]\",\"triggers\":\"[\\\\\\\"how do we know the tests actually verify anything\\\\\\\",\\\\\\\"high coverage but bugs still slip through\\\\\\\",\\\\\\\"what is mutation testing\\\\\\\",\\\\\\\"is the test suite good or just thorough\\\\\\\",\\\\\\\"PIT vs Stryker\\\\\\\"]\",\"examples\":\"[\\\\\\\"explain why a 90% coverage codebase might have a 40% mutation score and what that means\\\\\\\",\\\\\\\"decide whether to run mutation testing on a critical financial module\\\\\\\",\\\\\\\"diagnose surviving mutants in a calculation function and identify the missing assertion\\\\\\\",\\\\\\\"design a CI pipeline that runs incremental mutation testing only on changed code\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"measure how much code the test suite executes (use test-coverage-strategy)\\\\\\\",\\\\\\\"design test doubles for an integration test (use test-doubles-design)\\\\\\\",\\\\\\\"inject failures into a running distributed system (use chaos-engineering)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"test-coverage-strategy\\\\\\\",\\\\\\\"test-driven-development\\\\\\\",\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"eval-driven-development\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"test-coverage-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"test-coverage-strategy owns the structural signal of which code the test suite reaches; mutation-testing owns the behavioral signal of whether the test suite would catch a defect at that code location. The two compose: coverage is a necessary precondition for mutation testing to apply (an uncovered mutant trivially survives); mutation is the next layer of test-quality signal.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"testing-strategy owns the strategic question of what to test at which level; this skill owns one measurement of how good the tests at any level actually are.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"test-driven-development\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"TDD produces tests with high behavioral specificity as a side effect; mutation testing is one way to measure whether that specificity is in fact present in a given test suite.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"test-coverage-strategy\\\\\\\",\\\\\\\"testing-strategy\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Mutation testing is to a test suite what a fire drill is to a building's evacuation plan — you do not measure preparedness by counting how many exits exist (coverage), you measure it by deliberately staging a fire and watching whether anyone notices in time (mutation kill rate). An exit that nobody walks through during the drill is not really an exit, regardless of how prominently it is signposted.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Mutation testing is a behavioral test-suite quality measurement in which the production code is automatically modified by small, syntactically-valid changes (mutants) and the test suite is run against each modified version. If the test suite fails on a mutant, the mutant is 'killed' — the tests caught the change. If the test suite still passes, the mutant 'survived' — the tests did not catch the change, which means the tests do not actually verify the behavior at that code location. The mutation score is the ratio of killed mutants to total (excluding equivalent mutants, which produce no observable behavior change despite the syntactic modification). Unlike code coverage, which measures whether the tests *reach* a piece of code, mutation testing measures whether the tests *verify* it.\\\\\\\",\\\\\\\"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/mutation-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/mutation-testing/SKILL.md
+---
+
+# Mutation Testing
+
+## Coverage
+
+The behavioral test-suite quality measurement that introduces small syntactically-valid modifications (mutants) to production code and checks whether the test suite distinguishes the mutant from the original. Covers the mutant-operator vocabulary (arithmetic, relational, conditional, logical, constant, statement deletion, return value, method call removal), the kill-or-survive primitive, the mutation score metric, the equivalent-mutant problem and detection heuristics, selective mutation (Offutt et al.'s subset), execution strategies (full / incremental / bytecode / distributed), the modern tooling ecosystem (PIT, Stryker, mutmut, etc.), and the strategic distinction between mutation score as a target (anti-pattern) and the survived-mutant list as a to-do (correct use).
+
+## Philosophy
+
+Mutation testing inverts the coverage question. Coverage asks: did the test reach this line? Mutation asks: would the test catch a defect at this line? The second question is closer to what we actually care about, and the answer is more specific: each survived mutant is a directly addressable test-suite gap with a known location and a known kind of defect.
+
+The discipline is not in maximizing the score; it is in reading the survived-mutant list. Each survivor is either a real gap (the test suite does not verify this behavior — write the test), an equivalent mutant (the syntactic change has no observable effect — exclude it), or an intentional non-test (defensive check, log string, debug path — note it as intentional). Working through the list with this classification produces a stronger test suite without engineering tests to satisfy the metric.
+
+Mutation testing's modern feasibility is what makes it strategic. A decade ago the technique was largely impractical for large codebases. Today's tools — PIT's bytecode mutation, Stryker's incremental analysis, distributed execution, test prioritization — run mutation testing in CI in minutes for codebases of hundreds of thousands of lines. The cost barrier that historically pushed teams to coverage as a substitute is largely gone.
+
+## Mutation Operator Catalog (Selective Set)
+
+| Operator | Example | Catches |
+|---|---|---|
+| Conditional Boundary | `<` → `<=` | Off-by-one in comparisons |
+| Negate Conditionals | `==` → `!=` | Inverted-condition bugs |
+| Math | `+` → `-`, `*` → `/` | Arithmetic mistakes |
+| Increments | `i++` → `i--` | Loop-direction bugs |
+| Invert Negatives | `-x` → `x` | Sign errors |
+| Return Values | `return x` → `return null` | Missing return assertions |
+| Void Method Calls | `obj.set(x)` → `(no-op)` | Missing-side-effect bugs |
+| Empty Returns | replace return with type's empty/default | Caught only if downstream uses the value |
+| Constants | `42` → `43`, `true` → `false` | Magic-number assertions |
+
+The Offutt et al. selective subset (about 5-8 operators) captures most of the signal of the full operator set at a fraction of the cost.
+
+## Mutation vs Coverage — The Composition
+
+| Aspect | Coverage | Mutation |
+|---|---|---|
+| What it measures | Did the tests execute this code? | Would the tests catch a defect here? |
+| Signal direction | Floor (uncovered = unverified) | Direct measure of verification |
+| Cost | Low — incremental with test execution | Higher — one test run per mutant |
+| Goodhart susceptibility | High (easy to game) | Lower (harder to engineer to without writing real tests) |
+| Precondition | None | Coverage at the location |
+| Diagnostic output | Map of unreached lines | List of survived mutants |
+
+A mature test-quality strategy uses coverage as the floor (reach everything important) and mutation as the verification signal (verify everything reached).
+
+## Working With Survived Mutants
+
+A survived mutant is not automatically a test bug. Classify each:
+
+1. **Real test gap** — the mutant alters observable behavior and no test catches it. Action: write the missing test.
+2. **Equivalent mutant** — the syntactic change has no observable effect. Action: mark as equivalent; some tools support inline suppression.
+3. **Intentional non-test** — the code is intentionally unverified (defensive check, log message, debug path). Action: annotate; consider whether the policy should change.
+4. **Off-scope code** — generated code, vendor code, scaffolding. Action: exclude from mutation analysis.
+
+A test suite that addresses the real-test-gap survivors and accepts the rest will see its mutation score climb organically — and, more importantly, its real defect-detection rate.
+
+## Incremental CI Integration
+
+The pattern that makes mutation testing practical in continuous integration:
+
+1. Compute the set of changed files in the PR.
+2. Generate mutants only on changed lines (PIT: `--targetTests` + diff-aware mode; Stryker: incremental mode).
+3. Run the affected tests against each mutant.
+4. Report new survivors on changed code.
+5. Block (or warn on) PRs that introduce new survivors above threshold.
+
+This scales to large codebases because the work per PR is bounded by the PR's size, not the codebase's size.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Mutation testing is paired with coverage, not used as a replacement. Coverage measures reach; mutation measures verification.
+- [ ] The mutation operator set in use is named and documented (full / selective Offutt subset / custom).
+- [ ] Survived mutants are classified (real gap / equivalent / intentional non-test / off-scope), not treated as a uniform list of bugs.
+- [ ] Mutation score is read as a list-of-actions summary, not as a target to engineer toward. Hard merge-gates on the score are avoided unless paired with explicit anti-Goodhart policies.
+- [ ] Equivalent-mutant noise is acknowledged (5-15% typical) and either accepted in the raw score or excluded from a published adjusted score.
+- [ ] For CI integration, incremental mutation on changed code is used; full mutation runs are scheduled (nightly, weekly) rather than blocking every PR.
+- [ ] Mutation testing is not applied to dead code, generated code, or off-scope code that produces noise without value.
+- [ ] The team can name the operator that caused each surviving mutant (off-by-one, condition negation, etc.) — the survival's *kind* is part of the diagnostic, not just the count.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Measuring how much of the code the test suite reaches | `test-coverage-strategy` | coverage measures structural reach; this skill measures behavioral verification |
+| Designing test doubles (mocks, stubs, fakes) | `test-doubles-design` | test-doubles owns stand-in construction; this skill measures whether the resulting tests verify behavior |
+| Choosing test levels (unit/integration/e2e) | `testing-strategy` | testing-strategy owns the strategic level question |
+| Injecting failures into a deployed system | `chaos-engineering` | chaos is runtime fault injection; this skill is build-time source-code mutation |
+| Generating input variations to find crashes | fuzz-testing skill | fuzzing varies inputs; this skill varies the program |
+| Iterating on LLM behavior via evals | `eval-driven-development` | eval-driven-development is the LLM analog; mutation testing is for deterministic code |
+
+## Key Sources
+
+- DeMillo, R. A., Lipton, R. J., & Sayward, F. G. (1978). ["Hints on Test Data Selection: Help for the Practicing Programmer"](https://ieeexplore.ieee.org/document/1646911). *IEEE Computer*, 11(4), 34-41. The foundational paper introducing the mutation-testing concept and the competent-programmer / coupling-effect hypotheses that justify the technique.
+- Jia, Y., & Harman, M. (2011). ["An Analysis and Survey of the Development of Mutation Testing"](https://ieeexplore.ieee.org/document/5487526). *IEEE Transactions on Software Engineering*, 37(5), 649-678. The canonical comprehensive survey of mutation testing across decades of research.
+- Just, R., Jalali, D., Inozemtseva, L., Ernst, M. D., Holmes, R., & Fraser, G. (2014). ["Are Mutants a Valid Substitute for Real Faults in Software Testing?"](https://dl.acm.org/doi/10.1145/2635868.2635929). *FSE 2014*. The empirical study showing mutation score correlates with real fault-detection rate, validating mutation as a meaningful proxy.
+- Andrews, J. H., Briand, L. C., & Labiche, Y. (2005). ["Is Mutation an Appropriate Tool for Testing Experiments?"](https://dl.acm.org/doi/10.1145/1062455.1062530). *ICSE 2005*. Earlier empirical study supporting mutation as a valid measure of test-suite effectiveness.
+- Offutt, A. J., Lee, A., Rothermel, G., Untch, R. H., & Zapf, C. (1996). ["An Experimental Determination of Sufficient Mutant Operators"](https://dl.acm.org/doi/10.1145/227607.227610). *ACM Transactions on Software Engineering and Methodology*, 5(2), 99-118. The selective-mutation paper that established the small operator subset capturing most signal at a fraction of the cost.
+- Coles, H. ["PIT Mutation Testing — Documentation"](https://pitest.org/). The reference for the canonical JVM mutation-testing tool; bytecode mutation, incremental analysis, CI integration.
+- Stryker Mutator. ["Stryker — Documentation"](https://stryker-mutator.io/). The reference for the JS/TS/.NET/Scala mutation-testing tool; framework-integrated and source-level.
+- Inozemtseva, L., & Holmes, R. (2014). ["Coverage Is Not Strongly Correlated with Test Suite Effectiveness"](https://dl.acm.org/doi/10.1145/2568225.2568271). *ICSE 2014*. Adjacent finding: coverage's weak correlation with effectiveness is part of why mutation matters as a stronger signal.

package/marketplace/skills/naming-conventions/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: naming-conventions
+description: "Use when naming a new file, function, variable, type, route, database column, environment variable, or any other code or system artifact. Covers identifier morphology (verb-noun choice, plural vs singular, prefix/suffix conventions), kebab-case vs camelCase vs snake_case vs PascalCase per artifact kind, abbreviation rules, name-vs-path semantics, the rename-coordination workflow, and detection of names that lie. Do NOT use for content writing (use `documentation`), for restructuring already-named code (use `refactor`), or for human-language copy in product UI (separate skill, not in this library)."
+license: MIT
+compatibility: Language-agnostic
+allowed-tools: Read Grep Bash Edit
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-04\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-04\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"naming\\\\\\\",\\\\\\\"naming convention\\\\\\\",\\\\\\\"name a file\\\\\\\",\\\\\\\"name a function\\\\\\\",\\\\\\\"name a variable\\\\\\\",\\\\\\\"name a type\\\\\\\",\\\\\\\"rename\\\\\\\",\\\\\\\"identifier\\\\\\\",\\\\\\\"kebab case\\\\\\\",\\\\\\\"camel case\\\\\\\",\\\\\\\"snake case\\\\\\\",\\\\\\\"pascal case\\\\\\\",\\\\\\\"abbreviation\\\\\\\",\\\\\\\"prefix suffix\\\\\\\",\\\\\\\"what to call this\\\\\\\",\\\\\\\"this name doesn't fit\\\\\\\",\\\\\\\"the name lies\\\\\\\",\\\\\\\"misleading name\\\\\\\"]\",\"examples\":\"[\\\\\\\"what should I name this util that converts between order shapes?\\\\\\\",\\\\\\\"is `isValidUser` or `validateUser` the right name for this guard?\\\\\\\",\\\\\\\"this function is called `getThing` but it also writes to disk — rename it\\\\\\\",\\\\\\\"kebab-case or snake_case for a new database column?\\\\\\\",\\\\\\\"the type is called `Result` but it's specifically the order-pricing result — rename\\\\\\\",\\\\\\\"should I prefix this hook with `use` or just call it `subscribeOrders`?\\\\\\\",\\\\\\\"we have `User` and `UserAccount` and `AccountUser` — which means what?\\\\\\\",\\\\\\\"rename plan: this column was called `created` but it stores the ship date\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"refactor this 200-line function into smaller pieces\\\\\\\",\\\\\\\"write a doc explaining our naming conventions\\\\\\\",\\\\\\\"review this PR's naming choices\\\\\\\",\\\\\\\"the variable named `userIsActive` is logging the wrong value\\\\\\\",\\\\\\\"scaffold a new skill that teaches naming conventions\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"refactor\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"refactor reshapes existing code structure; naming-conventions decides what an artifact should be CALLED, before or independently of restructuring\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"code-review\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"code-review evaluates a diff holistically; naming-conventions is the focused naming-decision skill invoked during authoring\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"debugging\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"debugging chases observed wrong behaviour; naming-conventions catches names that LIE about their meaning before the bug ships\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"refactor\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"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/naming-conventions/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/naming-conventions/SKILL.md
+---
+
+# Naming Conventions
+
+## Coverage
+
+- Identifier morphology: verb-noun selection (`get` vs `fetch` vs `load`), plural vs singular for collections, prefix/suffix conventions (`is` / `has` / `should` for booleans, `use` for React hooks)
+- Casing per artifact kind: kebab-case (file names, URL paths, CLI flags), camelCase (JavaScript/TypeScript variables and functions), PascalCase (types, classes, components, React JSX), snake_case (Python, SQL columns, environment variables when convention demands), SCREAMING_SNAKE_CASE (constants, env-var keys)
+- Abbreviation rules: when an abbreviation is universally known (`url`, `id`, `api`), when it requires expansion (`cust` → `customer`), and when team-internal jargon must be avoided in public-facing names
+- Name-vs-path semantics: the difference between *what an artifact is called* and *where it lives*; when name and path agree (file system) vs when they diverge (TypeScript module re-exports, npm-published package paths)
+- Rename coordination: how to update every reference in the same commit, when to ship a deprecation alias, and how to detect missed call sites with grep
+- Names that lie: identifiers whose words promise a behaviour the code does not deliver, and how to detect them (the function called `getX` that also writes; the boolean called `isReady` that means "should be ready"; the column called `created` that stores the ship date)
+- Cross-cutting consistency: when a naming choice in one part of the codebase forces a related choice elsewhere (table column `customer_id` and TypeScript type `Customer.id`)
+
+## Philosophy
+
+Names are the most-read part of any codebase. Every reader pays the cost of a bad name; only the author pays the cost of choosing well. The single most valuable property of a name is *truthfulness*: a name that lies — about what an artifact does, returns, or means — is more harmful than a name that is merely unclear. The second-most-valuable property is *consistency with sibling names*: a function called `getOrders` should sit alongside `getCustomers`, not `loadCustomers`. The third is *brevity*, and only the third — short names that mislead are not a virtue.
+
+When a name does not fit, the answer is almost always to rename, not to add a comment explaining what the name "really" means. Comments rot; renames travel with the code.
+
+## Casing per Artifact Kind
+
+Casing is project-convention-driven for the artifacts where languages don't enforce it, and language-mandated for the rest. Pick the convention once, document it in the project's CONTRIBUTING or AGENTS file, and apply it everywhere.
+
+| Artifact | Convention | Example |
+|---|---|---|
+| File name (any) | kebab-case | `order-pricing.ts`, `webhook-handler.py` |
+| URL path segment | kebab-case | `/api/order-pricing` |
+| CLI flag | kebab-case | `--include-template` |
+| JS/TS variable, function, parameter | camelCase | `orderTotal`, `calculateMargin()` |
+| JS/TS type, class, interface, React component | PascalCase | `Order`, `OrderPricing`, `<OrderRow/>` |
+| Python variable, function | snake_case | `order_total`, `calculate_margin` |
+| Python class | PascalCase | `Order`, `OrderPricing` |
+| SQL table name | snake_case (lowercase) | `orders`, `order_line_items` |
+| SQL column name | snake_case | `created_at`, `customer_id` |
+| Environment variable | SCREAMING_SNAKE_CASE | `STRIPE_SECRET_KEY`, `NODE_ENV` |
+| Constant in code | SCREAMING_SNAKE_CASE | `MAX_RETRIES`, `DEFAULT_TIMEOUT_MS` |
+| Boolean variable / function | `is*` / `has*` / `should*` / `can*` prefix | `isAdmin`, `hasReceipt`, `shouldRetry` |
+| React hook | `use*` prefix (mandatory) | `useOrders`, `useDebounce` |
+| Predicate function | verb in interrogative form | `validateEmail()`, `isValidEmail()` |
+
+## Identifier Morphology
+
+The verb you pick encodes a contract. Choose deliberately.
+
+| Verb | Implies | Wrong when |
+|---|---|---|
+| `get` | Pure read; cheap; never mutates; idempotent | The function writes, calls an API, or has any side effect |
+| `fetch` | Network or I/O read; may fail; may be slow | The function reads from local memory or never crosses a boundary |
+| `load` | Read-and-cache, or read-from-disk; one-shot | The function returns synchronously from already-loaded data |
+| `compute` / `calculate` | Pure transformation of inputs | The function takes no inputs or returns I/O |
+| `validate` | Returns boolean OR throws; no side effects | The function modifies the input or has hidden side effects |
+| `assert` | Throws on failure; void return on success | The function returns a value or has a happy non-throwing path |
+| `parse` | String → structured data; may throw on malformed input | The function takes structured data or never throws |
+| `format` | Structured data → string | The function returns structured data |
+| `create` | Allocates/persists a new entity; returns its identity | The function returns a transient value with no persisted identity |
+| `update` | Modifies an existing entity by identity | The function inserts or replaces |
+| `delete` / `remove` | Removes an entity from the system | The function only removes from a transient view |
+
+The single most common naming bug is `getX` that also writes. If the function has a side effect, the verb must be one that *implies* side effects (`save`, `apply`, `commit`, `flush`, `record`).
+
+## Names That Lie
+
+A name lies when its words promise behaviour the code does not deliver. Detecting these costs nothing at authoring time and saves real debugging time later.
+
+- **Verb mismatch**: `getThing()` that calls a remote API, `validate()` that throws, `parse()` that returns null on failure (it should throw or be renamed `tryParse`).
+- **Boolean polarity inversion**: `isInvalid` set to `true` to mean valid; the codebase will eventually have `if (!isInvalid)` and someone will read it backwards. Use `isValid` and invert the value.
+- **Optional collapse**: `getOrder()` that returns `Order | undefined`. The caller has no way to know the function can return undefined without reading the implementation. Either rename to `findOrder()` (convention: "find" allows null return) or change to `getOrderOrThrow()`.
+- **Stale meaning after refactor**: a column originally named `created` that, after a migration, now stores the ship date. The name predates the meaning. Rename the column AND all of its callers in the same commit.
+- **Domain-language drift**: code says `User` but the domain glossary says `Account`. Pick one in the glossary and rename in code.
+
+## Rename Coordination
+
+Renaming is a small change that touches many places. Do all of them in one commit; ship none of them piecemeal.
+
+1. **Pick the new name** by the rules above.
+2. **Find every call site**: `grep -rn "OldName" --include="*.ts" --include="*.tsx" --include="*.md"` (and equivalent for your language). Don't trust IDE rename — it misses dynamic references and string literals.
+3. **Update all references** in one diff. The diff stat should show the rename and nothing else. If you find yourself fixing other things along the way, split the commits.
+4. **Decide on a deprecation alias** when external consumers may have pinned to the old name. Export both names for one minor version; remove the old name in the next minor.
+5. **Run the lint and test suite** to catch dynamic references the grep missed (e.g., reflection, template strings, JSON config).
+6. **Update docs** in the same commit. Stale docs are a naming bug.
+
+## Verification
+
+- [ ] The name is *truthful* — every word in the name describes behaviour the code actually delivers
+- [ ] The casing matches the artifact-kind convention (file kebab, type PascalCase, env SCREAMING_SNAKE)
+- [ ] The verb implies the right cost class (`get` is cheap, `fetch` may fail, `compute` is pure)
+- [ ] Boolean prefix is positive polarity (`isValid` not `isInvalid`)
+- [ ] Sibling artifacts use the same verb stem (don't mix `getOrders` with `loadCustomers`)
+- [ ] No team-internal jargon in public-facing names (file names, route paths, error messages)
+- [ ] Rename diffs touch ALL references in one commit, including docs and tests
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `refactor` | Restructuring already-named code (extract function, inline variable, split file) — naming may change as a side effect of the refactor |
+| `documentation` | Writing prose explanation of a naming convention — this skill makes the choice; documentation explains it |
+| `code-review` | Evaluating a whole PR — naming is one of many concerns the reviewer covers |
+| `debugging` | Investigating why a misnamed identifier produces wrong behaviour — debugging chases the bug; naming-conventions prevents the next one |

package/marketplace/skills/observability-modeling/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: observability-modeling
+description: "Use when designing telemetry semantics before or during implementation: logs, metrics, traces, events, spans, attributes, correlation IDs, SLOs, alert signals, and diagnostic questions. Do NOT use for domain/business event contracts (use `event-contract-design`), configuring an error tracker alone (use `error-tracking`), performance optimization (use `performance-engineering`), or debugging a current incident (use `debugging`)."
+license: MIT
+compatibility: "Portable observability modeling discipline for applications, integrations, jobs, queues, APIs, and agent workflows."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/observability\",\"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\":\"[\\\\\\\"observability modeling\\\\\\\",\\\\\\\"telemetry design\\\\\\\",\\\\\\\"logs metrics traces\\\\\\\",\\\\\\\"SLO\\\\\\\",\\\\\\\"spans\\\\\\\",\\\\\\\"correlation id\\\\\\\",\\\\\\\"diagnostic events\\\\\\\",\\\\\\\"alert design\\\\\\\",\\\\\\\"instrumentation model\\\\\\\"]\",\"examples\":\"[\\\\\\\"design telemetry for this ingestion pipeline so failures can be diagnosed later\\\\\\\",\\\\\\\"which logs, metrics, spans, and correlation IDs should this interface contract require?\\\\\\\",\\\\\\\"model observability for a background job before adding alerts\\\\\\\",\\\\\\\"turn these diagnostic questions into events and metrics\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"set up Sentry error tracking for this app\\\\\\\",\\\\\\\"profile and optimize a slow endpoint\\\\\\\",\\\\\\\"debug the current production incident\\\\\\\",\\\\\\\"write application tests for this feature\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"error-tracking\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"error-tracking owns error-capture setup and handling; observability-modeling owns the broader telemetry schema\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"event-contract-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"event-contract-design owns published business event contracts; observability-modeling owns telemetry events, spans, metrics, and logs for diagnosability\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"performance-engineering\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"performance-engineering improves measured performance; observability-modeling defines the signals needed to measure and diagnose\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"debugging\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"debugging investigates a current failure; observability-modeling designs future diagnosability\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"testing-strategy proves behavior in tests; observability-modeling proves runtime diagnosability\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"error-tracking\\\\\\\",\\\\\\\"performance-engineering\\\\\\\",\\\\\\\"system-interface-contracts\\\\\\\",\\\\\\\"event-contract-design\\\\\\\",\\\\\\\"debugging\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"error-tracking\\\\\\\",\\\\\\\"debugging\\\\\\\"]}\",\"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/observability-modeling/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/observability-modeling/SKILL.md
+---
+
+# Observability Modeling
+
+## Coverage
+
+Design telemetry semantics that make systems diagnosable. Covers diagnostic questions, logs, metrics, traces, spans, events, attributes, correlation IDs, SLOs, alert signals, cardinality, privacy, sampling, and contract-level observability requirements.
+
+## Philosophy
+
+Observability starts with questions, not tools. "Can we answer why this order failed to sync?" is a better design input than "add logs." Tool setup without a telemetry model produces noisy data and weak diagnosis.
+
+Instrument boundaries, state changes, and decisions. Avoid high-cardinality or sensitive fields unless the operational value justifies the risk.
+
+## Method
+
+1. List diagnostic questions the system must answer.
+2. Map each question to required signals: log, metric, trace, event, or derived view.
+3. Define correlation identifiers across boundaries.
+4. Name span/event attributes with stable semantics and cardinality limits.
+5. Add SLOs and alert signals only for user or business impact.
+6. Define privacy redaction and sampling rules.
+7. Verify that failures can be reconstructed from emitted signals.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/observability-modeling.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/observability-modeling.json). The checklist below is the authoring gate for telemetry-semantics decisions; the eval file is the grader surface.
+
+## Verification
+
+- [ ] Telemetry answers named diagnostic questions
+- [ ] Correlation IDs cross async and external boundaries
+- [ ] Event and metric names use stable domain language
+- [ ] High-cardinality attributes are avoided or justified
+- [ ] Sensitive data is redacted before emission
+- [ ] Alerts map to actionable symptoms, not raw noise
+- [ ] A realistic failure can be reconstructed from the proposed signals
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `error-tracking` | You need error tracker setup, redaction, source maps, or issue triage. |
+| `event-contract-design` | You need a business/domain event envelope, schema, topic, replay, or consumer compatibility contract. |
+| `performance-engineering` | You need to profile and optimize latency, throughput, or resource use. |
+| `debugging` | There is already a failing incident or reproducible bug. |
+| `testing-strategy` | You need pre-runtime test coverage design. |