@gong-ym/ai-spec-auto 0.2.13 → 0.2.15

package/.agents/skills/profiles/vue/vue-best-practices/references/state-management.md

@@ -1,135 +1,135 @@
----
-title: State Management Strategy
-impact: HIGH
-impactDescription: Choosing the wrong store pattern can cause SSR request leaks, brittle mutation flows, and poor scaling
-type: best-practice
-tags: [vue3, state-management, pinia, composables, ssr, vueuse]
----
-
-# State Management Strategy
-
-**Impact: HIGH** - Use the lightest state solution that fits your app architecture. SPA-only apps can use lightweight global composables, while SSR/Nuxt apps should default to Pinia for request-safe isolation and predictable tooling.
-
-## Task List
-
-- Keep state local first, then promote to shared/global only when needed
-- Use singleton composables only in non-SSR applications
-- Expose global state as readonly and mutate through explicit actions
-- Prefer Pinia for SSR/Nuxt, large apps, and advanced debugging/plugin needs
-- Avoid exporting mutable module-level reactive state directly
-
-## Choose the Lightest Store Approach
-
-- **Feature composable:** Default for reusable logic with local/feature-level state.
-- **Singleton composable or VueUse `createGlobalState`:** Small non-SSR apps needing shared app state.
-- **Pinia:** SSR/Nuxt apps, medium-to-large apps, and cases requiring DevTools, plugins, or action tracing.
-
-## Avoid Exporting Mutable Module State
-
-**BAD:**
-```ts
-// store/cart.ts
-import { reactive } from 'vue'
-
-export const cart = reactive({
-  items: [] as Array<{ id: string; qty: number }>
-})
-```
-
-**GOOD:**
-```ts
-// composables/useCartStore.ts
-import { reactive, readonly } from 'vue'
-
-let _store: ReturnType<typeof createCartStore> | null = null
-
-function createCartStore() {
-  const state = reactive({
-    items: [] as Array<{ id: string; qty: number }>
-  })
-
-  function addItem(id: string, qty = 1) {
-    const existing = state.items.find((item) => item.id === id)
-    if (existing) {
-      existing.qty += qty
-      return
-    }
-    state.items.push({ id, qty })
-  }
-
-  return {
-    state: readonly(state),
-    addItem
-  }
-}
-
-export function useCartStore() {
-  if (!_store) _store = createCartStore()
-  return _store
-}
-```
-
-## Do Not Use Runtime Singletons in SSR
-
-Module singletons live for the runtime lifetime. In SSR this can leak state between requests.
-
-**BAD:**
-```ts
-// shared singleton reused across requests
-const cartStore = useCartStore()
-
-export function useServerCart() {
-  return cartStore
-}
-```
-
-**GOOD:**
-
-> `pinia` dependency required.
-
-```ts
-// stores/cart.ts
-import { defineStore } from 'pinia'
-
-export const useCartStore = defineStore('cart', {
-  state: () => ({
-    items: [] as Array<{ id: string; qty: number }>
-  }),
-  actions: {
-    addItem(id: string, qty = 1) {
-      const existing = this.items.find((item) => item.id === id)
-      if (existing) {
-        existing.qty += qty
-        return
-      }
-      this.items.push({ id, qty })
-    }
-  }
-})
-```
-
-## Use `createGlobalState` for Small SPA Global State
-
-> `@vueuse/core` dependency required.
-
-If the app is non-SSR and already uses VueUse, `createGlobalState` removes singleton boilerplate.
-
-```ts
-import { createGlobalState } from '@vueuse/core'
-import { computed, ref } from 'vue'
-
-export const useAuthState = createGlobalState(() => {
-  const token = ref<string | null>(null)
-  const isAuthenticated = computed(() => token.value !== null)
-
-  function setToken(next: string | null) {
-    token.value = next
-  }
-
-  return {
-    token,
-    isAuthenticated,
-    setToken
-  }
-})
-```
+---
+title: State Management Strategy
+impact: HIGH
+impactDescription: Choosing the wrong store pattern can cause SSR request leaks, brittle mutation flows, and poor scaling
+type: best-practice
+tags: [vue3, state-management, pinia, composables, ssr, vueuse]
+---
+
+# State Management Strategy
+
+**Impact: HIGH** - Use the lightest state solution that fits your app architecture. SPA-only apps can use lightweight global composables, while SSR/Nuxt apps should default to Pinia for request-safe isolation and predictable tooling.
+
+## Task List
+
+- Keep state local first, then promote to shared/global only when needed
+- Use singleton composables only in non-SSR applications
+- Expose global state as readonly and mutate through explicit actions
+- Prefer Pinia for SSR/Nuxt, large apps, and advanced debugging/plugin needs
+- Avoid exporting mutable module-level reactive state directly
+
+## Choose the Lightest Store Approach
+
+- **Feature composable:** Default for reusable logic with local/feature-level state.
+- **Singleton composable or VueUse `createGlobalState`:** Small non-SSR apps needing shared app state.
+- **Pinia:** SSR/Nuxt apps, medium-to-large apps, and cases requiring DevTools, plugins, or action tracing.
+
+## Avoid Exporting Mutable Module State
+
+**BAD:**
+```ts
+// store/cart.ts
+import { reactive } from 'vue'
+
+export const cart = reactive({
+  items: [] as Array<{ id: string; qty: number }>
+})
+```
+
+**GOOD:**
+```ts
+// composables/useCartStore.ts
+import { reactive, readonly } from 'vue'
+
+let _store: ReturnType<typeof createCartStore> | null = null
+
+function createCartStore() {
+  const state = reactive({
+    items: [] as Array<{ id: string; qty: number }>
+  })
+
+  function addItem(id: string, qty = 1) {
+    const existing = state.items.find((item) => item.id === id)
+    if (existing) {
+      existing.qty += qty
+      return
+    }
+    state.items.push({ id, qty })
+  }
+
+  return {
+    state: readonly(state),
+    addItem
+  }
+}
+
+export function useCartStore() {
+  if (!_store) _store = createCartStore()
+  return _store
+}
+```
+
+## Do Not Use Runtime Singletons in SSR
+
+Module singletons live for the runtime lifetime. In SSR this can leak state between requests.
+
+**BAD:**
+```ts
+// shared singleton reused across requests
+const cartStore = useCartStore()
+
+export function useServerCart() {
+  return cartStore
+}
+```
+
+**GOOD:**
+
+> `pinia` dependency required.
+
+```ts
+// stores/cart.ts
+import { defineStore } from 'pinia'
+
+export const useCartStore = defineStore('cart', {
+  state: () => ({
+    items: [] as Array<{ id: string; qty: number }>
+  }),
+  actions: {
+    addItem(id: string, qty = 1) {
+      const existing = this.items.find((item) => item.id === id)
+      if (existing) {
+        existing.qty += qty
+        return
+      }
+      this.items.push({ id, qty })
+    }
+  }
+})
+```
+
+## Use `createGlobalState` for Small SPA Global State
+
+> `@vueuse/core` dependency required.
+
+If the app is non-SSR and already uses VueUse, `createGlobalState` removes singleton boilerplate.
+
+```ts
+import { createGlobalState } from '@vueuse/core'
+import { computed, ref } from 'vue'
+
+export const useAuthState = createGlobalState(() => {
+  const token = ref<string | null>(null)
+  const isAuthenticated = computed(() => token.value !== null)
+
+  function setToken(next: string | null) {
+    token.value = next
+  }
+
+  return {
+    token,
+    isAuthenticated,
+    setToken
+  }
+})
+```

package/.agents/skills/profiles/vue/vue-best-practices/references/updated-hook-performance.md

@@ -1,187 +1,187 @@
----
-title: Avoid Expensive Operations in Updated Hook
-impact: MEDIUM
-impactDescription: Heavy computations in updated hook cause performance bottlenecks and potential infinite loops
-type: capability
-tags: [vue3, vue2, lifecycle, updated, performance, optimization, reactivity]
----
-
-# Avoid Expensive Operations in Updated Hook
-
-**Impact: MEDIUM** - The `updated` hook runs after every reactive state change that causes a re-render. Placing expensive operations, API calls, or state mutations here can cause severe performance degradation, infinite loops, and dropped frames below the optimal 60fps threshold.
-
-Use `updated`/`onUpdated` sparingly for post-DOM-update operations that cannot be handled by watchers or computed properties. For most reactive data handling, prefer watchers (`watch`/`watchEffect`) which provide more control over what triggers the callback.
-
-## Task List
-
-- Never perform API calls in updated hook
-- Never mutate reactive state inside updated (causes infinite loops)
-- Use conditional checks to verify updates are relevant before acting
-- Prefer `watch` or `watchEffect` for reacting to specific data changes
-- Use throttling/debouncing if updated operations are expensive
-- Reserve updated for low-level DOM synchronization tasks
-
-**BAD:**
-```javascript
-// BAD: API call in updated - fires on every re-render
-export default {
-  data() {
-    return { items: [], lastUpdate: null }
-  },
-  updated() {
-    // This runs after every single state change!
-    fetch('/api/sync', {
-      method: 'POST',
-      body: JSON.stringify(this.items)
-    })
-  }
-}
-```
-
-```javascript
-// BAD: State mutation in updated - infinite loop
-export default {
-  data() {
-    return { renderCount: 0 }
-  },
-  updated() {
-    // This causes another update, which triggers updated again!
-    this.renderCount++ // Infinite loop
-  }
-}
-```
-
-```javascript
-// BAD: Heavy computation on every update
-export default {
-  updated() {
-    // Expensive operation runs on every keystroke, every state change
-    this.processedData = this.heavyComputation(this.rawData)
-    this.analytics = this.calculateMetrics(this.allData)
-  }
-}
-```
-
-**GOOD:**
-```javascript
-import debounce from 'lodash-es/debounce'
-
-// GOOD: Use watcher for specific data changes
-export default {
-  data() {
-    return { items: [] }
-  },
-  watch: {
-    // Only fires when items actually changes
-    items: {
-      handler(newItems) {
-        this.syncToServer(newItems)
-      },
-      deep: true
-    }
-  },
-  methods: {
-    syncToServer: debounce(function(items) {
-      fetch('/api/sync', {
-        method: 'POST',
-        body: JSON.stringify(items)
-      })
-    }, 500)
-  }
-}
-```
-
-```vue
-<!-- GOOD: Composition API with targeted watchers -->
-<script setup>
-import { ref, watch, onUpdated } from 'vue'
-import { useDebounceFn } from '@vueuse/core'
-
-const items = ref([])
-const scrollContainer = ref(null)
-
-// Watch specific data - not all updates
-watch(items, (newItems) => {
-  syncToServer(newItems)
-}, { deep: true })
-
-const syncToServer = useDebounceFn((items) => {
-  fetch('/api/sync', { method: 'POST', body: JSON.stringify(items) })
-}, 500)
-
-// Only use onUpdated for DOM synchronization
-onUpdated(() => {
-  // Scroll to bottom only if content changed height
-  if (scrollContainer.value) {
-    scrollContainer.value.scrollTop = scrollContainer.value.scrollHeight
-  }
-})
-</script>
-```
-
-```javascript
-// GOOD: Conditional check in updated hook
-export default {
-  data() {
-    return {
-      content: '',
-      lastSyncedContent: ''
-    }
-  },
-  updated() {
-    // Only act if specific condition is met
-    if (this.content !== this.lastSyncedContent) {
-      this.syncContent()
-      this.lastSyncedContent = this.content
-    }
-  },
-  methods: {
-    syncContent: debounce(function() {
-      // Sync logic
-    }, 300)
-  }
-}
-```
-
-## Valid Use Cases for Updated Hook
-
-```javascript
-// GOOD: Low-level DOM synchronization
-export default {
-  updated() {
-    // Sync third-party library with Vue's DOM
-    this.thirdPartyWidget.refresh()
-
-    // Update scroll position after content change
-    this.$nextTick(() => {
-      this.maintainScrollPosition()
-    })
-  }
-}
-```
-
-## Prefer Computed Properties for Derived Data
-
-```javascript
-// BAD: Calculating derived data in updated
-export default {
-  data() {
-    return { numbers: [1, 2, 3, 4, 5] }
-  },
-  updated() {
-    this.sum = this.numbers.reduce((a, b) => a + b, 0) // Causes another update!
-  }
-}
-
-// GOOD: Use computed property instead
-export default {
-  data() {
-    return { numbers: [1, 2, 3, 4, 5] }
-  },
-  computed: {
-    sum() {
-      return this.numbers.reduce((a, b) => a + b, 0)
-    }
-  }
-}
-```
+---
+title: Avoid Expensive Operations in Updated Hook
+impact: MEDIUM
+impactDescription: Heavy computations in updated hook cause performance bottlenecks and potential infinite loops
+type: capability
+tags: [vue3, vue2, lifecycle, updated, performance, optimization, reactivity]
+---
+
+# Avoid Expensive Operations in Updated Hook
+
+**Impact: MEDIUM** - The `updated` hook runs after every reactive state change that causes a re-render. Placing expensive operations, API calls, or state mutations here can cause severe performance degradation, infinite loops, and dropped frames below the optimal 60fps threshold.
+
+Use `updated`/`onUpdated` sparingly for post-DOM-update operations that cannot be handled by watchers or computed properties. For most reactive data handling, prefer watchers (`watch`/`watchEffect`) which provide more control over what triggers the callback.
+
+## Task List
+
+- Never perform API calls in updated hook
+- Never mutate reactive state inside updated (causes infinite loops)
+- Use conditional checks to verify updates are relevant before acting
+- Prefer `watch` or `watchEffect` for reacting to specific data changes
+- Use throttling/debouncing if updated operations are expensive
+- Reserve updated for low-level DOM synchronization tasks
+
+**BAD:**
+```javascript
+// BAD: API call in updated - fires on every re-render
+export default {
+  data() {
+    return { items: [], lastUpdate: null }
+  },
+  updated() {
+    // This runs after every single state change!
+    fetch('/api/sync', {
+      method: 'POST',
+      body: JSON.stringify(this.items)
+    })
+  }
+}
+```
+
+```javascript
+// BAD: State mutation in updated - infinite loop
+export default {
+  data() {
+    return { renderCount: 0 }
+  },
+  updated() {
+    // This causes another update, which triggers updated again!
+    this.renderCount++ // Infinite loop
+  }
+}
+```
+
+```javascript
+// BAD: Heavy computation on every update
+export default {
+  updated() {
+    // Expensive operation runs on every keystroke, every state change
+    this.processedData = this.heavyComputation(this.rawData)
+    this.analytics = this.calculateMetrics(this.allData)
+  }
+}
+```
+
+**GOOD:**
+```javascript
+import debounce from 'lodash-es/debounce'
+
+// GOOD: Use watcher for specific data changes
+export default {
+  data() {
+    return { items: [] }
+  },
+  watch: {
+    // Only fires when items actually changes
+    items: {
+      handler(newItems) {
+        this.syncToServer(newItems)
+      },
+      deep: true
+    }
+  },
+  methods: {
+    syncToServer: debounce(function(items) {
+      fetch('/api/sync', {
+        method: 'POST',
+        body: JSON.stringify(items)
+      })
+    }, 500)
+  }
+}
+```
+
+```vue
+<!-- GOOD: Composition API with targeted watchers -->
+<script setup>
+import { ref, watch, onUpdated } from 'vue'
+import { useDebounceFn } from '@vueuse/core'
+
+const items = ref([])
+const scrollContainer = ref(null)
+
+// Watch specific data - not all updates
+watch(items, (newItems) => {
+  syncToServer(newItems)
+}, { deep: true })
+
+const syncToServer = useDebounceFn((items) => {
+  fetch('/api/sync', { method: 'POST', body: JSON.stringify(items) })
+}, 500)
+
+// Only use onUpdated for DOM synchronization
+onUpdated(() => {
+  // Scroll to bottom only if content changed height
+  if (scrollContainer.value) {
+    scrollContainer.value.scrollTop = scrollContainer.value.scrollHeight
+  }
+})
+</script>
+```
+
+```javascript
+// GOOD: Conditional check in updated hook
+export default {
+  data() {
+    return {
+      content: '',
+      lastSyncedContent: ''
+    }
+  },
+  updated() {
+    // Only act if specific condition is met
+    if (this.content !== this.lastSyncedContent) {
+      this.syncContent()
+      this.lastSyncedContent = this.content
+    }
+  },
+  methods: {
+    syncContent: debounce(function() {
+      // Sync logic
+    }, 300)
+  }
+}
+```
+
+## Valid Use Cases for Updated Hook
+
+```javascript
+// GOOD: Low-level DOM synchronization
+export default {
+  updated() {
+    // Sync third-party library with Vue's DOM
+    this.thirdPartyWidget.refresh()
+
+    // Update scroll position after content change
+    this.$nextTick(() => {
+      this.maintainScrollPosition()
+    })
+  }
+}
+```
+
+## Prefer Computed Properties for Derived Data
+
+```javascript
+// BAD: Calculating derived data in updated
+export default {
+  data() {
+    return { numbers: [1, 2, 3, 4, 5] }
+  },
+  updated() {
+    this.sum = this.numbers.reduce((a, b) => a + b, 0) // Causes another update!
+  }
+}
+
+// GOOD: Use computed property instead
+export default {
+  data() {
+    return { numbers: [1, 2, 3, 4, 5] }
+  },
+  computed: {
+    sum() {
+      return this.numbers.reduce((a, b) => a + b, 0)
+    }
+  }
+}
+```