initial commit

.agents/skills/tanstack-query-best-practices/rules/qk-hierarchical-organization.md

@@ -0,0 +1,76 @@
+# qk-hierarchical-organization: Organize Keys Hierarchically
+
+## Priority: CRITICAL
+
+## Explanation
+
+Structure query keys from general to specific: entity type first, then ID, then modifiers/filters. This enables efficient invalidation at any level of specificity and creates predictable cache organization.
+
+## Bad Example
+
+```tsx
+// Flat, inconsistent key structures
+const { data: todos } = useQuery({
+  queryKey: ['all-todos-list'],
+  queryFn: fetchTodos,
+})
+
+const { data: todo } = useQuery({
+  queryKey: ['single-todo-5'],
+  queryFn: () => fetchTodo(5),
+})
+
+const { data: comments } = useQuery({
+  queryKey: ['todo-5-comments'],
+  queryFn: () => fetchTodoComments(5),
+})
+
+// Can't easily invalidate all todo-related queries
+```
+
+## Good Example
+
+```tsx
+// Hierarchical: entity → id → sub-resource → filters
+const { data: todos } = useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+})
+
+const { data: todo } = useQuery({
+  queryKey: ['todos', 5],
+  queryFn: () => fetchTodo(5),
+})
+
+const { data: comments } = useQuery({
+  queryKey: ['todos', 5, 'comments'],
+  queryFn: () => fetchTodoComments(5),
+})
+
+const { data: filteredTodos } = useQuery({
+  queryKey: ['todos', { status: 'done', page: 1 }],
+  queryFn: () => fetchTodos({ status: 'done', page: 1 }),
+})
+
+// Now we can invalidate at any level:
+queryClient.invalidateQueries({ queryKey: ['todos'] })        // All todos
+queryClient.invalidateQueries({ queryKey: ['todos', 5] })     // Todo 5 and its sub-resources
+queryClient.invalidateQueries({ queryKey: ['todos', 5, 'comments'] }) // Just comments
+```
+
+## Recommended Hierarchy Pattern
+
+```
+['entity']                              // List
+['entity', id]                          // Single item
+['entity', id, 'sub-resource']          // Related data
+['entity', { filters }]                 // Filtered list
+['entity', id, 'sub-resource', { filters }] // Filtered sub-resource
+```
+
+## Context
+
+- Essential for applications with related data
+- Enables efficient cache management
+- Works with prefix-based invalidation
+- Consider using query key factories (see `qk-factory-pattern`) for consistency