@skill-graph/cli 0.5.6

package/marketplace/skills/e2e-test-design/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: e2e-test-design
+description: "Use when designing end-to-end tests that exercise a user-visible path through the whole system, including the UI layer: the user-journey unit-of-test that distinguishes e2e from integration testing, the five-primitive structure (user journey, environment, test data, observable assertion, recovery), why e2e tests are expensive and how to keep them few-and-load-bearing, the wait/synchronization discipline that makes them not-flaky, the page-object and trace-test patterns, the role of e2e tests in the test pyramid/trophy (the top tier — fewest in count but highest in coverage of user-observable behavior), and the modern e2e tool landscape (Playwright, Cypress, Selenium). Do NOT use for testing internal seams of the system (use integration-test-design), single-unit isolated tests (use testing-strategy + test-doubles-design), consumer-driven contract verification (use contract-testing), or visual regression of specific components (use snapshot-testing)."
+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\":\"[\\\\\\\"end-to-end testing\\\\\\\",\\\\\\\"e2e test\\\\\\\",\\\\\\\"user journey test\\\\\\\",\\\\\\\"Playwright\\\\\\\",\\\\\\\"Cypress\\\\\\\",\\\\\\\"Selenium\\\\\\\",\\\\\\\"page object\\\\\\\",\\\\\\\"test flake\\\\\\\",\\\\\\\"wait strategy\\\\\\\",\\\\\\\"trace test\\\\\\\",\\\\\\\"smoke test\\\\\\\"]\",\"triggers\":\"[\\\\\\\"do we need e2e tests\\\\\\\",\\\\\\\"the e2e tests are flaky\\\\\\\",\\\\\\\"Playwright vs Cypress\\\\\\\",\\\\\\\"how many e2e tests is too many\\\\\\\",\\\\\\\"page object pattern\\\\\\\"]\",\"examples\":\"[\\\\\\\"design an e2e test suite for an onboarding journey: signup → email verify → first action\\\\\\\",\\\\\\\"decide which user journeys deserve e2e coverage vs integration-test coverage\\\\\\\",\\\\\\\"diagnose flaky e2e tests — usually wait-strategy or test-data problems\\\\\\\",\\\\\\\"explain why fewer e2e tests with higher load-bearing value beats many e2e tests with low value\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"test internal seams of the system (use integration-test-design)\\\\\\\",\\\\\\\"test a single component in isolation (use testing-strategy + test-doubles-design)\\\\\\\",\\\\\\\"verify a service's contract against consumers (use contract-testing)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"integration-test-design\\\\\\\",\\\\\\\"snapshot-testing\\\\\\\",\\\\\\\"test-driven-development\\\\\\\",\\\\\\\"contract-testing\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"testing-strategy owns the strategic ratio of test levels; this skill owns the design of the e2e tier specifically — the smallest tier in the pyramid/trophy, the most expensive per test, the most user-meaningful per test.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"integration-test-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"integration-test-design owns tests of internal seams between units; this skill owns user-journey tests through the whole stack including UI. The cost difference is an order of magnitude; conflating them either inflates CI cost or misses real e2e coverage.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"contract-testing\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"contract-testing verifies the interface between consumer and provider via consumer-driven contracts; this skill verifies the user-journey behavior end-to-end. Contracts replace e2e tests across service boundaries when the journey is service-to-service; e2e is for journeys with humans at one end.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"snapshot-testing\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"Visual snapshot tests are a regression net at e2e or component scope; this skill owns the user-journey behavior end-to-end. They compose: visual snapshots within e2e tests catch UI changes the journey assertions don't.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"integration-test-design\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"An e2e test is to a software system what a flight rehearsal is to a launch — you do not certify a rocket by testing each bolt in a clean room (units), nor by firing each engine in isolation (integration), nor by writing a specification of what the avionics should do (contract); you certify it by performing the entire launch sequence, with real fuel, against a real flight plan, with the actual crew, and you do this rarely because each rehearsal costs millions and ten high-fidelity rehearsals tell you more than a thousand quick ones.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"End-to-end (e2e) test design is the discipline of designing tests that exercise a complete user-visible path through the entire system — the UI, the application layer, the data layer, external integrations, and back. The unit of test is the *user journey*: a sequence of user actions and the observable outcomes the user experiences. E2e tests are the highest-scope tier of the test pyramid (or trophy) — the fewest in count, the slowest per test, the most user-meaningful per test. Their value is the confidence that the system, assembled, works for a real user task; their cost is real and growing with the system's complexity. The discipline of e2e test design is keeping the count small enough that the cost stays manageable while keeping the coverage broad enough that the tests are load-bearing evidence the system works for users.\\\\\\\",\\\\\\\"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/e2e-test-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/e2e-test-design/SKILL.md
+---
+
+# E2e Test Design
+
+## Coverage
+
+The discipline of designing tests that exercise a complete user-visible path through the entire system — UI, application, data, third parties, and back — with the user journey as the unit of test. Covers the five primitives (journey, environment, test data, observable assertion, wait strategy), the pyramid/trophy position (top tier, fewest tests, highest cost, highest user-meaningful coverage), the test-data strategies that determine isolation and flake rate, the wait-for-condition synchronization discipline that prevents flake, the framework landscape (Playwright, Cypress, Selenium, Puppeteer), and the cost-and-count trade-off that distinguishes good e2e suites from over-investment.
+
+## Philosophy
+
+E2e tests are the smallest tier of the test suite by count and the largest by individual cost. They are the evidence that the *assembled system* works for *real users*; nothing else in the test suite provides that evidence. They are also the most expensive tests to write, run, and maintain.
+
+The discipline is making each e2e test *load-bearing*: covers a journey that matters; asserts outcomes that prove the system works for users; runs reliably with near-zero flake. A team with one hundred low-value flaky e2e tests is worse off than a team with ten high-value reliable e2e tests, because trust in the suite — the willingness to take a red build as evidence of a real bug — is the suite's value.
+
+The right e2e count is much lower than most teams intuit. The pyramid/trophy framings put e2e at the top — fewest tests, by design. Teams that grow e2e suites to hundreds of tests usually have many tests that should be integration tests; the discipline is reversing that drift.
+
+## What An E2e Test Looks Like
+
+| Component | Detail |
+|---|---|
+| Scope | A complete user journey (signup, checkout, primary creative action) |
+| Environment | Production-like; all real components, recorded fakes for paid third parties |
+| Stack | Full UI, application, database, message bus, file storage |
+| Test data | Isolated per test, typically via per-test user accounts with unique IDs |
+| Assertions | DOM elements visible, URL changes, key user-observable outcomes |
+| Wait strategy | Wait-for-condition with generous timeouts; never hardcoded delays |
+| Diagnostics | Screenshot on failure, video capture, trace viewer for replay |
+| Runtime | Seconds to tens of seconds per test |
+| Suite size | 10-50 critical-path; 50-200 for broader regression |
+| Suite runtime | Under 30 minutes total via parallelization |
+
+## The Wait-Strategy Discipline
+
+E2e flake's primary cause is bad synchronization. The discipline:
+
+| Anti-pattern | Pattern |
+|---|---|
+| `page.click('button'); sleep(2); expect(elem).toBeVisible()` | `page.click('button'); await expect(elem).toBeVisible()` (auto-waits up to timeout) |
+| `sleep(5); expect(toast).toBe('Saved')` | `await expect(toast).toBe('Saved', { timeout: 10_000 })` (retries until match) |
+| `page.click('a'); sleep(3); page.click('next')` | `page.click('a'); await page.waitForURL(/expected/); page.click('next')` |
+| Hardcoded delay for network call | `await page.waitForResponse(predicate)` |
+| Hardcoded delay for animation | Animation-aware wait or disable animations in test config |
+
+Playwright, Cypress, and Selenium all support wait-for-condition. The discipline is using it everywhere instead of `sleep`.
+
+## Test-Data Strategy Comparison
+
+| Strategy | Speed | Isolation | Best for |
+|---|---|---|---|
+| Fresh environment per test | Slowest | Strongest | Highest-stakes journeys; very few tests |
+| Per-test data with unique IDs | Fast | Strong | Most production e2e suites |
+| Fixture seed + per-user partition | Fast | Strong (if partition discipline holds) | Suites with shared lookup data |
+| Shared snapshot, read-only discipline | Fastest | Relies on discipline | Pure read flows; rare |
+
+Per-test data with unique IDs is the working standard. Each test creates the users, orders, or whatever entities it needs, with IDs that don't collide with other tests. Cleanup happens at test end or suite end.
+
+## Framework Selection
+
+| Framework | Strengths | Weaknesses | Best fit |
+|---|---|---|---|
+| Playwright | Modern, fast, multi-browser, auto-waiting, trace viewer | Newer ecosystem, smaller community than Selenium | New projects; recommended default |
+| Cypress | Excellent DX, retry-until-pass, in-browser test execution | Chromium-family focused, iframe and tab handling awkward | Developer-experience-focused teams |
+| Selenium WebDriver | Largest ecosystem, cross-language, every browser | Slower, more boilerplate, more flake-prone without careful setup | Large enterprise / legacy / cross-browser-matrix |
+| Puppeteer | Lower-level Chrome API | Chromium-only, less abstraction | Lower-level scripting and scraping |
+| Detox / Appium / Maestro | Mobile-native | Mobile-only | Mobile app e2e |
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Every e2e test covers a complete user journey, not a UI interaction in isolation. "Click this button" is not an e2e test; "complete signup" is.
+- [ ] The test environment is production-like: real UI, real backend, real database, real message bus. Recorded fakes are used only for paid or unavailable third parties.
+- [ ] Wait strategy is wait-for-condition with generous timeouts everywhere. No hardcoded `sleep` calls.
+- [ ] Test data is isolated per test (per-test user accounts with unique IDs, or per-test data with cleanup). Shared mutable state is the flake source.
+- [ ] Each e2e test has a clear load-bearing reason for existing — names a journey that matters, asserts an outcome that would not be caught by a lower-tier test.
+- [ ] Suite size and runtime are tracked. Suites trending toward 500+ tests or 30+ minutes are diagnosed; many should be lower-tier tests.
+- [ ] Flake rate is monitored and held near zero. Flaky tests are diagnosed and fixed, not retried-and-ignored.
+- [ ] Failure diagnostics (screenshot, video, trace) are configured so that test failures are debuggable from the CI artifacts.
+- [ ] E2e tests run on every PR (critical-path subset) and on every merge or nightly (broader regression). They are not the primary test for behaviors lower-tier tests can verify.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Testing an internal seam between modules | `integration-test-design` | integration tests are cheaper and faster for non-user-journey verification |
+| Testing a single unit in isolation | `testing-strategy` + `test-doubles-design` | unit-scope is much cheaper for implementation-detail verification |
+| Verifying a service-to-service contract | `contract-testing` | contract tests are more targeted than e2e for service-boundary verification |
+| Visual regression of a specific component | `snapshot-testing` | snapshot is cheaper and more targeted than e2e for visual regression |
+| Choosing the ratio of test levels | `testing-strategy` | strategy owns ratios; this skill owns e2e-tier design |
+| Measuring whether the test suite catches defects | `mutation-testing` | mutation is the test-suite quality signal; this skill is e2e tier design |
+
+## Key Sources
+
+- Cohn, M. (2009). *Succeeding with Agile: Software Development Using Scrum*. The test pyramid framing places e2e at the top tier; canonical reference for why e2e count should be small.
+- Fowler, M. (2012). ["The Practical Test Pyramid"](https://martinfowler.com/articles/practical-test-pyramid.html). Practitioner essay on the pyramid; sections on UI/e2e tests' cost-benefit profile.
+- Dodds, K. C. (2018). ["The Testing Trophy and Testing Classifications"](https://kentcdodds.com/blog/the-testing-trophy-and-testing-classifications). Alternative framing that retains e2e at the top tier with similar cost-and-count reasoning.
+- Microsoft / Playwright Team. ["Playwright — Documentation"](https://playwright.dev/docs/intro). Canonical reference for the modern multi-browser e2e framework; includes the auto-waiting and trace-viewer discipline.
+- Cypress.io. ["Cypress — Documentation"](https://docs.cypress.io/). Canonical reference for the Cypress framework; includes the retry-until-pass assertion model and the in-browser test execution architecture.
+- Selenium Project. ["Selenium WebDriver — Documentation"](https://www.selenium.dev/documentation/webdriver/). The canonical cross-language WebDriver protocol reference; foundation for many derived tools.
+- Meszaros, G. (2007). *xUnit Test Patterns: Refactoring Test Code*. Catalog includes e2e-relevant patterns for test data lifecycle, shared fixtures, and test independence.
+- Fowler, M. ["Page Object"](https://martinfowler.com/bliki/PageObject.html). The canonical reference for the page-object pattern; useful for organizing large e2e suites.
+- Google Testing Blog. ["Testing on the Toilet — Just say no to more end-to-end tests"](https://testing.googleblog.com/2015/04/just-say-no-to-more-end-to-end-tests.html). Industrial perspective on why more e2e tests is usually the wrong response to bug pressure.
+- North, D. ["BDD as Outside-In Development"](https://dannorth.net/introducing-bdd/). Adjacent thread: BDD's outside-in style produces user-journey-scope tests at the outermost layer, conceptually aligned with e2e.

package/marketplace/skills/entity-relationship-modeling/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: entity-relationship-modeling
+description: "Use when designing database tables, reviewing schema changes, planning migrations, or translating conceptual models into physical database structures. Covers ER notation, entity/attribute/key design, normalization and denormalization, junction tables, inheritance mapping, temporal modeling, ER-to-SQL translation, indexing, and constraints. Do NOT use for conceptual domain analysis (use `conceptual-modeling`), formal ontology (use `ontology`), or cross-system API contracts (use `system-interface-contracts`)."
+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\":\"engineering\",\"domain\":\"engineering/modeling\",\"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\":\"[\\\\\\\"entity relationship\\\\\\\",\\\\\\\"ER diagram\\\\\\\",\\\\\\\"ER model\\\\\\\",\\\\\\\"database design\\\\\\\",\\\\\\\"schema design\\\\\\\",\\\\\\\"normalization\\\\\\\",\\\\\\\"foreign key\\\\\\\",\\\\\\\"primary key\\\\\\\",\\\\\\\"junction table\\\\\\\",\\\\\\\"database modeling\\\\\\\"]\",\"triggers\":\"[\\\\\\\"er-modeling-skill\\\\\\\",\\\\\\\"database-design-skill\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"database-migration\\\\\\\"],\\\\\\\"boundary\\\\\\\":[\\\\\\\"conceptual-modeling\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"code-review\\\\\\\"]}\",\"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/entity-relationship-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/entity-relationship-modeling/SKILL.md
+---
+# Entity-Relationship Modeling
+
+## Domain Context
+
+**What is this skill?** This skill provides entity-relationship (ER) modeling patterns for designing database schemas from domain requirements: Chen notation and Crow's Foot notation, entity identification and attribute analysis, primary/foreign key design, normalization (1NF through BCNF), denormalization trade-offs, junction table patterns, inheritance mapping strategies (single-table, class-table, concrete-table), temporal data modeling, and schema evolution/migration patterns. Covers the ER-to-SQL translation pipeline, indexing strategy from access patterns, constraint specification (NOT NULL, UNIQUE, CHECK, FK), and anti-patterns like EAV abuse, polymorphic associations, and over-normalization. Use when designing new database tables, reviewing schema changes, planning migrations, or translating conceptual models into physical database structures. Do NOT use for conceptual domain analysis (use `conceptual-modeling`), formal ontology (use `ontology`), or cross-system data mapping (use `relational-mapping`).
+
+## Coverage
+
+Entity-relationship modeling for database schema design: Chen notation and Crow's Foot notation, entity identification and attribute analysis, primary/foreign key design (natural vs. surrogate, UUID vs. serial), normalization forms (1NF through BCNF) with trade-off analysis, denormalization patterns for read performance, junction table design for M:N relationships, inheritance mapping strategies (single-table, class-table, concrete-table), temporal data modeling (SCD Type 1/2/3, bi-temporal), schema evolution and migration patterns, ER-to-SQL translation, indexing strategy from access patterns, constraint specification (NOT NULL, UNIQUE, CHECK, FK, EXCLUDE), and anti-patterns (EAV, polymorphic associations, over-normalization, mega-tables). Does not cover conceptual domain analysis (`conceptual-modeling`), formal ontology (`ontology`), or cross-system data mapping (`relational-mapping`).
+
+## Philosophy
+
+A database schema is a commitment about what the business considers true. Every table is a claim that a category of things exists; every foreign key is a claim that two categories are related; every constraint is a claim about what the business considers valid. Bad ER design does not just cause slow queries — it causes business logic bugs, data integrity violations, and migration nightmares. This skill exists because agents commonly produce schemas that "work" for the happy path but fail under real-world conditions: concurrent updates, schema evolution, multi-tenancy, and audit requirements. The goal is schemas that are correct first, performant second, and evolvable always.
+
+## 1. Entity Identification
+
+### What Makes a Good Entity
+
+| Criterion | Pass | Fail |
+|-----------|------|------|
+| **Has identity** | Two orders can be distinguished by ID | "OrderType" — just an enum value |
+| **Has multiple attributes** | Order has status, amount, date, customer | "Color" with just a name |
+| **Has a lifecycle** | Order transitions through states | A constant lookup value |
+| **Participates in relationships** | Order belongs to Customer, has LineItems | An isolated value with no connections |
+| **Business users name it** | "Customer," "Product," "Order" | "DataRecord," "Item," "Thing" |
+
+### Entity vs. Attribute vs. Relationship
+
+| If it has... | It is probably... |
+|-------------|-------------------|
+| Multiple attributes of its own | An entity |
+| Only a name/label | An attribute (or enum) |
+| Attributes that describe a connection | A relationship entity (reified relationship) |
+| Multiple instances per parent | A child entity (not a multi-valued attribute) |
+
+## 2. Primary Key Design
+
+> For philosophical identity questions (what makes two entities "the same"), see `ontology`. This section covers the database implementation of those decisions.
+
+| Strategy | When to use | Trade-offs |
+|----------|-------------|-----------|
+| **UUID (v4 or v7)** | Distributed systems, multi-tenancy, external exposure | 16 bytes, not sortable (v4), not human-readable |
+| **UUID v7** | Need sortable UUIDs for index performance | Timestamp-prefixed, best of both worlds |
+| **Serial/BIGSERIAL** | Single-database, internal only | Compact, sortable, but reveals sequence |
+| **Natural key** | Immutable business identifier (ISO codes, SKUs) | Only if truly immutable; rare in practice |
+| **Composite key** | Junction tables, external system references | Complex JOINs, ORM friction |
+
+Rules:
+- Default to UUID v7 for new tables in multi-tenant SaaS (sortable, no sequence leakage, distributed-safe).
+- Never expose serial IDs externally (information leakage: competitor can count your orders).
+- Natural keys are tempting but dangerous — "immutable" business identifiers change more often than you think.
+
+## 3. Relationship Patterns
+
+### Cardinality Implementation
+
+| Relationship | Implementation |
+|-------------|---------------|
+| **1:1** | FK with UNIQUE on child table, or merge into one table |
+| **1:N** | FK on the N-side (child) referencing parent PK |
+| **M:N** | Junction table with two FKs + composite UNIQUE |
+| **M:N with attributes** | Junction table promoted to entity (with its own PK and additional columns) |
+| **Self-referential** | FK referencing same table (e.g., `manager_id` → `employees.id`) |
+| **Polymorphic** | Avoid; use junction tables per type or single FK with type discriminator |
+
+### Junction Table Design
+
+```sql
+-- Simple M:N
+CREATE TABLE product_categories (
+  product_id    UUID REFERENCES products(id) ON DELETE CASCADE,
+  category_id   UUID REFERENCES categories(id) ON DELETE CASCADE,
+  PRIMARY KEY (product_id, category_id)
+);
+
+-- M:N with attributes (promoted to entity)
+CREATE TABLE order_line_items (
+  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  order_id      UUID NOT NULL REFERENCES orders(id) ON DELETE CASCADE,
+  product_id    UUID NOT NULL REFERENCES products(id),
+  quantity      INTEGER NOT NULL CHECK (quantity > 0),
+  unit_price_cents INTEGER NOT NULL CHECK (unit_price_cents >= 0),
+  created_at    TIMESTAMPTZ DEFAULT now()
+);
+```
+
+## 4. Normalization
+
+| Form | Rule | Violation example | Fix |
+|------|------|-------------------|-----|
+| **1NF** | Atomic values, no repeating groups | `tags: "red,blue,green"` | Separate table for tags |
+| **2NF** | No partial dependencies (all non-key attributes depend on entire PK) | Junction table with attributes depending on only one FK | Move to parent table or new entity |
+| **3NF** | No transitive dependencies (non-key attributes don't depend on other non-key attributes) | `order.customer_name` duplicating `customer.name` | Remove; join when needed |
+| **BCNF** | Every determinant is a candidate key | Rare in practice; usually 3NF suffices | Decompose table |
+
+Rules:
+- Normalize to 3NF by default for transactional tables.
+- Denormalize deliberately for read-heavy analytics with documented justification.
+- Never skip normalization analysis — even if you plan to denormalize, understanding the normal form reveals the true dependencies.
+
+## 5. Denormalization Patterns
+
+| Pattern | When | Risk |
+|---------|------|------|
+| **Materialized view** | Read-heavy aggregations, dashboards | Staleness, refresh overhead |
+| **Computed column** | Frequently derived values | Must be maintained on writes |
+| **Redundant column** | Avoid frequent JOINs for hot queries | Update anomalies |
+| **JSON column** | Flexible schema within structured data | Query complexity, no FK enforcement |
+| **Pre-aggregated table** | Time-series rollups, analytics | Dual-write consistency |
+
+Rules:
+- Every denormalization must document: what is denormalized, why, and how consistency is maintained.
+- Prefer materialized views (DB-maintained) over application-level redundancy (app-maintained).
+- JSON columns are not a substitute for proper entity design; use only for genuinely flexible/unstructured data.
+
+## 6. Inheritance Mapping
+
+| Strategy | When | Trade-offs |
+|----------|------|-----------|
+| **Single-table** (STI) | Few subtypes, similar attributes, simple queries | Nullable columns, wasted space |
+| **Class-table** | Many shared attributes, need FK to parent | JOIN overhead, complex inserts |
+| **Concrete-table** | Subtypes are queried independently, few shared operations | No polymorphic queries, attribute duplication |
+
+### Decision Matrix
+
+| Criterion | Single-table | Class-table | Concrete-table |
+|-----------|-------------|-------------|----------------|
+| Query simplicity | Best | Worst | Medium |
+| Storage efficiency | Worst | Best | Medium |
+| Polymorphic queries | Built-in | Requires JOIN | Requires UNION |
+| Subtype isolation | None | Partial | Full |
+| Schema evolution | Easy (add column) | Medium (alter multiple) | Hard (alter each) |
+
+Rules:
+- Default to single-table inheritance for <= 3 subtypes with mostly shared attributes.
+- Switch to class-table when subtypes diverge significantly (many subtype-specific columns).
+- Concrete-table only when subtypes are operationally independent and never queried together.
+
+## 7. Temporal Data Modeling
+
+| Pattern | Tracks | Implementation |
+|---------|--------|---------------|
+| **SCD Type 1** | Current value only (overwrite) | Simple UPDATE |
+| **SCD Type 2** | Full history with validity periods | `valid_from`, `valid_to`, `is_current` |
+| **SCD Type 3** | Previous + current value | `current_value`, `previous_value` columns |
+| **Bi-temporal** | Both business time and system time | `valid_from`, `valid_to`, `recorded_at`, `superseded_at` |
+
+Rules:
+- Financial data requires at minimum SCD Type 2 (full audit trail).
+- Use `valid_to IS NULL` or a boolean `is_current` flag for efficient current-value queries.
+- Bi-temporal modeling is necessary when you need to answer "what did we think was true on date X about date Y?"
+
+## 8. Constraint Specification
+
+| Constraint | Purpose | Example |
+|-----------|---------|---------|
+| `NOT NULL` | Attribute is mandatory | Every order has a customer |
+| `UNIQUE` | No duplicate values | Email addresses |
+| `CHECK` | Business rule enforcement | `quantity > 0`, `amount_cents >= 0` |
+| `FOREIGN KEY` | Referential integrity | Order references Customer |
+| `EXCLUDE` | No overlapping ranges | Booking date ranges |
+| `DEFAULT` | Sensible initial value | `created_at DEFAULT now()` |
+
+Rules:
+- Push validation to the database whenever possible. Application-level validation can be bypassed; DB constraints cannot.
+- Every financial amount column needs `CHECK (amount >= 0)` or explicit handling of negatives.
+- Prefer `ON DELETE CASCADE` for composition (line items); `ON DELETE RESTRICT` for association (customer has orders).
+
+## 9. Anti-Patterns
+
+| Anti-Pattern | Symptom | Fix |
+|-------------|---------|-----|
+| **EAV (Entity-Attribute-Value)** | Generic `key/value` table instead of proper columns | Design explicit entities; use JSON column for genuinely dynamic attributes |
+| **Polymorphic association** | One FK column + type discriminator pointing to multiple tables | Separate FK per related table, or junction table per relationship type |
+| **Mega-table** | 50+ columns, many nullable | Decompose into related entities by business concern |
+| **Over-normalization** | 15 JOINs for a simple query | Selectively denormalize with materialized views |
+| **God table** | One table serves orders, invoices, quotes, and returns | Separate by business entity; share via FK to common parent if needed |
+| **Missing constraints** | No CHECK, FK, or UNIQUE — all validation in app code | Add database-level constraints as the source of truth |
+| **Implicit deletion** | `is_deleted` boolean instead of proper lifecycle | Use soft delete with `deleted_at` timestamp, or archive tables |
+
+## Verification
+
+> **Scope note:** This checklist covers the implementation (ER) layer — primary keys, foreign keys, normalization, and index strategy. For relationship-level verification (named associations, semantic cardinality), use [`conceptual-modeling`]. For axiom-level verification (formal class definitions, property domains/ranges), use [`ontology`].
+
+After applying this skill, verify:
+- [ ] Primary keys are defined for every entity with an explicit strategy (UUID v7 preferred for new tables)
+- [ ] Foreign keys correctly reference parent PKs with explicit ON DELETE behavior (CASCADE for composition, RESTRICT for association)
+- [ ] Normalization level is documented (3NF for OLTP default; any denormalization is justified and documented)
+- [ ] Index strategy is documented — at minimum, covering PKs, FK columns, and query predicates for hot paths
+- [ ] Financial columns have CHECK constraints for valid ranges (`amount >= 0` or explicit negatives handling)
+- [ ] Temporal data has the appropriate SCD type for audit requirements
+- [ ] No EAV or polymorphic association patterns without explicit justification
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Analyzing business requirements into implementation-independent domain concepts | `conceptual-modeling` | Conceptual modeling captures the domain; ER modeling implements the storage |
+| Defining formal type hierarchies with reasoning and axioms | `ontology` | Ontology is the philosophical layer; ER modeling is the physical layer |
+| Mapping entities between different systems or representations | `relational-mapping` | Relational mapping connects systems; ER modeling designs one system's schema |
+| Running SQL migrations on Neon Postgres | `database-migration` | Migration handles the change process; ER modeling handles the target design |
+
+---
+
+*Version 1.0.0 — 2026-03-29. Initial creation.*

package/marketplace/skills/epistemic-grounding/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: epistemic-grounding
+description: "Use when authoring any artifact that makes claims — skill content, documentation, audit findings, architecture proposals, code review comments. Covers the discipline of grounding every claim to a verifiable source, distinguishing verified-by-evidence from inferred-from-context, using normative vocabulary precisely (RFC 2119 MUST/SHOULD/MAY), and structuring arguments so the warrant from data to claim is visible to a reader. Do NOT use for verification protocol mechanics in this repo (use the verification-protocol rule file), for output-completeness enforcement (use methodology), or for self-scoring on a 1-5 scale (use self-evaluation)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"foundations\",\"domain\":\"foundations/epistemics\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-15\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-15\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"epistemic grounding\\\\\\\",\\\\\\\"claim grounding\\\\\\\",\\\\\\\"source citation\\\\\\\",\\\\\\\"RFC 2119 modality\\\\\\\",\\\\\\\"Toulmin argument\\\\\\\",\\\\\\\"evidence-based assertion\\\\\\\",\\\\\\\"hallucination prevention\\\\\\\",\\\\\\\"normative vocabulary\\\\\\\",\\\\\\\"warrant\\\\\\\",\\\\\\\"epistemic hedge\\\\\\\"]\",\"triggers\":\"[\\\\\\\"ground this claim\\\\\\\",\\\\\\\"cite a source\\\\\\\",\\\\\\\"MUST vs SHOULD\\\\\\\",\\\\\\\"is this verified\\\\\\\",\\\\\\\"how do you know that\\\\\\\"]\",\"examples\":\"[\\\\\\\"before stating that this library supports X, confirm against the actual docs\\\\\\\",\\\\\\\"rewrite this finding so each assertion either cites a file or is marked as inference\\\\\\\",\\\\\\\"should this be a MUST or a SHOULD? what's the strength of the claim?\\\\\\\",\\\\\\\"the agent reported 'fix works' but no test was run — flag the gap in grounding\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"verify every step of an audit task with concrete evidence (use methodology)\\\\\\\",\\\\\\\"decide which lint rule to add for a specific kind of drift (use skill-infrastructure)\\\\\\\",\\\\\\\"evaluate a finished SKILL.md against the comprehension grader (use evaluation)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"methodology\\\\\\\",\\\\\\\"semantics\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"methodology\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"methodology enforces output-level completeness and step-level evidence receipts; epistemic-grounding is the upstream discipline that decides what counts as evidence in the first place.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"semantics\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"semantics owns the rules for naming and meaning-making; epistemic-grounding owns the rules for grounding a claim to a verifiable source.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"methodology\\\\\\\",\\\\\\\"evaluation\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Epistemic grounding is to claims what double-entry bookkeeping is to financial transactions — every assertion has a corresponding source on the other side of the ledger, and any entry without its pair is a red flag in the audit.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Epistemic grounding is the discipline of binding every assertion to a verifiable source, marking the modality (strength) of the claim, and making the warrant (the inference from source to claim) explicit. It is the practice that turns a generated statement into a defended statement.\\\\\\\",\\\\\\\"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/epistemic-grounding/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/epistemic-grounding/SKILL.md
+---
+
+# Epistemic Grounding
+
+## Coverage
+
+The discipline of grounding every claim to a verifiable source, marking the modality (RFC 2119 MUST/SHOULD/MAY) of the claim, and making the warrant from source to claim explicit. Covers the six-primitive Toulmin argument structure (claim/data/warrant/backing/qualifier/rebuttal), the RFC 2119 normative vocabulary, the distinction between verified/inferred/hallucinated, how to hedge honestly without softening, and the failure modes (cargo-cult citation, stale grounding, vibe-based assertion). Applies to any artifact that makes claims: SKILL.md content, code review comments, audit findings, documentation, architecture proposals, agent output.
+
+## Philosophy
+
+Confidence is not evidence. An LLM trained to be helpful produces fluent, confident text whether or not the underlying claim is true — RLHF rewards plausibility, not verification. The result is that ungrounded text is indistinguishable from grounded text by surface signals alone: tone, structure, and vocabulary look identical.
+
+The countermeasure is not to ask the model to "be more careful" (it can't see its own confidence). It is to require structural signals that make grounding state visible: every claim has a source-warrant-qualifier triple in the text, or it carries an explicit hedge ("not verified", "as of 2026-05-15", "inferred from context"). A reader scanning the text can then tell at a glance which claims are grounded and which are not.
+
+This discipline serves three downstream uses: (1) audit and review become tractable because the reviewer knows what to verify; (2) drift detection becomes possible because grounded claims expose their dependencies; (3) downstream agents reading the artifact can decide which claims to trust and which to re-verify.
+
+## The Six-Primitive Argument
+
+Every grounded claim has six primitives, derived from Toulmin's argument structure (1958). Most agent output surfaces only the Claim and silently elides the rest.
+
+| Primitive | What it answers | Example |
+|---|---|---|
+| **Claim** | What is being asserted? | "HTTP DELETE is idempotent." |
+| **Data** | What source supports the claim? | "RFC 9110 § 9.3.5" |
+| **Warrant** | What rule connects data to claim? | "RFC 9110 normatively defines HTTP method semantics; § 9.3.5 specifies DELETE's idempotency." |
+| **Backing** | What gives the warrant authority? | "IETF standards body; the RFC has been ratified and is the canonical HTTP/1.1 reference." |
+| **Qualifier** | How strong is the claim? | "MUST" (per RFC 2119) — DELETE is by-definition idempotent. |
+| **Rebuttal** | Under what conditions does the claim fail? | "Server-side state changes that cause subsequent DELETEs to return different status codes do not violate idempotency in the spec sense — idempotency is about the server's resource state, not the response code." |
+
+A grounded version of "HTTP DELETE is idempotent" might read in full: *"DELETE is idempotent (RFC 9110 § 9.3.5, MUST). Repeated calls produce the same resource state; response codes may differ (404 after the first 204), which does not violate spec-level idempotency."* That sentence has all six primitives. The ungrounded version — "DELETE is idempotent" — has only the claim.
+
+In a SKILL.md, you don't enumerate all six explicitly every sentence. You inline them via citation form, qualifier word, and parenthetical rebuttal. The discipline is to write each claim such that the six primitives can be *reconstructed* by a reader, not necessarily that they are all surface-visible.
+
+## RFC 2119 Modality
+
+The normative vocabulary from RFC 2119 gives Qualifiers a shared, machine-readable meaning. Use these words *only* in their RFC 2119 sense; in non-normative writing, use weaker words.
+
+| Word | Meaning |
+|---|---|
+| **MUST** / **REQUIRED** / **SHALL** | Absolute requirement. The claim is binding; violation breaks the contract. |
+| **MUST NOT** / **SHALL NOT** | Absolute prohibition. |
+| **SHOULD** / **RECOMMENDED** | Strong recommendation. Violation requires understanding and justifying the deviation. |
+| **SHOULD NOT** / **NOT RECOMMENDED** | Strong recommendation against. |
+| **MAY** / **OPTIONAL** | Truly optional. Either choice is conformant. |
+
+A skill that says "the handler MUST verify HMAC" makes a different commitment than "the handler should verify HMAC" (lowercase, weak). The capitalized RFC 2119 form has contract weight; the lowercase form is advisory English. Mixing them is a grounding failure.
+
+In SKILL.md authoring, use RFC 2119 vocabulary *only* when the claim is genuinely normative (a protocol requirement, a security invariant, a financial correctness rule). For preferences and patterns, use weaker prose: "prefer", "by default", "in this repo we use".
+
+## Verified vs Inferred vs Asserted
+
+Every claim falls into one of three states. Epistemic grounding requires labeling the state explicitly when it isn't obvious from context.
+
+| State | Definition | Required marker |
+|---|---|---|
+| **Verified** | The claim was confirmed by a tool call (Read, Grep, curl, test run) in the same writing session or has an attached evidence receipt. | Cite the verification ("ran `npm test`, all 47 passed") or attach the source path with a line range. |
+| **Inferred** | The claim is a reasonable conclusion from cited evidence, but the conclusion itself wasn't directly tested. | Mark with "inferred from", "follows from", or a hedge like "likely". |
+| **Asserted** | The claim is from the writer's prior knowledge with no in-session verification. | Mark with "as of <date>", "I haven't verified this", or "in my experience". This is the weakest state and should be rare in grounded writing. |
+
+The failure mode is silent state-drift: asserting something as if verified, or inferring something as if asserted. The discipline is to mark the state when it differs from what context implies.
+
+## Failure Modes
+
+| Failure | What it looks like | Why it fails |
+|---|---|---|
+| **Cargo-cult citation** | A reference is added at the end of a paragraph, but doesn't actually support the specific claims in that paragraph. | The warrant from source to claim is missing; the citation is decorative. |
+| **Stale grounding** | A claim cites a source that has since been moved, renamed, or rewritten. | The grounding was once valid but isn't anymore; the reader trusts it without knowing. |
+| **Vibe-based assertion** | A claim is stated with no marker, in a context where the reader will assume it's grounded. | Silent state-drift from asserted to verified. |
+| **Overstated modality** | "MUST" used for a preference; "MAY" used for a hard requirement. | RFC 2119 vocabulary loses its load-bearing meaning. |
+| **Pseudo-hedge** | "Probably", "in most cases", "generally" applied where the writer actually knows the answer. | Soft hedging looks like grounding but obscures the actual state of knowledge. |
+| **Citation laundering** | Citing a secondary source (a blog post citing an RFC) without going to the primary. | The chain of warrants is weak; the secondary source may have misread the primary. |
+| **Authority projection** | Citing a high-authority source for a claim it doesn't actually make. | The source's authority covers the writer's claim even though the source didn't say it. |
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Every claim that would surprise a domain expert has a source attached.
+- [ ] RFC 2119 vocabulary is used only in normative claims, not in advisory prose.
+- [ ] No paragraph has trailing-citation decoration where the citation doesn't tie to specific claims.
+- [ ] Claims that are inference (not from a cited source) are explicitly marked.
+- [ ] The strongest claims have the most explicit grounding; the weakest claims have hedges.
+- [ ] No "MUST" applies to a preference; no "MAY" applies to a requirement.
+- [ ] At least one Rebuttal is acknowledged for the central claim of the artifact.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Enforcing step-level evidence receipts and output completeness | `methodology` | methodology owns the execution discipline; this skill is the upstream grounding discipline that decides what counts as evidence in the first place |
+| Naming things precisely (variables, functions, files) | `semantics` | semantics owns naming precision; this skill owns claim grounding |
+| Drawing inferences from premises | `reasoning` | reasoning is the cognitive primitive; this skill is the marking discipline for distinguishing inference from observation |
+| Verifying that a specific implementation works | `evaluation` or repo-local verification protocol | evaluation owns grader frameworks; this skill is the structural discipline upstream of any verification |
+| Designing the rules of a skill audit | `skill-infrastructure` | skill-infrastructure owns lint and census tooling; this skill governs what counts as a grounded claim that lint might check |
+
+## Key Sources
+
+- Toulmin, S. (1958). *The Uses of Argument*. Cambridge University Press. The canonical six-primitive argument structure (claim/data/warrant/backing/qualifier/rebuttal).
+- Bradner, S. (1997). [RFC 2119: Key words for use in RFCs to Indicate Requirement Levels](https://datatracker.ietf.org/doc/html/rfc2119). IETF. The standardized MUST/SHOULD/MAY normative vocabulary.
+- Leiba, B. (2017). [RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words](https://datatracker.ietf.org/doc/html/rfc8174). IETF. Clarifies that only ALL-CAPS forms carry RFC 2119 weight.
+- Northeastern University (2025). "AI sycophancy: 58.19% rate across frontier models." The measurement that justifies structural countermeasures over behavioral ones.
+- Royal Society Open Science (2025). "LLM summarization bias: overgeneralization in 26-73% of cases." The measurement that justifies explicit source-to-claim warrant tracking.