devstack 0.1.0

package/vendor/skills/skills/tanstack-query-best-practices/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: tanstack-query-best-practices
+description: TanStack Query (React Query) best practices for data fetching, caching, mutations, and server state management. Activate when building data-driven React applications with server state.
+---
+
+# TanStack Query Best Practices
+
+Comprehensive guidelines for implementing TanStack Query (React Query) patterns in React applications. These rules optimize data fetching, caching, mutations, and server state synchronization.
+
+## When to Apply
+
+- Creating new data fetching logic
+- Setting up query configurations
+- Implementing mutations and optimistic updates
+- Configuring caching strategies
+- Integrating with SSR/SSG
+- Refactoring existing data fetching code
+
+## Rule Categories by Priority
+
+| Priority | Category         | Rules   | Impact                                       |
+| -------- | ---------------- | ------- | -------------------------------------------- |
+| CRITICAL | Query Keys       | 5 rules | Prevents cache bugs and data inconsistencies |
+| CRITICAL | Caching          | 5 rules | Optimizes performance and data freshness     |
+| HIGH     | Mutations        | 6 rules | Ensures data integrity and UI consistency    |
+| HIGH     | Error Handling   | 3 rules | Prevents poor user experiences               |
+| MEDIUM   | Prefetching      | 4 rules | Improves perceived performance               |
+| MEDIUM   | Parallel Queries | 2 rules | Enables dynamic parallel fetching            |
+| MEDIUM   | Infinite Queries | 3 rules | Prevents pagination bugs                     |
+| MEDIUM   | SSR Integration  | 4 rules | Enables proper hydration                     |
+| LOW      | Performance      | 4 rules | Reduces unnecessary re-renders               |
+| LOW      | Offline Support  | 2 rules | Enables offline-first patterns               |
+
+## Quick Reference
+
+### Query Keys (Prefix: `qk-`)
+
+- `qk-array-structure` — Always use arrays for query keys
+- `qk-include-dependencies` — Include all variables the query depends on
+- `qk-hierarchical-organization` — Organize keys hierarchically (entity → id → filters)
+- `qk-factory-pattern` — Use query key factories for complex applications
+- `qk-serializable` — Ensure all key parts are JSON-serializable
+
+### Caching (Prefix: `cache-`)
+
+- `cache-stale-time` — Set appropriate staleTime based on data volatility
+- `cache-gc-time` — Configure gcTime for inactive query retention
+- `cache-defaults` — Set sensible defaults at QueryClient level
+- `cache-invalidation` — Use targeted invalidation over broad patterns
+- `cache-placeholder-vs-initial` — Understand placeholder vs initial data differences
+
+### Mutations (Prefix: `mut-`)
+
+- `mut-invalidate-queries` — Always invalidate related queries after mutations
+- `mut-optimistic-updates` — Implement optimistic updates for responsive UI
+- `mut-rollback-context` — Provide rollback context from onMutate
+- `mut-error-handling` — Handle mutation errors gracefully
+- `mut-loading-states` — Use isPending for mutation loading states
+- `mut-mutation-state` — Use useMutationState for cross-component tracking
+
+### Error Handling (Prefix: `err-`)
+
+- `err-error-boundaries` — Use error boundaries with useQueryErrorResetBoundary
+- `err-retry-config` — Configure retry logic appropriately
+- `err-fallback-data` — Provide fallback data when appropriate
+
+### Prefetching (Prefix: `pf-`)
+
+- `pf-intent-prefetch` — Prefetch on user intent (hover, focus)
+- `pf-route-prefetch` — Prefetch data during route transitions
+- `pf-stale-time-config` — Set staleTime when prefetching
+- `pf-ensure-query-data` — Use ensureQueryData for conditional prefetching
+
+### Infinite Queries (Prefix: `inf-`)
+
+- `inf-page-params` — Always provide getNextPageParam
+- `inf-loading-guards` — Check isFetchingNextPage before fetching more
+- `inf-max-pages` — Consider maxPages for large datasets
+
+### SSR Integration (Prefix: `ssr-`)
+
+- `ssr-dehydration` — Use dehydrate/hydrate pattern for SSR
+- `ssr-client-per-request` — Create QueryClient per request
+- `ssr-stale-time-server` — Set higher staleTime on server
+- `ssr-hydration-boundary` — Wrap with HydrationBoundary
+
+### Parallel Queries (Prefix: `parallel-`)
+
+- `parallel-use-queries` — Use useQueries for dynamic parallel queries
+- `query-cancellation` — Implement query cancellation properly
+
+### Performance (Prefix: `perf-`)
+
+- `perf-select-transform` — Use select to transform/filter data
+- `perf-structural-sharing` — Leverage structural sharing
+- `perf-notify-change-props` — Limit re-renders with notifyOnChangeProps
+- `perf-placeholder-data` — Use placeholderData for instant UI
+
+### Offline Support (Prefix: `offline-`)
+
+- `network-mode` — Configure network mode for offline support
+- `persist-queries` — Configure query persistence for offline support
+
+## How to Use
+
+Each rule file in the `rules/` directory contains:
+
+1. **Explanation** — Why this pattern matters
+2. **Bad Example** — Anti-pattern to avoid
+3. **Good Example** — Recommended implementation
+4. **Context** — When to apply or skip this rule
+
+## Full Reference
+
+See individual rule files in `rules/` directory for detailed guidance and code examples.

package/vendor/skills/skills/tanstack-query-best-practices/rules/cache-gc-time.md

@@ -0,0 +1,93 @@
+# cache-gc-time: Configure gcTime for Inactive Query Retention
+
+## Priority: CRITICAL
+
+## Explanation
+
+`gcTime` (garbage collection time, formerly `cacheTime`) controls how long inactive queries remain in the cache before being garbage collected. Default is 5 minutes. Configure based on your navigation patterns and memory constraints.
+
+## Bad Example
+
+```tsx
+// Not considering gcTime for frequently revisited pages
+const { data } = useQuery({
+  queryKey: ["dashboard-stats"],
+  queryFn: fetchDashboardStats,
+  // Default gcTime of 5 minutes - might be too short for frequently revisited data
+});
+
+// Setting gcTime too high without consideration
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      gcTime: Infinity, // Never garbage collect - potential memory leak
+    },
+  },
+});
+
+// Setting gcTime to 0 - cache is immediately removed
+const { data } = useQuery({
+  queryKey: ["user-data"],
+  queryFn: fetchUserData,
+  gcTime: 0, // Loses cache benefits entirely
+});
+```
+
+## Good Example
+
+```tsx
+// Longer gcTime for frequently revisited data
+const { data } = useQuery({
+  queryKey: ["dashboard-stats"],
+  queryFn: fetchDashboardStats,
+  gcTime: 30 * 60 * 1000, // 30 minutes - user returns to dashboard often
+});
+
+// Shorter gcTime for rarely revisited large data
+const { data: report } = useQuery({
+  queryKey: ["detailed-report", reportId],
+  queryFn: () => fetchReport(reportId),
+  gcTime: 2 * 60 * 1000, // 2 minutes - large payload, viewed once
+});
+
+// Sensible default with query-specific overrides
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      gcTime: 10 * 60 * 1000, // 10 minutes default
+    },
+  },
+});
+```
+
+## Understanding gcTime vs staleTime
+
+```
+Query Mount → Data Fresh (staleTime) → Data Stale → Query Unmount → gcTime countdown → Garbage Collected
+
+Timeline example (staleTime: 1min, gcTime: 5min):
+0:00 - Query mounts, fetches data
+0:00-1:00 - Data is fresh (no background refetch)
+1:00+ - Data is stale (background refetch on new mount)
+5:00 - User navigates away, query unmounts
+5:00-10:00 - Data in cache but inactive (gcTime countdown)
+10:00 - Data garbage collected (next mount = full loading state)
+```
+
+## Recommended gcTime Values
+
+| Scenario                    | gcTime     | Rationale                |
+| --------------------------- | ---------- | ------------------------ |
+| Frequently revisited routes | 15 - 30min | Instant navigation       |
+| Detail pages (viewed once)  | 2 - 5min   | Memory efficient         |
+| Large payloads              | 1 - 2min   | Prevent memory bloat     |
+| Critical user data          | 30min+     | Offline-like experience  |
+| SSR hydration               | >= 2s      | Prevent hydration issues |
+
+## Context
+
+- gcTime countdown starts when ALL query observers unmount
+- Remounting before gcTime expires returns cached data instantly
+- Setting gcTime < staleTime is rarely useful
+- For SSR, avoid gcTime: 0 (use minimum 2000ms to allow hydration)
+- Monitor memory usage in long-running applications

package/vendor/skills/skills/tanstack-query-best-practices/rules/cache-invalidation.md

@@ -0,0 +1,114 @@
+# cache-invalidation: Use Targeted Invalidation Over Broad Patterns
+
+## Priority: CRITICAL
+
+## Explanation
+
+Query invalidation marks cached data as stale, triggering background refetches. Use targeted invalidation to refresh only affected data. Overly broad invalidation causes unnecessary network requests; too narrow invalidation leaves stale data.
+
+## Bad Example
+
+```tsx
+// Invalidating everything after a single todo update
+const mutation = useMutation({
+  mutationFn: updateTodo,
+  onSuccess: () => {
+    queryClient.invalidateQueries(); // Invalidates ENTIRE cache
+  },
+});
+
+// Invalidating too broadly
+const mutation = useMutation({
+  mutationFn: updateTodoStatus,
+  onSuccess: () => {
+    // Invalidates all todos including unrelated lists
+    queryClient.invalidateQueries({ queryKey: ["todos"] });
+  },
+});
+
+// Missing invalidation of related queries
+const mutation = useMutation({
+  mutationFn: addComment,
+  onSuccess: () => {
+    // Only invalidates comment list, misses comment count
+    queryClient.invalidateQueries({ queryKey: ["comments", postId] });
+  },
+});
+```
+
+## Good Example
+
+```tsx
+// Targeted invalidation with exact matching
+const mutation = useMutation({
+  mutationFn: updateTodo,
+  onSuccess: (data, variables) => {
+    // Invalidate specific todo and related queries
+    queryClient.invalidateQueries({ queryKey: ["todos", variables.id] });
+    // Also invalidate lists that might contain this todo
+    queryClient.invalidateQueries({ queryKey: ["todos", "list"] });
+  },
+});
+
+// Use exact: true when you only want one specific query
+const mutation = useMutation({
+  mutationFn: updateUserProfile,
+  onSuccess: () => {
+    queryClient.invalidateQueries({
+      queryKey: ["user", "profile"],
+      exact: true, // Only this exact key, not ['user', 'profile', 'settings']
+    });
+  },
+});
+
+// Invalidate multiple related queries
+const mutation = useMutation({
+  mutationFn: addComment,
+  onSuccess: (data, { postId }) => {
+    // Invalidate all comment-related queries for this post
+    queryClient.invalidateQueries({ queryKey: ["posts", postId, "comments"] });
+    queryClient.invalidateQueries({ queryKey: ["posts", postId, "comment-count"] });
+    // Optionally invalidate the post itself if it shows comment count
+    queryClient.invalidateQueries({ queryKey: ["posts", postId] });
+  },
+});
+
+// Predicate-based invalidation for complex scenarios
+queryClient.invalidateQueries({
+  predicate: query => query.queryKey[0] === "todos" && query.state.data?.userId === currentUserId,
+});
+```
+
+## Invalidation Patterns
+
+```tsx
+// Prefix matching (default) - invalidates all matching prefixes
+queryClient.invalidateQueries({ queryKey: ["todos"] });
+// Matches: ['todos'], ['todos', 1], ['todos', { status: 'done' }]
+
+// Exact matching - only the exact key
+queryClient.invalidateQueries({ queryKey: ["todos"], exact: true });
+// Matches: ['todos'] only
+
+// Predicate matching - custom logic
+queryClient.invalidateQueries({
+  predicate: query => query.queryKey.includes("user-generated"),
+});
+
+// Refetch type control
+queryClient.invalidateQueries({
+  queryKey: ["todos"],
+  refetchType: "active", // Only refetch active queries (default)
+  // refetchType: 'inactive' - Only inactive
+  // refetchType: 'all' - Both
+  // refetchType: 'none' - Mark stale but don't refetch
+});
+```
+
+## Context
+
+- Invalidation only marks queries as stale; refetch happens when query is used
+- `refetchType: 'active'` (default) only refetches queries with active observers
+- Use hierarchical query keys to enable precise invalidation
+- Consider `setQueryData` for optimistic updates instead of invalidation
+- Always test invalidation patterns to ensure all affected queries are refreshed

package/vendor/skills/skills/tanstack-query-best-practices/rules/cache-placeholder-vs-initial.md

@@ -0,0 +1,152 @@
+# cache-placeholder-vs-initial: Understand Placeholder vs Initial Data
+
+## Priority: MEDIUM
+
+## Explanation
+
+`placeholderData` and `initialData` both provide data before the fetch completes, but behave differently. `initialData` is treated as real cached data, while `placeholderData` is temporary and doesn't persist to cache. Choose based on whether your fallback data should be cached.
+
+## Bad Example
+
+```tsx
+// Using initialData when you don't want it cached
+function PostPreview({ postId, previewData }: Props) {
+  const { data } = useQuery({
+    queryKey: ["posts", postId],
+    queryFn: () => fetchPost(postId),
+    initialData: previewData, // Wrong: this becomes cached "truth"
+    // If previewData is incomplete, it pollutes the cache
+    // staleTime applies to this data as if it were fetched
+  });
+}
+
+// Using placeholderData when you want persistence
+function UserProfile({ userId }: Props) {
+  const { data } = useQuery({
+    queryKey: ["users", userId],
+    queryFn: () => fetchUser(userId),
+    placeholderData: cachedUserFromList, // Wrong: won't persist
+    // User navigates away and back - placeholder shown again
+    // No cache entry created until fetch completes
+  });
+}
+```
+
+## Good Example: placeholderData for Temporary Display
+
+```tsx
+// Show list data while fetching detail
+function PostDetail({ postId }: { postId: string }) {
+  const queryClient = useQueryClient();
+
+  const { data, isPlaceholderData } = useQuery({
+    queryKey: ["posts", postId],
+    queryFn: () => fetchPost(postId),
+    placeholderData: () => {
+      // Use partial data from list cache as placeholder
+      const posts = queryClient.getQueryData<Post[]>(["posts"]);
+      return posts?.find(p => p.id === postId);
+    },
+  });
+
+  return (
+    <article className={isPlaceholderData ? "opacity-50" : ""}>
+      <h1>{data?.title}</h1>
+      {isPlaceholderData ? <p>Loading full content...</p> : <div>{data?.content}</div>}
+    </article>
+  );
+}
+```
+
+## Good Example: initialData for Known Good Data
+
+```tsx
+// SSR: Data fetched on server should be initial
+function PostPage({ serverData }: { serverData: Post }) {
+  const { data } = useQuery({
+    queryKey: ["posts", serverData.id],
+    queryFn: () => fetchPost(serverData.id),
+    initialData: serverData,
+    // Specify when this data was fetched for proper stale calculation
+    initialDataUpdatedAt: serverData.fetchedAt,
+  });
+
+  return <PostContent post={data} />;
+}
+
+// Pre-seeding cache with complete data
+function App() {
+  const queryClient = useQueryClient();
+
+  // If you have complete, authoritative data
+  useEffect(() => {
+    queryClient.setQueryData(["config"], completeConfigData);
+  }, []);
+}
+```
+
+## Good Example: keepPreviousData Pattern
+
+```tsx
+// Keep showing old data while fetching new (pagination, filters)
+function ProductList({ page }: { page: number }) {
+  const { data, isPlaceholderData } = useQuery({
+    queryKey: ["products", page],
+    queryFn: () => fetchProducts(page),
+    placeholderData: keepPreviousData, // Built-in helper
+  });
+
+  return (
+    <div className={isPlaceholderData ? "opacity-70" : ""}>
+      {data?.map(product => (
+        <ProductCard key={product.id} product={product} />
+      ))}
+      {isPlaceholderData && <LoadingOverlay />}
+    </div>
+  );
+}
+```
+
+## Comparison Table
+
+| Behavior                  | `initialData`                    | `placeholderData`      |
+| ------------------------- | -------------------------------- | ---------------------- |
+| Persisted to cache        | Yes                              | No                     |
+| `staleTime` applies       | Yes                              | No (always fetches)    |
+| `isPlaceholderData`       | `false`                          | `true`                 |
+| Shown to other components | Yes (cached)                     | No                     |
+| Use case                  | SSR, complete known data         | Preview, previous page |
+| Affects `dataUpdatedAt`   | Yes (use `initialDataUpdatedAt`) | No                     |
+
+## Good Example: Combining Both
+
+```tsx
+function PostDetail({ postId, ssrData }: Props) {
+  const queryClient = useQueryClient();
+
+  const { data } = useQuery({
+    queryKey: ["posts", postId],
+    queryFn: () => fetchPost(postId),
+
+    // If we have SSR data, use as initial (cached)
+    initialData: ssrData,
+    initialDataUpdatedAt: ssrData?.fetchedAt,
+
+    // If no SSR data, try to use list preview as placeholder
+    placeholderData: () => {
+      if (ssrData) return undefined; // Already have initial
+      const posts = queryClient.getQueryData<Post[]>(["posts"]);
+      return posts?.find(p => p.id === postId);
+    },
+  });
+}
+```
+
+## Context
+
+- `placeholderData` can be a value or function (lazy evaluation)
+- `initialData` affects cache immediately on query creation
+- Use `initialDataUpdatedAt` with `initialData` for proper stale calculations
+- `keepPreviousData` is a built-in placeholder strategy
+- Check `isPlaceholderData` to show loading indicators
+- `placeholderData` is ideal for "instant" UI while fetching

package/vendor/skills/skills/tanstack-query-best-practices/rules/cache-stale-time.md

@@ -0,0 +1,80 @@
+# cache-stale-time: Set Appropriate staleTime Based on Data Volatility
+
+## Priority: CRITICAL
+
+## Explanation
+
+`staleTime` determines how long data is considered fresh. The default is 0ms, meaning data is immediately stale and will refetch on every new query mount. Set appropriate staleTime based on how often your data actually changes to reduce unnecessary network requests.
+
+## Bad Example
+
+```tsx
+// Default staleTime of 0 - refetches on every component mount
+const { data } = useQuery({
+  queryKey: ["user-profile", userId],
+  queryFn: () => fetchUserProfile(userId),
+  // No staleTime set - always considered stale
+});
+
+// User profile probably doesn't change every second
+// This causes unnecessary API calls on navigation
+
+// Setting same staleTime everywhere regardless of data type
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60 * 1000, // 1 minute for everything - too simple
+    },
+  },
+});
+```
+
+## Good Example
+
+```tsx
+// Match staleTime to data volatility
+const { data: profile } = useQuery({
+  queryKey: ["user-profile", userId],
+  queryFn: () => fetchUserProfile(userId),
+  staleTime: 5 * 60 * 1000, // 5 minutes - profile rarely changes
+});
+
+const { data: notifications } = useQuery({
+  queryKey: ["notifications"],
+  queryFn: fetchNotifications,
+  staleTime: 30 * 1000, // 30 seconds - changes more frequently
+});
+
+const { data: stockPrice } = useQuery({
+  queryKey: ["stock", symbol],
+  queryFn: () => fetchStockPrice(symbol),
+  staleTime: 0, // Real-time data - always refetch
+});
+
+// Set sensible defaults, override per-query
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60 * 1000, // 1 minute default
+    },
+  },
+});
+```
+
+## Recommended staleTime Values
+
+| Data Type                           | staleTime  | Rationale                      |
+| ----------------------------------- | ---------- | ------------------------------ |
+| Real-time (stocks, live feeds)      | 0          | Must always be current         |
+| Frequently changing (notifications) | 30s - 1min | Balance freshness and requests |
+| User-generated content              | 1 - 5min   | Changes on user action         |
+| Reference data (categories, config) | 10 - 30min | Rarely changes                 |
+| Static content                      | Infinity   | Never changes                  |
+
+## Context
+
+- `staleTime: 0` (default) triggers background refetch on every mount
+- `staleTime: Infinity` never considers data stale (manual invalidation only)
+- Stale data is still returned instantly - refetch happens in background
+- For SSR, set higher staleTime to avoid immediate client refetch
+- Consider using `queryOptions` factory to centralize staleTime per data type

package/vendor/skills/skills/tanstack-query-best-practices/rules/err-error-boundaries.md

@@ -0,0 +1,147 @@
+# err-error-boundaries: Use Error Boundaries with useQueryErrorResetBoundary
+
+## Priority: HIGH
+
+## Explanation
+
+When using Suspense with TanStack Query, errors propagate to error boundaries. Use `useQueryErrorResetBoundary` to reset query errors when users retry, preventing stuck error states.
+
+## Bad Example
+
+```tsx
+// Error boundary without query reset - retry may not work
+function ErrorBoundary({ children }: { children: React.ReactNode }) {
+  return (
+    <ReactErrorBoundary
+      fallbackRender={({ error, resetErrorBoundary }) => (
+        <div>
+          <p>Error: {error.message}</p>
+          <button onClick={resetErrorBoundary}>Try again</button>
+          {/* resetErrorBoundary alone doesn't reset query state */}
+        </div>
+      )}
+    >
+      {children}
+    </ReactErrorBoundary>
+  );
+}
+
+// Query error persists after retry click
+```
+
+## Good Example
+
+```tsx
+import { useQueryErrorResetBoundary } from "@tanstack/react-query";
+import { ErrorBoundary } from "react-error-boundary";
+
+function QueryErrorBoundary({ children }: { children: React.ReactNode }) {
+  const { reset } = useQueryErrorResetBoundary();
+
+  return (
+    <ErrorBoundary
+      onReset={reset}
+      fallbackRender={({ error, resetErrorBoundary }) => (
+        <div className="error-container">
+          <h2>Something went wrong</h2>
+          <pre>{error.message}</pre>
+          <button onClick={resetErrorBoundary}>Try again</button>
+        </div>
+      )}
+    >
+      {children}
+    </ErrorBoundary>
+  );
+}
+
+// Usage with Suspense
+function App() {
+  return (
+    <QueryErrorBoundary>
+      <Suspense fallback={<Loading />}>
+        <Posts />
+      </Suspense>
+    </QueryErrorBoundary>
+  );
+}
+
+function Posts() {
+  // useSuspenseQuery throws on error, caught by boundary
+  const { data } = useSuspenseQuery({
+    queryKey: ["posts"],
+    queryFn: fetchPosts,
+  });
+
+  return <PostList posts={data} />;
+}
+```
+
+## Good Example: With TanStack Router
+
+```tsx
+// Route-level error handling
+import { createFileRoute } from "@tanstack/react-router";
+import { useQueryErrorResetBoundary } from "@tanstack/react-query";
+
+export const Route = createFileRoute("/posts")({
+  loader: ({ context: { queryClient } }) => queryClient.ensureQueryData(postQueries.list()),
+
+  errorComponent: ({ error, reset }) => {
+    const { reset: resetQuery } = useQueryErrorResetBoundary();
+
+    return (
+      <div>
+        <p>Failed to load posts: {error.message}</p>
+        <button
+          onClick={() => {
+            resetQuery();
+            reset();
+          }}
+        >
+          Retry
+        </button>
+      </div>
+    );
+  },
+
+  component: PostsPage,
+});
+```
+
+## Error Boundary Placement Strategy
+
+```tsx
+// Granular error boundaries for isolated failures
+function Dashboard() {
+  return (
+    <div className="dashboard">
+      {/* Each section can fail independently */}
+      <QueryErrorBoundary>
+        <Suspense fallback={<Skeleton />}>
+          <RecentActivity />
+        </Suspense>
+      </QueryErrorBoundary>
+
+      <QueryErrorBoundary>
+        <Suspense fallback={<Skeleton />}>
+          <Statistics />
+        </Suspense>
+      </QueryErrorBoundary>
+
+      <QueryErrorBoundary>
+        <Suspense fallback={<Skeleton />}>
+          <Notifications />
+        </Suspense>
+      </QueryErrorBoundary>
+    </div>
+  );
+}
+```
+
+## Context
+
+- `useQueryErrorResetBoundary` clears error state for all queries in the boundary
+- Always pair Suspense queries with error boundaries
+- Place boundaries based on failure isolation needs
+- Consider inline error handling for non-critical data
+- The reset only affects queries that were in error state