@skill-graph/cli 0.5.6

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

@@ -0,0 +1,120 @@
+---
+name: snapshot-testing
+description: "Use when reasoning about snapshot testing as a tactical technique: the capture-and-compare-against-baseline pattern, the difference between data snapshots (serialized object trees), DOM snapshots (rendered HTML trees), and visual snapshots (pixel images), the approval-cycle discipline that determines whether the technique adds testing value or just maintenance burden, the failure modes (auto-update without review, snapshot churn on irrelevant changes, large snapshots that hide diffs), where snapshot testing fits (structural regression of complex outputs) and where it doesn't (behavioral specification of contracts), and the relationship to visual regression testing tools (Chromatic, Percy, Loki, Playwright screenshots). Do NOT use for behavioral assertions about output values (use example tests in testing-strategy), for universal property claims (use property-based-testing), for the construction of test doubles (use test-doubles-design), or for end-to-end user-journey testing (use e2e-test-design)."
+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\":\"[\\\\\\\"snapshot testing\\\\\\\",\\\\\\\"golden file\\\\\\\",\\\\\\\"characterization test\\\\\\\",\\\\\\\"approval testing\\\\\\\",\\\\\\\"visual regression\\\\\\\",\\\\\\\"Chromatic\\\\\\\",\\\\\\\"Percy\\\\\\\",\\\\\\\"Storybook\\\\\\\",\\\\\\\"Jest snapshot\\\\\\\",\\\\\\\"DOM snapshot\\\\\\\",\\\\\\\"image snapshot\\\\\\\",\\\\\\\"approval cycle\\\\\\\"]\",\"triggers\":\"[\\\\\\\"should this be a snapshot test\\\\\\\",\\\\\\\"the snapshot keeps changing\\\\\\\",\\\\\\\"is visual regression testing the same thing\\\\\\\",\\\\\\\"should we auto-update snapshots\\\\\\\",\\\\\\\"snapshot file is too big\\\\\\\"]\",\"examples\":\"[\\\\\\\"decide whether a rendered component is a candidate for a snapshot test or for behavioral tests\\\\\\\",\\\\\\\"diagnose a test suite where every PR updates snapshot files — likely snapshot churn from non-stable inputs\\\\\\\",\\\\\\\"explain why auto-updating snapshots without review removes the testing value\\\\\\\",\\\\\\\"design an approval cycle for a visual regression suite (Chromatic / Percy)\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"specify the exact return value of a calculation (use example tests under testing-strategy)\\\\\\\",\\\\\\\"verify a universal property like sort correctness (use property-based-testing)\\\\\\\",\\\\\\\"design end-to-end user journey tests (use e2e-test-design)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"property-based-testing\\\\\\\",\\\\\\\"test-driven-development\\\\\\\",\\\\\\\"code-review\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"testing-strategy owns the strategic question of what to test at which level; this skill owns one tactical technique (capture-and-compare) within that strategy.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"property-based-testing\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"property-based-testing asserts universal claims about output structure; snapshot testing captures a specific output and asserts equality to a baseline. The two complement: PBT for universal contracts, snapshots for complex structural outputs that are easier to capture than specify.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"test-driven-development\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"TDD prescribes writing the test before the code; snapshot testing requires the code to exist before the snapshot can be captured. Snapshot testing fits poorly with strict TDD on greenfield code and well with characterization of existing code.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"code-review\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"Snapshot diffs surface change evidence that code review must read and approve; the approval cycle of snapshot testing is operationally part of the review process the code-review discipline owns.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"code-review\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"A snapshot test is to a piece of output what a wedding photograph is to a memory of the day — the photograph does not say what the wedding *should* have looked like, only what it did look like; on the next anniversary, you compare the room to the photograph and notice 'the curtains are different' (intentional — they were replaced) or 'the picture is crooked' (unintentional — fix it). A photograph filed away without anyone ever looking at it again is not a record; it is paper. A snapshot file the team auto-accepts via `-u` is the same.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Snapshot testing is a tactical testing technique in which the output of a system under test is captured on a known-good run, stored as an artifact (the snapshot), and compared against fresh output on each subsequent test run. A mismatch is the test failure. The snapshot itself is the assertion — there is no hand-written claim about what the output should be; the claim is 'the output should equal what it was last time, until someone deliberately approves a new baseline.' The discipline is in the *approval cycle*: when the output legitimately changes, a human reviews the diff and accepts the new baseline; when the change is unexpected, the test failure surfaces the regression. A snapshot test without disciplined approval review is not a test; it is a record of whatever the output happened to be on the day the snapshot was last updated.\\\\\\\",\\\\\\\"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/snapshot-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/snapshot-testing/SKILL.md
+---
+
+# Snapshot Testing
+
+## Coverage
+
+The tactical testing technique in which the output of a system under test is captured on a known-good run, stored as an artifact, and compared against fresh output on each subsequent test run. Covers the five primitives (target output, snapshot artifact, comparison and diff, approval cycle, stability discipline), the taxonomy across output target (data / DOM / image / text), storage location (inline / file / centralized service), approval process (auto-update / manual edit / PR-integrated review), comparison strategy (exact / perceptual / structural / property-equality), and scope (unit / integration / full-page visual). Covers the Feathers characterization-test pattern as a legitimate use, and the auto-update-without-review anti-pattern as the technique's most common failure mode.
+
+## Philosophy
+
+A snapshot test is a photograph of the output. The photograph itself is not a specification — it doesn't say what the output should be, only what it was on the day of capture. The technique's value is in surfacing every subsequent change to a reviewer's eye, so that intentional changes are approved and unintentional changes are caught as regressions.
+
+The discipline is the approval cycle. When a snapshot test fails, the developer reads the diff, decides whether the change was intentional, and either updates the baseline (intentional) or fixes the production code (unintentional). A team that types `jest -u` reflexively in response to every failing snapshot has automated the maintenance and removed the verification.
+
+Snapshot testing fits where the output is structurally complex enough that hand-specifying every part is expensive, where small drift should be visible, and where the team will honor the approval cycle. It fits poorly where the output is simple (use precise assertions), unstable (the snapshot will churn), or where the team treats failures as nuisances to silence rather than signals to read.
+
+## Output Target Matrix
+
+| Target | Serialization | Diff format | Common tooling |
+|---|---|---|---|
+| Data structure | JSON or framework-specific | Line-by-line text diff | Jest `toMatchSnapshot`, Vitest snapshot |
+| DOM / HTML | Pretty-printed HTML or virtual-DOM tree | Line-by-line text diff | `@testing-library` + Jest, Enzyme legacy |
+| Image | PNG (or other lossless) | Perceptual diff with threshold | Chromatic, Percy, Argos, Loki, Playwright screenshots |
+| Text | Plain text | Line-by-line text diff | Approval test libraries; framework snapshot |
+| Generated code | Plain text | Line-by-line text diff | Same as text |
+
+The target's serialization stability is the technique's precondition. Outputs that include timestamps, random IDs, iteration-order-dependent collections, or environment-dependent values must be normalized before snapshot capture or the test will churn.
+
+## The Approval Cycle In Detail
+
+```
+Test fails (snapshot != fresh output)
+            │
+            ▼
+   Read the diff carefully
+            │
+            ▼
+  ┌─────────────┴─────────────┐
+  │                           │
+  Change was intended         Change was not intended
+  │                           │
+  ▼                           ▼
+  Update the snapshot         Fix the production code
+  (the new baseline is the    (the snapshot stays;
+   intended output)            the code is what changed
+                               unintentionally)
+```
+
+The discipline is the read. The diff must be small enough to read, the diff format must be legible, and the developer must read it. Tooling that bypasses the read (auto-update, mass-accept) is incompatible with the technique.
+
+## When Snapshot Testing Fits
+
+| Fits well | Fits poorly |
+|---|---|
+| Complex rendered DOM components | Simple return values |
+| Large JSON API responses | Single primitive outputs |
+| Generated SQL or code output | Random or nondeterministic outputs |
+| Visual regression of UI components | Outputs that change frequently for unrelated reasons |
+| Characterizing legacy code for refactoring | Greenfield code under strict TDD |
+| Full-page visual diff | Behavioral contracts that need explicit specification |
+| Detecting structural drift over time | Cases where every diff is expected and uninformative |
+
+## Stability Sources To Control
+
+| Source | Mitigation |
+|---|---|
+| Wall-clock timestamps | Inject a deterministic clock; freeze time in tests |
+| Random IDs (UUID, nanoid) | Inject a seeded ID generator in tests |
+| Iteration order of unordered collections | Sort before serialization |
+| Environment-dependent values (env vars, hostnames) | Fix or mock in test environment |
+| Browser/OS rendering differences (image snapshots) | Use a snapshot service that pins the environment; tolerance threshold for perceptual diff |
+| Pretty-printer changes across library versions | Pin the serializer version |
+| Locale-dependent formatting | Fix locale in tests |
+
+A snapshot test on output without these controls churns on noise and trains the team to ignore the failures.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Every snapshot test has a designated approval cycle. The team's response to a failed snapshot test is "read the diff," not "run `-u`."
+- [ ] Snapshot files are small enough that the diff between baseline and fresh output is readable by a human reviewer. Snapshots over a few hundred lines are split or replaced with per-property assertions.
+- [ ] The target output is *stable* — timestamps, IDs, ordering, and environment values are controlled. Snapshots that churn on noise are diagnosed as instability, not accepted as normal.
+- [ ] Snapshot tests are paired with example tests for behaviors that need specification. The suite is not snapshot-only.
+- [ ] Visual snapshots use perceptual diff with a tolerance threshold, not bit-for-bit equality. The threshold is tuned to ignore rendering noise while catching real changes.
+- [ ] PR review surfaces snapshot diffs; reviewers actually read them. (For visual snapshots, the snapshot service's review UI is the integration point.)
+- [ ] Characterization snapshots are recognized as safety nets for legacy refactoring, not as specifications. They are progressively replaced with example or property tests as the code is understood.
+- [ ] Snapshot files in source control are reviewed for size. Repository bloat from large snapshot files is a real cost that needs counterweight (technique fit, review discipline).
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Specifying one concrete behavior with explicit assertions | example tests (see `testing-strategy`) | examples specify with reasoning; snapshots capture without |
+| Asserting a universal property like sort correctness | `property-based-testing` | properties assert universal claims; snapshots assert "equals last time" |
+| Constructing test doubles | `test-doubles-design` | test-doubles owns the stand-in construction |
+| Designing end-to-end user journey tests | `e2e-test-design` | e2e owns user-level behavioral testing; snapshot-of-screenshot is one tool inside it |
+| Choosing test levels (unit/integration/e2e) | `testing-strategy` | strategy owns level choice; this skill is one tactical technique within |
+| Reviewing intended visual changes against a design system | dedicated design-review process | visual design intent assessment is its own discipline; visual snapshots surface unintended changes, not whether intended ones are good |
+
+## Key Sources
+
+- Feathers, M. (2004). *Working Effectively with Legacy Code*. Prentice Hall. Introduces "characterization tests" — capturing current behavior as a safety net for refactoring legacy code. The conceptual ancestor of snapshot testing.
+- Jest Team. ["Snapshot Testing — Jest Documentation"](https://jestjs.io/docs/snapshot-testing). The most-adopted JavaScript snapshot-testing implementation; canonical reference for inline snapshots, the `__snapshots__/` convention, and the `--updateSnapshot` flag and its discipline implications.
+- Llopis, N. ["Approval Tests"](https://approvaltests.com/). Cross-language framework explicitly focused on the approval cycle as the central discipline; useful as a contrast to auto-update-heavy tools.
+- Chromatic. ["Visual Testing Handbook"](https://www.chromatic.com/blog/visual-testing-handbook/). Practitioner-oriented guide to visual snapshot testing, perceptual diff, cross-browser concerns, and PR-integrated review UI.
+- Percy / BrowserStack. ["Visual Testing Documentation"](https://docs.percy.io/). Reference for the centralized-snapshot-service pattern in visual regression testing.
+- Storybook Team. ["Visual testing with Storybook"](https://storybook.js.org/docs/writing-tests/visual-testing). Reference for integrating visual snapshot testing with component development workflows.
+- Reactive Tests. ["Testing Library — Snapshot considerations"](https://testing-library.com/docs/queries/about/#priority) and broader [Testing Library documentation](https://testing-library.com/). Practitioner reference for DOM snapshot best practices in React/Vue test suites.
+- Spadini, D., Schvarcbacher, M., Oprescu, A.-M., Bruntink, M., & Bacchelli, A. (2020). ["Investigating Severity Thresholds for Test Smells"](https://dl.acm.org/doi/10.1145/3387940.3392177). Industrial study including snapshot-test smells; useful empirical signal on approval-cycle failure modes.

package/marketplace/skills/spec-driven-development/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: spec-driven-development
+description: "This skill provides Spec Driven Development (SDD) expertise for AI engineering: the Specify → Plan → Tasks → Implement lifecycle. Use when starting any non-trivial task, refactoring a core module, or when an agent loop has stalled due to ambiguous requirements. Do NOT use for one-line edits or README fixes."
+license: MIT
+compatibility: "Markdown, Git, agent-skill runtimes"
+allowed-tools: Read Grep Bash
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"workflow\",\"category\":\"engineering\",\"domain\":\"engineering/methodology\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-03-28\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-03-28\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"spec driven development\\\\\\\",\\\\\\\"SDD\\\\\\\",\\\\\\\"technical plan\\\\\\\",\\\\\\\"task decomposition\\\\\\\",\\\\\\\"specification\\\\\\\",\\\\\\\"architecture plan\\\\\\\",\\\\\\\"phase gates\\\\\\\",\\\\\\\"AI engineering methodology\\\\\\\"]\",\"triggers\":\"[\\\\\\\"sdd-skill\\\\\\\",\\\\\\\"planning-mode\\\\\\\",\\\\\\\"spec-driven-development\\\\\\\"]\",\"relations\":\"{\\\\\\\"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/spec-driven-development/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/spec-driven-development/SKILL.md
+---
+# Spec Driven Development (SDD)
+
+## Domain Context
+
+**What is this skill?** This skill provides Spec Driven Development (SDD) expertise for AI engineering: the Specify → Plan → Tasks → Implement lifecycle. Use when starting any non-trivial task, refactoring a core module, or when an agent loop has stalled due to ambiguous requirements. Do NOT use for one-line edits or README fixes.
+
+## Workflow
+
+Use the ordered phases, checklists, and guardrails in the sections below as the canonical workflow for this skill. When multiple subsections describe steps, follow them in the order presented.
+
+## Coverage
+
+The 5-phase SDD lifecycle (Specify, Plan, Decompose, Implement, Verify), spec.md and plan.md artifact authoring, atomic task decomposition (<10 min per task with topological ordering), verification gates (spec compliance, zero regressions, visual QA, doc updates), and the Build-Measure-Learn validation loop for post-implementation learning.
+
+## Philosophy
+
+AI agents default to implementation-first thinking: receive a prompt, start coding. This produces features that "work" but miss edge cases, violate constraints, and accumulate design debt. SDD exists because fixing a design flaw in Markdown costs 10x less than fixing it in a pull request. By forcing the Specify and Plan phases before any code is written, agents surface hidden dependencies, breaking changes, and security constraints while they are cheap to address. Observed failure: agents that skip specs produce code that passes tests but fails real-world scenarios the spec would have caught.
+
+> Spec Driven Development is the methodology of separating **"What"** (Specification) from **"How"** (Implementation). In the age of AI agents, SDD replaces "vibe coding" (iterative prompting without a plan) with systematic engineering.
+
+## 1. The SDD Lifecycle
+
+Every non-trivial task follows these five phases:
+
+| Phase | Agent Role | Output Artifact | Exit Criteria |
+|-------|------------|-----------------|---------------|
+| **1. Specify** | Researcher | `spec.md` | Human approval of requirements |
+| **2. Plan** | Architect | `plan.md` | Human approval of architecture |
+| **3. Decompose**| Project Manager | Linear Tasks | Tasks are atomic (<10 mins) |
+| **4. Implement**| Solver | Code + Tests | Tests pass, linting clear |
+| **5. Verify** | Validator | RESULT report | Spec compliance confirmed |
+
+**Rule**: Never start coding until the **Plan** phase is approved. Fixing a design flaw in Markdown is 10x cheaper than in a Pull Request.
+
+## 2. The Specification (`spec.md`)
+
+The `spec.md` defines the intent, constraints, and success criteria.
+
+- **Requirements**: User stories and "Must-Haves"
+- **Constraints**: Architecture, security, and PII rules (GDPR)
+- **Success Criteria**: Observable behaviors that prove the task is "Done"
+- **Edge Cases**: Zero states, error states, and high-volume data handling
+
+> **Anti-pattern**: Describing implementation details (e.g., "Use a `for` loop") in the spec. The spec is for "What", not "How".
+
+## 3. The Technical Plan (`plan.md`)
+
+The `plan.md` defines the implementation strategy and architecture.
+
+- **Architecture**: Affected modules, new components, and DB schema changes
+- **Data Flow**: How data moves from input to storage to output
+- **API Contracts**: Request/Response shapes and status codes
+- **Testing Strategy**: Unit, integration, and E2E coverage targets
+
+**Rule**: The plan must identify **hidden dependencies** and **breaking changes** before the first line of code is written.
+
+## 4. Task Decomposition
+
+Break the plan into atomic, testable tasks.
+
+- **Atomic**: One behavioral change per task
+- **Time-bound**: Each task should take an agent <10 minutes to implement
+- **Verifiable**: Each task must have a verification step (e.g., run a specific test)
+- **Topological Order**: Respect dependencies (Task B depends on Task A)
+
+> **Source**: `skills/task-lifecycle/SKILL.md` task decomposition rules.
+
+## 5. Verification Gates
+
+Verification is the only path to finality.
+
+- **SDD spec-compliance**: Every "Must-Have" in the spec is demonstrably true
+- **Zero-regressions**: Existing tests still pass
+- **Visual-QA**: UI changes match design-tokens and `composition-theory`
+- **Doc-update**: AGENTS.md, CONTEXT.md, and relevant domain docs updated
+
+## 6. Validate (Build-Measure-Learn)
+
+After implementation, validate that the change actually solves the problem. This phase comes from Eric Ries's Lean Startup methodology.
+
+### The BML Loop
+1. **Build** — Minimum viable implementation (already done in Phase 4)
+2. **Measure** — Collect data on whether the change achieved its goal
+   - Does the DORA rework rate stay stable or improve?
+   - Does user activation improve (if user-facing)?
+   - Does the target metric move in the right direction?
+3. **Learn** — Draw conclusions and decide next steps
+   - **Persevere** — The hypothesis was correct, continue investing
+   - **Pivot** — The hypothesis was wrong, change approach
+   - **Stop** — The problem isn't worth solving at this time
+
+### Validation Checklist
+- [ ] Success metric defined before implementation (from the spec)
+- [ ] Measurement mechanism in place (analytics, telemetry, user feedback)
+- [ ] Data collected for at least one cycle
+- [ ] Decision documented (persevere/pivot/stop) in Linear or decision ledger
+
+### When to Skip Validation
+- Pure infrastructure/tooling changes (validate via tests instead)
+- Bug fixes (validate via regression test)
+- Cosmetic changes under 10 lines
+
+> Source: Eric Ries "The Lean Startup" (2011)
+
+---
+
+## 7. Verification Checklist
+
+```text
+SDD CHECK
+=========
+[ ] spec.md approved by human (or documented rationale)
+[ ] plan.md approved by human (or documented rationale)
+[ ] Tasks are atomic (<10 min execution)
+[ ] Dependencies are explicitly ordered
+[ ] No code written until Plan phase is complete
+[ ] Every task has an associated test case
+[ ] Final verification confirms ALL spec success criteria met
+```
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| One-line edits, README fixes, or trivial changes | `effort` | Effort calibration determines when fast-track is appropriate |
+| Breaking a plan into atomic tasks with dependencies | `task` | Task skill owns decomposition mechanics and topological ordering |
+| Reviewing code quality after implementation | `code-review` | Code review owns post-implementation quality assessment |
+| Designing the UI layout and visual contracts | `design-execution` | Design execution owns the visual implementation doctrine |
+
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Changes follow the patterns documented above
+- [ ] No regressions in affected functionality

package/marketplace/skills/state-machine-modeling/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: state-machine-modeling
+description: "Use when modeling lifecycle states, transitions, guards, events, side effects, invalid states, retries, and state invariants for workflows or domain objects. Do NOT use for broad event discovery (use `event-storming`), database schema design (use `data-modeling`), or observability instrumentation after the lifecycle already exists (use `observability-modeling`)."
+license: MIT
+compatibility: "Portable state-machine discipline for product workflows, domain lifecycles, retries, background jobs, and UI flow control."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"modeling/state-machines\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-11\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-11\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"state machine\\\\\\\",\\\\\\\"state modeling\\\\\\\",\\\\\\\"lifecycle states\\\\\\\",\\\\\\\"transitions\\\\\\\",\\\\\\\"guards\\\\\\\",\\\\\\\"finite state machine\\\\\\\",\\\\\\\"invalid states\\\\\\\",\\\\\\\"status field\\\\\\\",\\\\\\\"workflow invariants\\\\\\\"]\",\"examples\":\"[\\\\\\\"model the order fulfillment status lifecycle so invalid transitions are impossible\\\\\\\",\\\\\\\"this status field keeps growing flags - should it become a state machine?\\\\\\\",\\\\\\\"define guards and side effects for onboarding steps\\\\\\\",\\\\\\\"find impossible states in this workflow before we implement it\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"discover the domain events and policies for the whole business process\\\\\\\",\\\\\\\"create database tables and constraints for this lifecycle\\\\\\\",\\\\\\\"instrument metrics and traces for an existing workflow\\\\\\\",\\\\\\\"debug why this job got stuck yesterday\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"event-storming\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"event-storming discovers domain behavior broadly; state-machine-modeling formalizes a specific lifecycle\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"data-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"data-modeling persists state; state-machine-modeling defines legal state behavior\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"observability-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"observability-modeling instruments a lifecycle; state-machine-modeling defines the lifecycle itself\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"debugging\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"debugging investigates an observed stuck state; state-machine-modeling prevents invalid states by design\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"event-storming\\\\\\\",\\\\\\\"system-interface-contracts\\\\\\\",\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"api-design\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"system-interface-contracts\\\\\\\"]}\",\"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/state-machine-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/state-machine-modeling/SKILL.md
+---
+
+# State Machine Modeling
+
+## Coverage
+
+Define legal lifecycle behavior for a domain object, UI flow, job, integration, or process. Covers states, transitions, events, guards, side effects, terminal states, retries, timeouts, compensation, invalid states, and transition verification.
+
+## Philosophy
+
+State modeling prevents boolean sprawl. When a workflow has several flags that can combine into impossible conditions, the model is already a state machine - just an implicit and unsafe one.
+
+Make illegal states unrepresentable where possible. Where that is not possible, make illegal transitions impossible and detectable.
+
+## Method
+
+1. Name the entity whose state is being modeled.
+2. List observable states as nouns or adjectives, not events.
+3. List events or commands that trigger transitions.
+4. Add guards: conditions required before a transition is legal.
+5. Add side effects separately from state changes.
+6. Mark terminal, retryable, and compensating states.
+7. Define invalid transitions and expected error behavior.
+8. Create transition-table tests before implementation.
+
+## Verification
+
+- [ ] States are mutually exclusive unless explicitly modeled as parallel regions
+- [ ] Every transition has a trigger
+- [ ] Guards are explicit where transitions depend on conditions
+- [ ] Side effects are not confused with state changes
+- [ ] Terminal and retry states are named
+- [ ] Invalid transitions have deterministic behavior
+- [ ] Tests cover allowed and forbidden transitions
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `event-storming` | You need to discover the broader domain flow, commands, policies, and aggregates. |
+| `data-modeling` | You need persistence schema or query shape for state data. |
+| `observability-modeling` | The lifecycle is settled and you need metrics, logs, traces, or alerts. |
+| `debugging` | A stateful system has already failed and needs root-cause analysis. |
+

package/marketplace/skills/state-management/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: state-management
+description: "Use when deciding where state lives, how it propagates, and how it composes: local component state vs lifted/shared state vs application state, server state vs client state, URL as state, persistent state, derived state, and the cross-cutting decision of who owns which piece. Covers state colocation, lifting up, derivation vs duplication, single source of truth, optimistic updates, server-state cache invalidation (React Query/SWR model), URL state for deep-linking, and anti-patterns like prop-drilling, state sprawl, and global-state-by-default. Do NOT use for specific state library choice (Redux vs Zustand — tactical), data fetching mechanics (use api-design or rendering-models), client/server boundary (use client-server-boundary), distributed system state (use replication-patterns), or finite state machines (use state-machine-modeling)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/frontend\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"state management\\\\\\\",\\\\\\\"state colocation\\\\\\\",\\\\\\\"lifting state\\\\\\\",\\\\\\\"state derivation\\\\\\\",\\\\\\\"single source of truth\\\\\\\",\\\\\\\"server state\\\\\\\",\\\\\\\"client state\\\\\\\",\\\\\\\"URL state\\\\\\\",\\\\\\\"persistent state\\\\\\\",\\\\\\\"ephemeral state\\\\\\\",\\\\\\\"global state\\\\\\\",\\\\\\\"prop drilling\\\\\\\",\\\\\\\"state sprawl\\\\\\\",\\\\\\\"optimistic update\\\\\\\",\\\\\\\"cache invalidation\\\\\\\",\\\\\\\"state ownership\\\\\\\",\\\\\\\"list state filtering sorting pagination\\\\\\\",\\\\\\\"state across routes\\\\\\\"]\",\"triggers\":\"[\\\\\\\"where should this state live\\\\\\\",\\\\\\\"should this be in component state or global\\\\\\\",\\\\\\\"I have state across multiple routes\\\\\\\",\\\\\\\"this prop is drilled through 5 components\\\\\\\",\\\\\\\"is this server state or client state\\\\\\\",\\\\\\\"should this be in the URL\\\\\\\"]\",\"examples\":\"[\\\\\\\"decide where the filter/sort/page state for a data table should live\\\\\\\",\\\\\\\"decide whether a piece of state should be in the URL, component state, or persistent storage\\\\\\\",\\\\\\\"diagnose whether a piece of duplicated state is a real performance need or accidental sprawl\\\\\\\",\\\\\\\"structure state for a form that spans multiple steps and survives navigation\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"implement a specific Redux reducer (tactical, library-specific)\\\\\\\",\\\\\\\"design the JSON shape of an API response (use api-design)\\\\\\\",\\\\\\\"model the state transitions of a multi-step workflow (use state-machine-modeling)\\\\\\\",\\\\\\\"configure HTTP cache headers on the server (use rendering-models or http-semantics)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"rendering-models\\\\\\\",\\\\\\\"client-server-boundary\\\\\\\",\\\\\\\"frontend-architecture\\\\\\\",\\\\\\\"api-design\\\\\\\",\\\\\\\"state-machine-modeling\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"client-server-boundary\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"client-server-boundary owns the line between code-that-runs-where (server components, client components, the serialization boundary); this skill owns the orthogonal question of which side owns which piece of state. They compose: the boundary skill says what code runs where; this skill says what state lives where.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"state-machine-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"state-machine-modeling owns finite-state representation of workflows (states, transitions, guards); this skill owns the decision of where state of any kind lives. The two compose when a workflow has a finite state space whose value still has to live somewhere — the machine names the values, this skill names the location.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"api-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"api-design owns the external request/response shape; this skill owns where the response data lives once it arrives, and how it's invalidated. Server state cache management (React Query / SWR doctrine) is in scope of this skill; the API surface itself is not.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"rendering-models\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"rendering-models owns the question of when content is generated (SSR, RSC, CSR, ISR); this skill owns the question of where data backing that content lives. The two intersect in 'server state' — data fetched on the server that the client needs.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"rendering-models\\\\\\\",\\\\\\\"api-design\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"State management is to a frontend application what addressing is to a postal system — you do not ask 'should this letter exist?', you ask 'where does it live?', and the right destination depends entirely on the letter's kind: a registered package (server data with provable delivery), a postcard (URL state, public on the back), a private letter (client UI state, inside an envelope), a deed (persistent state, kept in the safe). One mailbox for everything produces predictable failures.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"State management is the architectural discipline of deciding, for each distinct piece of data that an application reads or writes, where that data lives, who owns it, how it propagates to the components that need it, and how it stays consistent across changes. The discipline is upstream of any specific state library: it asks 'should this be local, lifted, global, server-cached, URL-encoded, or persisted' before asking 'which library do I use to hold it.' State is not a single thing; it is a category with at least four distinct kinds (server state, client UI state, URL state, persistent state), each with different lifetimes, invalidation rules, and consistency requirements. The discipline is the recognition that treating all state the same — putting all of it in one global store, or scattering it across every component — produces the recurring frontend problems of prop drilling, stale data, broken back-buttons, and tests that pass while users are confused.\\\\\\\",\\\\\\\"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/state-management/SKILL.md\",\"skill_graph_export_description\":\"shortened for Agent Skills 1024-character description limit; canonical source keeps the full routing contract\",\"skill_graph_canonical_description_length\":\"1122\"}"
+  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/state-management/SKILL.md
+---
+
+# State Management
+
+## Coverage
+
+The architectural discipline of deciding, for each distinct piece of data an application reads or writes, where it lives, who owns it, how it propagates, and how it stays consistent. Covers the four kinds of state (server, client UI, URL, persistent), the colocation default and the lifting move, the single-source-of-truth principle, the React Query / SWR doctrine for server state, the URL as a state container, the architectural anti-patterns of premature globalization and state sprawl, optimistic-update trade-offs, and the framing of state ownership as a design contract distinct from state-library selection.
+
+## Philosophy
+
+State management is a series of location and ownership decisions, each of which has a correct default. The defaults are: colocate locally; lift only when needed; put server state in a server-state library; put URL-worthy state in the URL; put session-survival state in persistent storage; never have two sources of truth for one value. Most recurring frontend bugs (broken back-button, stale data, prop drilling, "why is this re-rendering," changes that don't reflect everywhere) are violations of these defaults. The discipline is not the library; it is the application of the defaults.
+
+The discipline matters because state is not one thing — server state, client UI state, URL state, and persistent state have different lifetimes, invalidation rules, and consistency requirements. Treating them as one category (one store, one set of patterns) produces a codebase that gets all four kinds of state slightly wrong simultaneously. Treating them as four categories produces a codebase where each kind is handled by the tool best suited to it.
+
+For agents writing or reviewing frontend code, the discipline is the framework that lets the agent reason locally — pick up a piece of state, classify it (server / client / URL / persistent), check its current location against the right location for its kind, and make targeted fixes. Without the framework, the agent pattern-matches against whatever the codebase already does, replicating existing choices without questioning whether they were correct.
+
+## The Four Kinds Of State
+
+| Kind | Owned by | Lifetime | Invalidation rule | Common tools |
+|---|---|---|---|---|
+| **Server state** | A backend | Session, with revalidation | Time-based (stale-while-revalidate); event-based (mutation, focus, reconnect); manual | React Query, SWR, RTK Query, Apollo, Server Components |
+| **Client UI state** | A component or hook in the active session | Ephemeral within a render lifecycle | Recreated on unmount | useState, useReducer, Context, Zustand, Jotai |
+| **URL state** | The URL itself; framework router | Until URL changes | URL navigation | useSearchParams, route params, nuqs |
+| **Persistent state** | The browser's local storage | Until cleared | Manual via app code | localStorage, IndexedDB, cookies |
+
+Each piece of state in an application falls into one of these. Misclassifying produces predictable bugs — server data in a general-purpose store loses automatic revalidation; URL-worthy state in component state breaks the back-button; persistent state in component state loses on refresh.
+
+## The Colocation Rule (Kent C. Dodds)
+
+> **"State should live as close as possible to where it's used."** — colocation, deliberate lifting, escalation only by need.
+
+The decision procedure:
+
+1. **Start local.** Put new state in the component that needs it. Use `useState` or `useReducer`.
+2. **Two consumers? Lift.** When a second component needs to read or write the state, lift to the nearest common ancestor and pass by props. Track the prop's path; if it goes through ≥4 intermediate components, consider Context or composition.
+3. **Tree-scoped? Context.** When the state is genuinely shared by a sub-tree (theme, viewer, auth) and the value changes rarely, use Context. Use `useContextSelector` or pattern-match to slice if many consumers depend on different parts of a large value.
+4. **Application-wide with frequent fine-grained updates? Store.** When you have many components depending on many slices of a value that changes often, a state library (Zustand, Jotai, Redux Toolkit) provides selector-based subscriptions that minimize re-renders. This is the rare case, not the default.
+5. **Server data? Server-state library.** Always. Don't put server data in a general-purpose store.
+6. **URL-worthy? URL state.** When the state should survive refresh, be shareable, respond to back-button.
+
+Premature jumps (skipping step 2 to land at step 4, or starting at step 4 by default) cause state sprawl. The cost of climbing the ladder later (refactoring local to lifted) is less than the cost of being too high up to start.
+
+## The Server-State Distinction
+
+Server state has four properties that no general-purpose store handles by default:
+
+| Property | What it requires | Why a server-state library wins |
+|---|---|---|
+| **Remote canonical source** | The client cache may diverge from the server | Built-in stale-while-revalidate, refetch on focus/reconnect |
+| **Deduplication** | Two components asking for the same data should fetch once | Query-key cache prevents duplicate fetches |
+| **Staleness** | Old data should be replaced | Time-based and event-based invalidation |
+| **Mutation-triggered invalidation** | Updating data should refresh related queries | Mutate-then-invalidate pattern by query key |
+
+The recurring failure: using Redux/Zustand for everything, then manually building "refetch on focus" middleware, manual deduplication, manual cache expiry, and manual mutation-invalidation rules. Each one of those is correct in concept; together they reimplement React Query, badly. The disciplined answer is to use a server-state library for server data and keep the general-purpose store (if any) for genuinely client UI state.
+
+## URL State Decision Rule
+
+> **"Should two people opening this URL see the same view?"**
+
+If yes, the state belongs in the URL. If no, it doesn't.
+
+| State | URL-worthy? | Why |
+|---|---|---|
+| Current filter, sort, page | Yes | Sharing a link reproduces the view; back-button works |
+| Selected tab in a multi-tab panel | Often yes | Bookmark-able sub-view |
+| Open/closed of a sidebar | Usually no | Personal preference, not the shared view |
+| Modal open/closed | Sometimes | If it's a deep-linkable modal (sharable URL), yes; if it's transient confirmation, no |
+| Form values mid-edit | No | Ephemeral; shouldn't survive refresh from a stranger's link |
+| Pagination cursor | Yes | Restores state on refresh; shareable position |
+| Search query | Yes | Canonical "what is this user looking for" |
+| Currently-hovered element | No | Ephemeral; not part of the shareable view |
+
+## Anti-Patterns And Their Fixes
+
+| Anti-pattern | Symptom | Fix |
+|---|---|---|
+| **Premature globalization** | Every new state goes into the global store; the store grows; nobody knows what's in it | Start local. Only lift on observed need. Audit the store for entries that haven't been read in N months. |
+| **Server data in a general-purpose store** | Custom middleware for refetch, dedup, invalidation; bugs in each | Migrate server data to React Query/SWR/RTK Query. Keep the general store for UI state only. |
+| **URL-worthy state in component state** | Back-button doesn't work; refresh loses filters; can't share a link | Move to `useSearchParams` or equivalent. Adopt nuqs for type-safe URL state. |
+| **Prop drilling through 7 layers** | Tedious to maintain; refactors break | Context for tree-shared data; or composition (children-as-prop) to avoid intermediate awareness. |
+| **Duplicated state (same value, two locations)** | Updates in one place don't reflect in the other | Identify the canonical owner; derive in the other location or sync explicitly. |
+| **Stored derived state without need** | Caches go stale; bugs from "I updated X but Y still shows old" | Compute derived state at read time. Use `useMemo` only with measured perf evidence. |
+| **Optimistic updates for high-failure mutations** | "Did that work? Oh no, it didn't" UX | Use pessimistic (loading then success/error) for low-confidence mutations; optimistic for high-confidence only. |
+| **localStorage for everything user-prefs** | Server doesn't know on first render; no cross-device sync | Server-side store for prefs that affect SSR; URL state for session-scoped prefs; localStorage only when local-only is correct. |
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Every distinct piece of state in scope has been classified into one of the four kinds (server / client UI / URL / persistent).
+- [ ] Server data is held by a server-state library (React Query, SWR, RTK Query, Apollo, Server Components), not a general-purpose store.
+- [ ] State that should survive refresh, be shareable, or respond to back-button is in the URL.
+- [ ] No piece of state is duplicated (same value held in two independent locations) without an explicit synchronization mechanism and a recorded reason.
+- [ ] Local state stays local; lifts have a documented justification.
+- [ ] Context use is limited to genuinely tree-scoped data; large frequently-changing values that go through Context have been migrated to a store with selector-based subscriptions.
+- [ ] Derived state is computed at read time; stored derived values have measured performance evidence.
+- [ ] Optimistic updates are limited to high-confidence mutations; rollback paths exist where they are used.
+- [ ] Persistent state choices match what the data actually needs (localStorage / IndexedDB / cookies / server-stored prefs).
+- [ ] The state model is documented enough that a new contributor can answer "where does X live" in under a minute.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Choosing between Redux, Zustand, Jotai, Recoil, MobX, etc. | Library docs + framework conventions | Library choice is a tactical decision below this skill |
+| Designing the JSON shape of an API endpoint | `api-design` | api-design owns the external request/response surface; this skill owns where the response lives once it arrives |
+| Modeling the finite-state transitions of a workflow | `state-machine-modeling` | state-machine-modeling owns the workflow representation; this skill owns the location decision |
+| Encoding/decoding URL search params, route params, hash | `url-state-management` | url-state-management owns the encoding patterns; this skill owns the upstream "should it be in the URL" decision |
+| Building distributed state across services | `replication-patterns` | replication-patterns owns multi-replica consistency; this skill applies to single-client state |
+| Deciding what runs on server vs client | `client-server-boundary` | client-server-boundary owns the code-location boundary; this skill owns the state-location decision orthogonal to it |
+| Building the cache infrastructure of a server-state library | the library itself (React Query docs, etc.) | The library is the implementation of what this skill recommends; don't reimplement |
+| Concurrency control across multiple users editing the same record | (no direct skill — out of scope) | Conflict resolution mechanisms (versioning, OT, CRDT) are a separate concern |
+
+## Key Sources
+
+- Dodds, K. C. (2019). ["Application State Management with React"](https://kentcdodds.com/blog/application-state-management-with-react) and ["State Colocation will make your React app faster"](https://kentcdodds.com/blog/state-colocation-will-make-your-react-app-faster). Foundational essays on the colocation rule and the lift-when-needed discipline; widely cited as the modern doctrine successor to Redux-by-default.
+- TanStack. [React Query overview and motivation](https://tanstack.com/query/latest/docs/framework/react/overview). The canonical articulation of the server-state distinction: "React Query is often described as the missing data-fetching library for React, but in more technical terms, it makes fetching, caching, synchronizing and updating server state in your React applications a breeze."
+- Vercel. [SWR docs](https://swr.vercel.app/). The first widely-adopted server-state library to make stale-while-revalidate the default mental model in React.
+- Abramov, D. (2019). ["You Might Not Need Redux"](https://medium.com/@dan_abramov/you-might-not-need-redux-be46360cf367) and follow-ups. Redux's author articulating that Redux is not always the right answer; foundational for the modern "store-by-need, not by-default" doctrine.
+- React Team. [Sharing State Between Components](https://react.dev/learn/sharing-state-between-components) and [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure). The official React docs' framing of lifting state up, single source of truth, and avoiding state duplication.
+- Karlton, P. (attributed). "There are only two hard things in Computer Science: cache invalidation and naming things." The canonical statement of why server-state caching is not trivial — its difficulty is one of the two named hardest problems in the field.
+- Marquardt, J. (2024). ["URL as the state of your app"](https://www.epicreact.dev/url-state). Modern articulation of the URL-as-state-container principle in the App Router era.
+- Pelle, M. (2024). [nuqs documentation](https://nuqs.47ng.com/). Type-safe URL state library; reference implementation of the URL-as-state pattern with serialization, parsing, and React integration.
+- Fowler, M. (2003). *Patterns of Enterprise Application Architecture*. Addison-Wesley. The classic treatment of the Service Layer / Data Mapper / Identity Map / Unit of Work patterns; the Identity Map pattern is the original articulation of "deduplicate fetches by entity key" that server-state libraries operationalize.