@mohammadhprp/system-prompt 0.11.0 → 0.11.2

package/framework/skills/learning-opportunities/examples.md

@@ -0,0 +1,34 @@
+# Learning Opportunities Examples
+
+## Offer an exercise after creating a module
+
+User just created auth middleware: "Done, that's the middleware working."
+
+Good agent behavior:
+
+- Offer one short, optional exercise: "Would you like a quick learning exercise on middleware patterns? About 10-15 minutes."
+- If the user agrees, use a predict-then-observe exercise: ask what happens when a request hits the middleware with an expired token.
+- Stop generating immediately after the question and wait for the user's answer.
+- If the prediction is wrong, be direct about what's incorrect, then explore the gap.
+
+## Teach it back after a refactor
+
+User: "We just replaced the cache layer. I want to make sure I actually understand it."
+
+Good agent behavior:
+
+- Ask the user to explain the caching layer as if to a new developer joining the project.
+- Stop after posing the question and wait for the response.
+- Confirm the specific parts they nailed, then name one concrete gap to refine.
+- Keep the exercise exploratory rather than test-like.
+
+## Decline when the user is in a hurry
+
+User: "Just ship it, this needs to go out now."
+
+Good agent behavior:
+
+- Recognize urgency and skip the exercise offer entirely.
+- Avoid repeating the offer when the user has already declined once this session.
+- Cap the session at two completed exercises and stop offering.
+- Keep any offer to a single sentence without insisting.

package/framework/skills/learning-opportunities/references/PRINCIPLES.md

@@ -0,0 +1,42 @@
+# Learning Principles
+
+Consult this file when adapting techniques or making judgment calls about learning approaches. These principles explain WHY the techniques in the main skill work.
+
+## Generation Effect
+
+Users encode information better when they produce it rather than passively consume it. Active retrieval strengthens memory traces in ways that passive review does not. This is why we ask for predictions and explanations before revealing answers.
+
+## Pre-testing
+
+Attempting to answer before learning new information produces stronger memory — even when the attempt is wrong. A failed attempt makes the correct answer more memorable by contrast. Wrong predictions are valuable data, not failures.
+
+## Spacing Effect
+
+Distributing learning over time beats cramming. This is why we use retrieval check-ins at session starts and limit exercises to 2 per session rather than drilling continuously.
+
+## Desirable Difficulties
+
+Conditions that make learning harder in the short term often produce better long-term retention. Exercises should require effort without being frustrating. Struggle during learning is a sign it's working, not failing.
+
+## Fluency Illusion
+
+When AI-generated code is clean and readable, users overestimate how well they understand it. The fluency of the output masks gaps in mental models. This is the primary risk this skill counteracts.
+
+## Dynamic Testing
+
+Errors during learning, when followed by clear corrective feedback, enhance retention compared to error-free learning. This is why we are direct about wrong answers rather than softening them.
+
+## Transfer and Interleaving
+
+Knowledge transfers better when connected to underlying principles and varied contexts. Asking "where else would this apply?" builds flexible knowledge rather than context-bound recall.
+
+## Sources
+
+- Bjork, R. A., Dunlosky, J., & Kornell, N. (2013). Self-regulated learning: Beliefs, techniques, and illusions.
+- Dunlosky, J., et al. (2013). Improving students' learning with effective learning techniques.
+- Giebl, S., et al. (2021). Answer first or Google first?
+- Hicks, C. M., Lee, C. S., & Foster-Marks, K. (2025). The New Developer: AI Skill Threat, Identity Change & Developer Thriving.
+- Roediger III, H. L., & Karpicke, J. D. (2006). The power of testing memory.
+- Soderstrom, N. C., & Bjork, R. A. (2015). Learning versus performance: An integrative review.
+- Tankelevitch, L., et al. (2024). The metacognitive demands and opportunities of generative AI.
+- Hicks, C. (2025). Cognitive helmets for the AI bicycle. Fight for the Human.

package/framework/skills/perf-web-optimization/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: perf-web-optimization
+description: 'Optimize web performance: bundle size, images, caching, lazy loading, and overall page speed. Use when site is slow, reducing bundle size, fixing layout shifts, improving Time to Interactive, or optimizing for Lighthouse scores. Triggers on: web performance, bundle size, page speed, slow site, lazy loading. Do NOT use for Core Web Vitals-specific fixes (use core-web-vitals), running Lighthouse audits (use perf-lighthouse), or Astro-specific optimization (use perf-astro).'
+---
+
+# Web Performance Optimization
+
+Systematic approach: Measure → Identify → Prioritize → Implement → Verify.
+
+## Target Metrics
+
+| Metric | Good    | Needs Work | Poor    |
+| ------ | ------- | ---------- | ------- |
+| LCP    | < 2.5s  | 2.5-4s     | > 4s    |
+| INP    | < 200ms | 200-500ms  | > 500ms |
+| CLS    | < 0.1   | 0.1-0.25   | > 0.25  |
+| TTFB   | < 800ms | 800ms-1.8s | > 1.8s  |
+
+## Quick Wins
+
+### 1. Images (usually biggest impact on LCP)
+
+```html
+<!-- Hero/LCP image: eager + high priority -->
+<img src="/hero.webp" alt="Hero" width="1200" height="600" loading="eager" fetchpriority="high" decoding="async" />
+
+<!-- Below fold: lazy load -->
+<img src="/product.webp" alt="Product" width="400" height="300" loading="lazy" decoding="async" />
+```
+
+Always set `width` and `height` to prevent CLS.
+
+### 2. Fonts (common LCP/CLS culprit)
+
+```html
+<!-- Preconnect to font origin -->
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+
+<!-- Non-blocking font load -->
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/css2?family=Inter&display=swap"
+  media="print"
+  onload="this.media='all'"
+/>
+```
+
+### 3. Third-party Scripts (common INP killer)
+
+```html
+<!-- Defer to user interaction -->
+<script>
+  function loadThirdParty() {
+    // Load analytics, chat widgets, etc.
+  }
+  ;['scroll', 'click', 'touchstart'].forEach((e) => addEventListener(e, loadThirdParty, { once: true, passive: true }))
+  setTimeout(loadThirdParty, 5000)
+</script>
+```
+
+### 4. Critical CSS
+
+Inline critical CSS in `<head>`, defer the rest:
+
+```html
+<style>
+  /* critical styles */
+</style>
+<link rel="preload" href="/styles.css" as="style" onload="this.rel='stylesheet'" />
+```
+
+## Bundle Analysis
+
+```bash
+# Webpack
+npx webpack-bundle-analyzer dist/stats.json
+
+# Vite
+npx vite-bundle-visualizer
+
+# Check package size before installing
+npx bundlephobia <package-name>
+```
+
+Common heavy packages to replace:
+
+- `moment` (67KB) → `date-fns` (12KB) or `dayjs` (2KB)
+- `lodash` (72KB) → cherry-pick imports or native methods
+
+## Code Splitting Patterns
+
+```javascript
+// React lazy
+const Chart = lazy(() => import('./Chart'))
+
+// Next.js dynamic
+const Admin = dynamic(() => import('./Admin'), { ssr: false })
+
+// Vite/Rollup manual chunks
+build: {
+  rollupOptions: {
+    output: {
+      manualChunks: {
+        vendor: ['react', 'react-dom']
+      }
+    }
+  }
+}
+```
+
+## Caching Headers
+
+```
+# Static assets (immutable hash in filename)
+Cache-Control: public, max-age=31536000, immutable
+
+# HTML (revalidate)
+Cache-Control: no-cache
+
+# API responses
+Cache-Control: private, max-age=0, must-revalidate
+```
+
+## Measurement
+
+For running audits, reading reports, and setting budgets, use the **perf-lighthouse** skill.
+
+## Checklist
+
+### Images
+
+- [ ] Modern formats (WebP/AVIF)
+- [ ] Responsive `srcset`
+- [ ] `width`/`height` attributes
+- [ ] `loading="lazy"` below fold
+- [ ] `fetchpriority="high"` on LCP image
+
+### JavaScript
+
+- [ ] Bundle < 200KB gzipped
+- [ ] Code splitting by route
+- [ ] Third-party scripts deferred
+- [ ] No unused dependencies
+
+### CSS
+
+- [ ] Critical CSS inlined
+- [ ] Non-critical CSS deferred
+- [ ] No unused CSS
+
+### Fonts
+
+- [ ] `font-display: swap`
+- [ ] Preconnect to font origin
+- [ ] Subset if possible
+
+## Detailed Examples
+
+For in-depth optimization patterns, see:
+
+- [references/core-web-vitals.md](references/core-web-vitals.md) - Fixing LCP, CLS, INP issues
+- [references/bundle-optimization.md](references/bundle-optimization.md) - Reducing JS bundle size
+- [references/image-optimization.md](references/image-optimization.md) - Image formats, responsive images, sharp scripts

package/framework/skills/perf-web-optimization/examples.md

@@ -0,0 +1,35 @@
+# Web Performance Optimization Examples
+
+## Slow landing page
+
+User: "Our landing page takes forever to load. Make it faster."
+
+Good agent behavior:
+
+- Follow the measure-identify-prioritize-implement-verify cycle rather than guessing.
+- Start with the highest-impact quick wins: LCP image loading with `fetchpriority="high"`, explicit dimensions, and modern formats.
+- Fix font loading with `font-display: swap` and preconnect to the font origin.
+- Verify against target metrics (LCP < 2.5s, INP < 200ms, CLS < 0.1) before calling it done.
+
+## Reduce JavaScript bundle size
+
+User: "The main bundle is over 1MB. How do we cut it down?"
+
+Good agent behavior:
+
+- Run a bundle analyzer (webpack or Vite) to find the heavy dependencies before proposing swaps.
+- Replace large packages like `moment` with lighter alternatives when the API allows.
+- Add route-level code splitting with lazy imports and vendor chunking.
+- Defer third-party scripts to user interaction rather than loading them eagerly.
+- Confirm the gzipped bundle is under 200KB afterward.
+
+## Fix layout shift on product pages
+
+User: "The images keep jumping around while the page loads."
+
+Good agent behavior:
+
+- Recognize CLS as the metric and add explicit `width`/`height` attributes to all images.
+- Reserve space for below-fold content instead of letting it shift on load.
+- Lazy load below-the-fold images while keeping the LCP image eager and high priority.
+- Verify the CLS score drops below 0.1 after the change.

package/framework/skills/perf-web-optimization/references/bundle-optimization.md

@@ -0,0 +1,180 @@
+# Bundle Size Optimization
+
+## Table of Contents
+- [Analysis Tools](#analysis-tools)
+- [Heavy Dependencies](#heavy-dependencies)
+- [Code Splitting](#code-splitting)
+- [Tree Shaking](#tree-shaking)
+
+---
+
+## Analysis Tools
+
+```bash
+# Webpack - generates interactive treemap
+npx webpack-bundle-analyzer dist/stats.json
+
+# Generate stats file first
+webpack --profile --json > dist/stats.json
+
+# Vite
+npx vite-bundle-visualizer
+
+# Source map explorer
+npx source-map-explorer dist/**/*.js
+
+# Check package size before adding
+npx bundlephobia lodash
+```
+
+---
+
+## Heavy Dependencies
+
+### moment → date-fns/dayjs
+
+```javascript
+// Before: moment (67KB)
+import moment from 'moment';
+moment(date).format('YYYY-MM-DD');
+
+// After: date-fns (tree-shakeable, ~2KB per function)
+import { format } from 'date-fns';
+format(date, 'yyyy-MM-dd');
+
+// After: dayjs (2KB total, moment-compatible API)
+import dayjs from 'dayjs';
+dayjs(date).format('YYYY-MM-DD');
+```
+
+### lodash → cherry-pick or native
+
+```javascript
+// Before: entire lodash (72KB)
+import _ from 'lodash';
+_.uniq(array);
+_.debounce(fn, 300);
+
+// After: cherry-pick (2KB each)
+import uniq from 'lodash/uniq';
+import debounce from 'lodash/debounce';
+
+// After: native alternatives
+[...new Set(array)]; // uniq
+// debounce - use custom or lodash-es/debounce
+```
+
+### Other common swaps
+
+| Heavy | Light Alternative |
+|-------|-------------------|
+| `axios` (13KB) | `fetch` (native) or `ky` (3KB) |
+| `uuid` (4KB) | `crypto.randomUUID()` (native) |
+| `classnames` (1KB) | template literals |
+
+---
+
+## Code Splitting
+
+### React.lazy
+
+```javascript
+import { lazy, Suspense } from 'react';
+
+const Chart = lazy(() => import('./Chart'));
+const AdminPanel = lazy(() => import('./AdminPanel'));
+
+function App() {
+  return (
+    <Suspense fallback={<Loading />}>
+      {showChart && <Chart />}
+      {isAdmin && <AdminPanel />}
+    </Suspense>
+  );
+}
+```
+
+### Next.js dynamic
+
+```javascript
+import dynamic from 'next/dynamic';
+
+// Client-only component
+const Map = dynamic(() => import('./Map'), { ssr: false });
+
+// With loading state
+const Chart = dynamic(() => import('./Chart'), {
+  loading: () => <Skeleton height={300} />
+});
+```
+
+### Route-based splitting (automatic in most frameworks)
+
+```javascript
+// Next.js - each page is a separate chunk
+// pages/dashboard.js → chunks/pages/dashboard.js
+// pages/admin.js → chunks/pages/admin.js
+
+// React Router with lazy
+const Dashboard = lazy(() => import('./pages/Dashboard'));
+const Admin = lazy(() => import('./pages/Admin'));
+```
+
+### Manual chunks (Vite/Rollup)
+
+```javascript
+// vite.config.js
+export default {
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          vendor: ['react', 'react-dom'],
+          charts: ['recharts', 'd3'],
+        }
+      }
+    }
+  }
+};
+```
+
+---
+
+## Tree Shaking
+
+### Enable in webpack
+
+```javascript
+// webpack.config.js
+module.exports = {
+  mode: 'production', // enables tree shaking
+  optimization: {
+    usedExports: true,
+    sideEffects: true,
+  }
+};
+```
+
+### Mark package as side-effect free
+
+```json
+// package.json
+{
+  "sideEffects": false
+}
+
+// Or specify files with side effects
+{
+  "sideEffects": ["*.css", "*.scss"]
+}
+```
+
+### Write tree-shakeable exports
+
+```javascript
+// Bad: default export of object
+export default { foo, bar, baz };
+
+// Good: named exports
+export { foo, bar, baz };
+```

package/framework/skills/perf-web-optimization/references/core-web-vitals.md

@@ -0,0 +1,154 @@
+# Core Web Vitals Optimization
+
+## Table of Contents
+- [LCP (Largest Contentful Paint)](#lcp-largest-contentful-paint)
+- [CLS (Cumulative Layout Shift)](#cls-cumulative-layout-shift)
+- [INP (Interaction to Next Paint)](#inp-interaction-to-next-paint)
+
+---
+
+## LCP (Largest Contentful Paint)
+
+Target: < 2.5s
+
+### Common Causes
+- Large unoptimized images
+- Slow server response (TTFB)
+- Render-blocking resources
+- Client-side rendering delays
+
+### Fix: Optimize LCP Image
+
+```html
+<!-- Preload in <head> -->
+<link rel="preload" as="image" href="/hero.webp" fetchpriority="high">
+
+<!-- Image tag -->
+<picture>
+  <source srcset="/hero.avif" type="image/avif">
+  <source srcset="/hero.webp" type="image/webp">
+  <img src="/hero.jpg" alt="Hero" width="1200" height="600"
+       loading="eager" fetchpriority="high" decoding="async">
+</picture>
+```
+
+### Fix: Reduce TTFB
+
+```javascript
+// Next.js: Use static generation when possible
+export async function getStaticProps() {
+  const data = await fetchData();
+  return { props: { data }, revalidate: 60 };
+}
+
+// Add stale-while-revalidate for dynamic content
+// Cache-Control: public, s-maxage=60, stale-while-revalidate=300
+```
+
+---
+
+## CLS (Cumulative Layout Shift)
+
+Target: < 0.1
+
+### Common Causes
+- Images without dimensions
+- Ads/embeds without reserved space
+- Web fonts causing FOIT/FOUT
+- Dynamic content injection
+
+### Fix: Reserve Space for Images
+
+```html
+<!-- Always specify dimensions -->
+<img src="/photo.jpg" alt="Photo" width="800" height="600">
+
+<!-- Or use aspect-ratio -->
+<img src="/photo.jpg" alt="Photo" style="aspect-ratio: 4/3; width: 100%;">
+```
+
+### Fix: Reserve Space for Dynamic Content
+
+```css
+/* Skeleton loader with fixed height */
+.ad-slot {
+  min-height: 250px;
+  background: #f0f0f0;
+}
+
+/* Aspect ratio container for embeds */
+.video-container {
+  aspect-ratio: 16/9;
+  width: 100%;
+}
+```
+
+### Fix: Prevent Font Flash
+
+```css
+@font-face {
+  font-family: 'CustomFont';
+  src: url('/font.woff2') format('woff2');
+  font-display: swap; /* or optional for less shift */
+}
+```
+
+---
+
+## INP (Interaction to Next Paint)
+
+Target: < 200ms
+
+### Common Causes
+- Long JavaScript tasks (>50ms)
+- Heavy event handlers
+- Layout thrashing
+- Too much main thread work
+
+### Fix: Break Up Long Tasks
+
+```javascript
+// Before: blocks main thread
+items.forEach(item => processItem(item));
+
+// After: yield to main thread
+async function processWithYield(items) {
+  for (const item of items) {
+    processItem(item);
+    // Yield every 5ms
+    if (performance.now() - start > 5) {
+      await new Promise(r => setTimeout(r, 0));
+      start = performance.now();
+    }
+  }
+}
+```
+
+### Fix: Debounce/Throttle Event Handlers
+
+```javascript
+// Debounce search input
+const search = debounce((query) => {
+  fetchResults(query);
+}, 300);
+
+input.addEventListener('input', (e) => search(e.target.value));
+```
+
+### Fix: Use CSS Instead of JS
+
+```css
+/* Prefer CSS for animations */
+.animate {
+  transition: transform 0.3s ease;
+}
+.animate:hover {
+  transform: scale(1.05);
+}
+
+/* Use content-visibility for off-screen content */
+.lazy-section {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 500px;
+}
+```