@vpxa/aikit 0.1.308 → 0.1.309

package/scaffold/dist/definitions/skills/frontend-design.mjs

@@ -12,224 +12,135 @@ metadata:
 
 # Frontend Design
 
-> Comprehensive frontend design system — visual design thinking, typography, color, layout, motion, accessibility, performance, and anti-pattern detection. Synthesized from Anthropic's frontend-design skill, Vercel Web Interface Guidelines, and Impeccable design patterns.
+Use for UI, layout, styling, responsive behavior, accessibility, motion, theming, and visual review. Frontend agent loads this for every UI task.
 
-## Quick Reference
+## Design Loop
 
-**Purpose:** Comprehensive design guidance — typography, color, layout, motion, accessibility, performance, anti-pattern detection.
+1. Understand user job, audience, content, and constraints.
+2. Inspect existing design system/tokens/components.
+3. Pick a direction that fits product domain; avoid generic demo styling.
+4. Implement with stable responsive dimensions and accessible interaction states.
+5. Verify desktop/mobile screenshots, keyboard flow, contrast, overflow, loading/error states.
 
-**Mandatory** for the Frontend agent on every task. Also for any UI, styling, responsive, or design work.
+## Context Checklist
 
-**Context checklist** (infer from codebase if not specified):
-Design system? | Brand guidelines? | Accessibility level (AA default)? | Breakpoints? | Motion budget? | Dark mode? | Target platforms?
+Infer from repo when not provided: design system, brand/tokens, breakpoints, dark mode, accessibility target (AA default), motion budget, content model, i18n/RTL, target devices.
 
-**Design cycle:** Understand → Explore → Evaluate → Refine
+## Foundations
 
-**Key principles:**
-- Typography: system font stack, modular scale, max 2 families
-- Color: semantic tokens (\`--color-success\`, not \`--green\`), 4.5:1+ contrast
-- Layout: CSS Grid for 2D, Flexbox for 1D, \`min()\`/\`clamp()\` for fluid sizing
-- Motion: \`prefers-reduced-motion\`, \`will-change\` sparingly, 200-300ms for UI
-- Accessibility: semantic HTML first, ARIA only when needed, focus visible, skip links
+Typography:
+- System or existing font stack; max 2 families.
+- Body >=16px mobile; readable line-height; max text width around 65ch.
+- Use hierarchy through size/weight/spacing; no viewport-width font scaling.
 
-**Anti-patterns to catch:** z-index wars, magic numbers, \`!important\` chains, px-only sizing, color-only status indicators.
+Color:
+- Semantic tokens over raw color names.
+- Text contrast >=4.5:1; non-text >=3:1.
+- Status never color-only; pair icon/text/shape.
+- Dark mode rebalances surfaces, not simple invert.
 
-## When to Use
+Layout:
+- Mobile-first; add breakpoints when layout breaks.
+- Grid for 2D, flex for 1D, container queries when component-owned.
+- Stable dimensions for fixed-format controls/boards/toolbars.
+- Touch targets >=44px when practical.
 
-**MANDATORY** for the Frontend agent on every task. Also use when:
-- Building any UI component, page, or layout
-- Styling, theming, or visual design work
-- Reviewing UI for quality, accessibility, or design consistency
-- User says "make it look good", "design", "UI", "styling", "responsive", "dark mode", "animation"
+Motion:
+- Animate transform/opacity; respect prefers-reduced-motion.
+- UI feedback 100-300ms; avoid long decorative motion.
+- Skeleton/loading states should not cause layout jump.
 
-## Context Gathering Protocol
+## Accessibility
 
-Before any design work, gather answers to these questions (infer from codebase if user doesn't specify):
+- Use semantic HTML before ARIA.
+- Forms need visible labels and inline errors.
+- Icons-only buttons need labels/tooltips.
+- Keyboard: logical tab order, visible focus, Escape closes overlays.
+- Verify at 200% zoom and with reduced motion.
 
-1. **Design System** — Does one exist? Tokens, variables, component library?
-2. **Brand Guidelines** — Colors, fonts, logo usage, tone?
-3. **Accessibility Requirements** — WCAG level (AA default), assistive tech?
-4. **Responsive Breakpoints** — Mobile-first? Specific breakpoints?
-5. **Motion Preferences** — Animation budget, reduced-motion support?
-6. **Content Model** — CMS, static, dynamic, i18n?
-7. **Dark Mode** — Required? System preference detection?
-8. **Target Platforms** — Desktop, mobile web, tablet, native?
+## Product-Fit Rules
 
-## Design Thinking Process
+Operational/SaaS tools: quiet, dense, scannable, predictable. Avoid marketing hero/card sprawl.
 
-Follow this cycle: **Understand → Explore → Evaluate → Refine**
+Games/creative/editorial surfaces: expressive visuals, motion, and custom assets are appropriate when they serve the activity.
 
-1. **Understand** — What is the user trying to accomplish? What are the constraints?
-2. **Explore** — Generate at minimum 2-3 distinct design directions. Name each direction. Describe the aesthetic and rationale.
-3. **Evaluate** — Compare against requirements, accessibility, performance, and the AI Slop Test.
-4. **Refine** — Iterate on the chosen direction. Polish details.
+Landing/brand pages: first viewport must show actual product/place/person/object; hero H1 should be brand/name/offer, not vague value prop.
+
+## Anti-Patterns To Remove
+
+- Generic gradient hero, decorative blobs, one-note purple/blue/slate/beige palettes.
+- Nested cards or full page sections styled as floating cards.
+- SVG pseudo-product art when real/generated bitmap asset is needed.
+- Magic spacing, z-index wars, !important chains.
+- Text overflow, clipped labels, overlapping controls, layout shift on hover/loading.
+- Raw stack traces or technical errors exposed to users.
+
+## Implementation Checks
+
+- Use existing component library and icon set; lucide when available.
+- Use icons for familiar tool actions; text only for clear commands.
+- Provide empty/loading/error/success/disabled/focus states.
+- Preserve URL/deep-link behavior for navigable app state.
+- Optimize images with dimensions, lazy loading, modern formats.
+- Virtualize large lists; split by route; target LCP <2.5s, INP <200ms, CLS <0.1.
+
+## Before Done
+
+Run app checks/tests available in repo. For visual work, inspect with browser screenshots across desktop/mobile and fix overflow/blank/overlap issues before final.
+
+## References
+
+Load on demand:
+- references/design-foundations.md — Detailed typography, color, layout, motion, accessibility, forms, i18n, performance, and SSR guidance.
+- references/ai-slop-test.md — Mandatory AI-generated design tell detection checklist (10 patterns to verify and fix).
+`},{file:`references/design-foundations.md`,content:`# Design Foundations (Detailed)
 
 ## Typography
 
-### Hierarchy
-- Use a **clear scale**: display → h1 → h2 → h3 → body → caption → overline
-- Maximum **3 font sizes** per viewport visible at once
-- Use \`font-weight\` to create hierarchy within same size
-- Line height: 1.5 for body text, 1.2-1.3 for headings
-- **Fluid typography**: use \`clamp()\` for responsive sizing — e.g., \`clamp(1rem, 2.5vw, 1.5rem)\`
-
-### Rules
-- Never use more than 2 typeface families
-- Ensure minimum **16px** body text on mobile
-- Use \`rem\` for font sizes, \`em\` for component-relative spacing
-- Monospace only for code: use a dedicated code font family
-- Set \`max-width: 65ch\` on text blocks for readability
-- Use \`text-wrap: balance\` on headings, \`text-wrap: pretty\` on body
-- Provide room for **text expansion** (50%+) for i18n
-
-## Color
-
-### 60-30-10 Rule
-- **60%** — Background/surface (neutral)
-- **30%** — Secondary/container (brand subtle)
-- **10%** — Accent/CTA (brand strong)
-
-### Systematic Color
-- Define colors as design tokens with semantic names: \`--color-surface\`, \`--color-text-primary\`, \`--color-accent\`
-- Every color needs **4.5:1 contrast ratio** minimum (WCAG AA) for text
-- Non-text elements need **3:1** minimum
-- Never rely on color alone to convey information — pair with icons, text, or patterns
-- Test with color blindness simulators
-
-### Dark Mode
-- Detect system preference with \`prefers-color-scheme\`
-- Don't just invert — re-design surfaces: dark surfaces get lighter elevation, reduce saturation
-- Smooth transition between modes (CSS transitions on \`background-color\`, \`color\`)
-- Diagrams/images: consider \`filter: invert(1)\` or provide alternate assets
-- Store user preference and sync with system default
+Use a clear scale: display -> h1 -> h2 -> h3 -> body -> caption. Maximum 3 font sizes visible at once. Use font-weight to create hierarchy within same size. Line height: 1.5 for body, 1.2-1.3 for headings. Use clamp() for fluid responsive sizing. Use rem for font sizes, em for component-relative spacing. Set max-width: 65ch on text blocks. Use text-wrap: balance on headings, text-wrap: pretty on body. Provide 50%+ room for i18n text expansion.
+
+## Color: 60-30-10 Rule
+
+60% Background/surface (neutral), 30% Secondary/container (brand subtle), 10% Accent/CTA (brand strong). Define colors as semantic design tokens: --color-surface, --color-text-primary, --color-accent. Every color needs 4.5:1 contrast minimum for text (WCAG AA), 3:1 for non-text. Never rely on color alone to convey information. Test with color blindness simulators.
+
+Dark mode: detect with prefers-color-scheme. Rebalance surfaces rather than simple invert. Dark surfaces get lighter elevation. Reduce saturation. Smooth CSS transitions on background-color and color.
 
 ## Layout & Spacing
 
-### Grid System
-- Use an **8px base grid** — all spacing is a multiple of 8 (4px for tight spaces)
-- CSS Grid for 2D layouts, Flexbox for 1D alignment
-- Consistent spacing tokens: \`--space-xs: 4px\`, \`--space-sm: 8px\`, \`--space-md: 16px\`, \`--space-lg: 24px\`, \`--space-xl: 32px\`, \`--space-2xl: 48px\`, \`--space-3xl: 64px\`
-
-### Responsive Design
-- **Mobile-first**: design for 320px, scale up
-- Breakpoints: only add when the layout breaks, not at device widths
-- Use \`container queries\` for component-level responsiveness
-- Fluid layouts with \`minmax()\`, \`auto-fill\`, \`auto-fit\`
-- Every interactive target: minimum **44×44px** touch area (WCAG 2.5.5)
-
-### Rules
-- Use consistent gutters — don't mix random padding values
-- Stacking: define a z-index scale (e.g., base: 0, dropdown: 100, modal: 200, toast: 300)
-- Avoid magic numbers — extract to named tokens
-
-## Motion & Animation
-
-### Principles
-- **Purpose before polish** — every animation must serve a purpose: orientation, feedback, continuity, or delight
-- **Spring physics** over linear easing — use \`cubic-bezier(0.175, 0.885, 0.32, 1.275)\` or spring-based libraries
-- Duration budget: micro-interactions **100-200ms**, transitions **200-400ms**, page transitions **300-500ms**
-- Never exceed **500ms** unless it's a storytelling/onboarding animation
-
-### Performance
-- Animate only \`transform\` and \`opacity\` — these run on the compositor thread
-- Never animate \`width\`, \`height\`, \`top\`, \`left\`, \`margin\`, \`padding\` (trigger layout)
-- Use \`will-change\` sparingly and only before the animation starts
-- \`requestAnimationFrame\` for JS animations
-
-### Accessibility
-- **Always respect \`prefers-reduced-motion\`**: reduce or remove animations when set
-- Layout animations: use \`layout\` prop (Framer Motion) or FLIP technique
-- Skeleton screens during loading — never an empty blank page
-- Skeleton loading → content: smooth fade transition, not a hard swap
-
-### Patterns
-- Enter/exit transitions with stagger for lists
-- Shared element transitions between route changes
-- Micro-interactions on hover/focus: subtle scale, bg-color shift, shadow change
-- Pull-to-refresh, swipe gestures (mobile) with physics-based feel
+Use an 8px base grid. CSS Grid for 2D, Flexbox for 1D. Define spacing tokens: --space-xs: 4px, --space-sm: 8px, --space-md: 16px, --space-lg: 24px, --space-xl: 32px.
 
-## Accessibility (WCAG AA Mandatory)
+Responsive: mobile-first from 320px. Add breakpoints only when layout breaks, not at device widths. Use container queries for component-level responsiveness. Fluid layouts with minmax(), auto-fill, auto-fit. Minimum 44x44px touch targets (WCAG 2.5.5). Define z-index scale (base: 0, dropdown: 100, modal: 200, toast: 300).
 
-### Structure
-- Use **semantic HTML**: \`header\`, \`nav\`, \`main\`, \`section\`, \`article\`, \`aside\`, \`footer\`
-- Every \`<img>\` has a meaningful \`alt\` (or \`alt=""\` for decorative)
-- Every form field has a visible \`<label>\` (not just placeholder)
-- Headings form a logical hierarchy (\`h1\` → \`h2\` → \`h3\`, no skipping)
-
-### Keyboard Navigation
-- All interactive elements reachable via **Tab** key
-- Logical tab order (follows visual reading order)
-- Focus indicators: visible, high-contrast, never \`outline: none\` without replacement
-- Escape to close modals/dropdowns, Enter/Space to activate
-- Skip-to-content link for screen readers
-
-### Screen Readers
-- ARIA labels on icons-only buttons: \`aria-label="Close"\`
-- Live regions for dynamic content: \`aria-live="polite"\` for updates, \`"assertive"\` for errors
-- Landmark roles if semantic HTML is insufficient
-- Don't use ARIA when a native HTML element works (\`<button>\` not \`<div role="button">\`)
-
-### Testing
-- Tab through entire flow without mouse
-- Test with screen reader (NVDA, VoiceOver)
-- Run Lighthouse accessibility audit
-- Test at 200% zoom — nothing should break or overflow
+## Motion
 
-## Forms
+Every animation must serve a purpose: orientation, feedback, continuity, delight. Spring physics over linear easing. Micro-interactions 100-200ms, transitions 200-400ms, never exceed 500ms except storytelling/onboarding. Animate only transform and opacity (compositor thread). Never animate width, height, top, left, margin, padding. Use will-change sparingly. Always respect prefers-reduced-motion. Skeleton screens during loading, never blank pages.
 
-- **Instant inline validation** — validate on blur, not on every keystroke
-- Show error messages below the field, not in an alert
-- Preserve user input on error — never clear a form on submit failure
-- **Auto-save** drafts for long forms (debounced)
-- Use \`inputmode\` for mobile: \`numeric\`, \`email\`, \`tel\`, \`url\`
-- Multi-step forms: show progress indicator and allow back-navigation
-- File uploads: drag-and-drop zone, progress indicator, file type restrictions, preview
-- **Optimistic UI**: show success immediately, revert on error
+## Accessibility (WCAG AA Mandatory)
 
-## Navigation & State
+Use semantic HTML: header, nav, main, section, article, aside, footer. Every img has meaningful alt. Every form field has visible label. Headings form logical hierarchy (no skipping).
 
-- URL should always reflect application state (\`/settings/profile\` not \`/settings#profile\`)
-- Support deep linking — any URL should be shareable and land on the right view
-- Breadcrumbs for hierarchical navigation (3+ levels deep)
-- Keyboard shortcuts for power users (document them)
-- Browser back/forward must work correctly — don't break history
+Keyboard: all interactive elements reachable via Tab. Logical tab order. Visible focus indicators, never outline: none without replacement. Escape closes modals/dropdowns. Skip-to-content link.
 
-## Performance
+Screen readers: ARIA labels on icon-only buttons, live regions for dynamic content (aria-live="polite" for updates, "assertive" for errors), landmark roles if semantic HTML insufficient. Do not use ARIA when native HTML element works.
 
-- **Virtual scroll** for lists > 100 items — don't render 10,000 DOM nodes
-- **Lazy load** images: use \`loading="lazy"\`, provide dimensions to prevent layout shift
-- **Prefetch** next-likely routes on hover/viewport intersection
-- **Code split** by route — each page only loads its own JavaScript
-- **Edge rendering** — render at the CDN edge when possible (SSR, RSC)
-- Optimize images: use \`<picture>\` with WebP/AVIF + fallback
-- Font loading: \`font-display: swap\`, preload critical fonts
-- Target LCP < 2.5s, INP < 200ms, CLS < 0.1
+Test: tab through entire flow without mouse. Test with NVDA/VoiceOver. Run Lighthouse audit. Test at 200% zoom.
 
-## Error Handling
+## Forms
 
-- **Graceful degradation** — partial failures shouldn't crash the entire page
-- Show retry buttons on transient errors
-- Offline indicator when network is lost
-- Clear error messages: what happened, what the user can do about it
-- Error boundaries in React: catch rendering errors, show fallback UI
-- Never show raw error messages, stack traces, or error codes to users
+Instant inline validation on blur, not every keystroke. Show error messages below the field. Preserve user input on error. Auto-save drafts for long forms (debounced). Use inputmode for mobile: numeric, email, tel, url. Multi-step forms: show progress and allow back-navigation. File uploads: drag-and-drop zone, progress, preview.
 
-## SSR & Hydration
+## Internationalization
 
-- Prevent hydration mismatches: no \`Date.now()\`, \`Math.random()\`, \`window\` in server render
-- Use streaming SSR for faster TTFB
-- Optimistic mutations: update UI before server confirms
-- Handle loading states with Suspense boundaries
+Use logical properties (margin-inline-start not margin-left). Format dates/numbers/currencies locale-aware. Plan for 50% text expansion for German/French. Test with CJK, Arabic, emoji. Externalize all user-visible strings.
 
-## Internationalization (i18n)
+## Performance
+
+Virtual scroll for lists >100 items. Lazy load images with loading="lazy", provide dimensions. Prefetch next-likely routes on hover/viewport intersection. Code split by route. Optimize images with picture element and WebP/AVIF. Use font-display: swap, preload critical fonts. Target LCP <2.5s, INP <200ms, CLS <0.1.
 
-- **RTL support**: use logical properties (\`margin-inline-start\` not \`margin-left\`)
-- Format dates/numbers/currencies locale-aware — never hardcode formats
-- Text expansion room: German/French can be 50%+ longer than English
-- Unicode support: test with CJK, Arabic, emoji
-- Externalize all user-visible strings
+## Error Handling
 
-## AI Slop Test — MANDATORY CHECK
+Graceful degradation — partial failures should not crash the entire page. Show retry buttons on transient errors. Offline indicator when network is lost. Clear error messages: what happened and what the user can do. React Error Boundaries. Never show raw stack traces or error codes to users.
+`},{file:`references/ai-slop-test.md`,content:`# AI Slop Test — Mandatory Check
 
 Before shipping ANY design, verify it does NOT have these AI-generated tells:
 
@@ -237,22 +148,14 @@ Before shipping ANY design, verify it does NOT have these AI-generated tells:
 |-----------------|---------------|
 | Centered hero + gradient blob | Does it look like every AI demo landing page? ADD ASYMMETRY |
 | Lowercase geometric sans headings | Add personality: case choices, weight variation, size contrast |
-| Purple-to-blue gradient | If using gradients, use brand-specific or creative color stops |
+| Purple-to-blue gradient | Use brand-specific or creative color stops |
 | Uniform card grid with icon + heading + text | Vary card sizes, add imagery, break the grid |
 | Stock illustration style | Use real photos, custom illustrations, or no imagery |
 | "Modern SaaS template" look | Add something unexpected: editorial layout, bold typography, color blocking |
-| Generic placeholder copy | Real content or clearly marked FPO (For Placement Only) |
+| Generic placeholder copy | Real content or clearly marked FPO |
 | Identical padding everywhere | Vary rhythm — tight grouping inside sections, generous between |
 | No texture or depth | Add subtle noise, shadows, borders, layering |
 | Perfectly symmetrical everything | Break symmetry deliberately — offset grids, varied alignments |
 
-If 3+ items match → **STOP and redesign**. The goal is distinctive, not generic.
-
-## Implementation Principles
-
-1. **Design tokens before code** — define variables/tokens first, then use them everywhere
-2. **Component boundaries** — each component owns its internal layout, parent owns its placement
-3. **Progressive enhancement** — works without JS, enhanced with JS
-4. **Content-first** — design with real content, not lorem ipsum
-5. **Test in context** — view components inside the actual page, not just in isolation
+If 3+ items match -> STOP and redesign. The goal is distinctive, not generic.
 `}];export{e as default};

package/scaffold/dist/definitions/skills/lesson-learned.mjs

@@ -136,7 +136,7 @@ Use this as a lookup table. When you spot a pattern in a diff, find the matching
 **Signals:** Multiple related parameters grouped into a single options/config object. Function signatures simplified.
 `},{file:`SKILL.md`,content:`---
 name: lesson-learned
-description: "Extract and persist engineering lessons from code changes into AI Kit memory. MUST use after completing ANY implementation, refactoring, debugging, or code review task — do NOT wait for user to ask. Also triggers on explicit requests: 'lesson', 'takeaway', 'what did I learn', 'reflect', 'principles'. Every completed task produces reusable lessons; skipping this loses institutional knowledge that prevents future rework."
+description: "Extract and persist engineering lessons from code changes into AI Kit memory. Use after implementation, refactoring, debugging, or code review tasks; also when user asks for lesson, takeaway, reflection, or principles. Produces reusable, evidence-grounded lessons without bloating memory."
 metadata:
   category: cross-cutting
   domain: general
@@ -149,214 +149,87 @@ metadata:
 
 # Lesson Learned
 
-Extract specific, grounded software engineering lessons from actual code changes. Not a lecture -- a mirror. Show the user what their code already demonstrates, and only elevate lessons that are earned by the diff.
+Extract durable engineering lessons from actual work. Lessons are not summaries; they are reusable principles proven by diff, test, or review evidence.
 
-## Auto-Trigger Protocol
+## When
 
-This skill MUST activate after any task that modifies code. The agent does NOT need user permission.
+Run after implementation, refactor, debugging, or review. Skip pure formatting/config churn unless it revealed a reusable process lesson.
 
-**Activation flow:**
-1. Task complete (implementation/refactor/debug/review done)
-2. Load this skill
-3. Run Phase 1-5 (takes ~30 seconds of analysis)
-4. Present lesson to user and persist to AI Kit memory
+## Flow
 
-**Skip conditions (ONLY skip if ALL are true):**
-- Changes are pure config/formatting (no logic changed)
-- Less than 5 lines of substantive code modified
-- Change is a trivial typo or import reorder
+1. Inspect diff and verification results.
+2. Identify 1-2 non-obvious principles future agents can reuse.
+3. Ground each lesson in file/line, commit, test, or tool receipt.
+4. Check existing lessons to avoid duplicates.
+5. Store with knowledge lesson create or remember, confidence 60-70 for single observation, 80+ for repeated pattern.
 
-## Phase 1: Determine Scope
-
-Ask the user or infer from context what to analyze.
-
-| Scope | Git Commands | When to Use |
-|-------|-------------|-------------|
-| Feature branch | \`git log main..HEAD --oneline\` + \`git diff main...HEAD\` | User is on a non-main branch (default) |
-| Last N commits | \`git log --oneline -N\` + \`git diff HEAD~N..HEAD\` | User specifies a range, or on main (default N=5) |
-| Specific commit | \`git show <sha>\` | User references a specific commit |
-| Working changes | \`git diff\` + \`git diff --cached\` | User says "what about these changes?" before committing |
-
-**Default behavior:**
-- If on a feature branch: analyze branch commits vs main
-- If on main: analyze the last 5 commits
-- If the user provides a different scope, use that
-
-## Phase 2: Gather Changes
-
-Use git log/diff to collect the changeset. Expert constraints:
-- **500-line threshold:** If diff > 500 lines, focus on the 3-5 most-changed files only
-- **Only read changed files** -- never speculatively read unchanged code for "context"
-- **Commit messages are clues** -- scan first, read code second
-
-## Phase 3: Analyze
+## Good Lesson Shape
 
-Apply this decision tree to find the dominant lesson:
+- Situation: when this applies.
+- Insight: principle or pattern.
+- Evidence: exact file/test/tool receipt.
+- Boundary: when not to apply it.
 
-1. **Is there a structural change?** (files split/merged, new module boundary, layer introduced)
-  -> Lesson is about architecture principles (SRP, Separation of Concerns, Cohesion)
+Bad: vague praise, task summary, restating code, or broad universal claims from one tiny change.
 
-2. **Is there a removed or simplified path?** (deleted code, simplified conditionals, fewer dependencies)
-  -> Lesson is about simplicity principles (YAGNI, KISS, Premature Abstraction avoidance)
+## Memory Hygiene
 
-3. **Is there error handling or edge case work?** (try/catch added, validation, fallbacks)
-  -> Lesson is about robustness principles (Fail Fast, Defensive Programming)
+Search before storing. Confirm/contradict existing lessons when new evidence supports or invalidates them. Prune/group/promote only during maintenance or when asked.
 
-4. **Is there duplication resolved?** (extracted shared logic, parameterized, DRY applied)
-  -> Lesson is about DRY and Rule of Three
+## References
 
-5. **Is there a naming or API change?** (renames, interface changes, contract adjustments)
-  -> Lesson is about Principle of Least Surprise and Encapsulation
+Load anti-patterns.md for low-quality lesson smells. Load se-principles.md for naming/generalization help. Load references/extraction-workflow.md for the detailed 5-phase extraction workflow with git commands and categorization rubric.
 
-6. **None of the above clearly dominate?**
-  -> The changes may be routine. Check commit messages for unstated intent. If still nothing emerges, be honest that no deep lesson exists.
+## Output
 
-For the dominant pattern, map to the specific principle from \`references/se-principles.md\` when needed and cite the concrete code change that demonstrates it.
+Report created/updated/skipped lessons, confidence, evidence, and reason if skipped.
+`},{file:`references/extraction-workflow.md`,content:`# Lesson Extraction Workflow
 
-## Quality Gate
-
-A lesson is only worth presenting if ALL of these are true:
-- **Non-obvious** -- someone reading the diff would not immediately see it without prompting
-- **Actionable** -- it changes future behavior, not just "interesting observation"
-- **Specific** -- cites actual file:line, not generic advice
-- **Earned** -- emerges naturally from the code, not force-fit to a principle
-
-If no lesson meets all four criteria, say so honestly: "These changes are solid execution -- no deep lesson here beyond good engineering practice."
-
-## Phase 4: Present the Lesson
-
-Use this template:
+## Phase 1: Determine Scope
 
-\`\`\`markdown
-## Lesson: [Principle Name]
+| Scope | Git Commands | When to Use |
+|-------|-------------|-------------|
+| Feature branch | \`git log main..HEAD --oneline\` + \`git diff main...HEAD\` | User is on a non-main branch (default) |
+| Last N commits | \`git log --oneline -N\` + \`git diff HEAD~N..HEAD\` | User specifies a range, or on main (default N=5) |
+| Single commit | \`git show --stat <sha>\` | User specifies a specific commit |
+| Working tree only | \`git diff --stat\` | Pre-commit review, no commits yet |
 
-**What happened in the code:**
-[2-3 sentences describing the specific change, referencing files and commits]
+Ask the user or infer from context what to analyze.
 
-**The principle at work:**
-[1-2 sentences explaining the SE principle]
+## Phase 2: Extract Patterns
 
-**Why it matters:**
-[1-2 sentences on the practical consequence -- what would go wrong without this, or what goes right because of it]
+Read the diff output and identify recurring patterns. Look for:
+- Repeated structural changes (extract method, add interface, remove duplication)
+- Error handling or validation additions
+- Naming or API improvements
+- Performance or correctness fixes
 
-**Takeaway for next time:**
-[One concrete, actionable sentence the user can apply to future work]
-\`\`\`
+Filter out: pure formatting, whitespace changes, import reordering, mechanical renames.
 
-If there is a second lesson worth noting, include at most one more:
+## Phase 3: Validate
 
-\`\`\`markdown
----
+For each candidate lesson:
+- Is it evidenced by the diff? (file/line reference required)
+- Is it non-obvious? (not "use const instead of let")
+- Is it reusable? (would another agent benefit from knowing this?)
+- Is it specific? (not "write better code")
 
-### Also worth noting: [Principle Name]
+Discard candidates that fail two or more checks.
 
-**In the code:** [1 sentence]
-**The principle:** [1 sentence]
-**Takeaway:** [1 sentence]
-\`\`\`
+## Phase 4: Categorize
 
-Do not present more than 2 lessons total. If the diff is mostly clean execution with no deeper pattern, say that directly.
+| Category | Store as | Confidence | Example |
+|----------|----------|------------|---------|
+| Reusable principle | lesson create | 70-90 | "Extract IO from business logic for testability" |
+| One-time observation | remember | 50-60 | "This project uses Biome over ESLint" |
+| Not useful | Skip | 0 | "Changed variable name" |
 
 ## Phase 5: Persist
 
-After presenting, store the lesson for cross-session recall using the confidence-tracked lesson system:
-
-~~~
-knowledge({ action: "lesson", subAction: "create", title: "<short principle name>", context: "<what happened — the code situation>", insight: "<what was learned — the principle applied>", evidence: "<proof — commit SHA, file:line, test result>", confidence: 70 })
-~~~
-
-**Confidence scale:**
-- 50-60: Single observation, no corroboration yet
-- 60-70: Clear pattern from one changeset (default starting point)
-- 70-80: Same pattern observed in 2+ independent changes
-- 80-90: Pattern confirmed across multiple PRs/sessions
-- 90+: Fundamental principle validated repeatedly -- treat as convention
-
-Confidence decays over time based on access recency (Ebbinghaus curve). Accessing a lesson via \`withdraw\` or \`list-lessons\` implicitly reinforces it.
-
-If you encounter a lesson that CONFIRMS a previously stored one:
-~~~
-knowledge({ action: "lesson", subAction: "confirm", id: "<lesson-path>" })
-~~~
-
-If a lesson CONTRADICTS a previously stored one:
-~~~
-knowledge({ action: "lesson", subAction: "contradict", id: "<lesson-path>", reason: "<why the old lesson no longer holds>" })
-~~~
-
-Before creating a new lesson, check existing ones: \`knowledge({ action: "lesson", subAction: "list-lessons" })\`
-Only create if no existing lesson already covers this insight.
-
-### Passive Learning (auto-observe)
-The server automatically observes tool output patterns and can detect:
-- Repeated error -> fix cycles (suggests lessons about common pitfalls)
-- Consistent code patterns across files (suggests convention lessons)
-- Recurring search queries (suggests documentation gaps)
-
-Trigger manually: \`knowledge({ action: "lesson", subAction: "auto-observe", buffer: "<tool output>" })\`
-Usually runs automatically via exec-hooks -- agents don't need to call this directly.
-
-## Phase 6: Lifecycle Maintenance (Periodic)
-
-Run these periodically (every few sessions) to maintain knowledge quality:
-
-### Prune Stale Lessons
-\`\`\`
-knowledge({ action: "lesson", subAction: "prune" })                // dry-run: shows candidates
-knowledge({ action: "lesson", subAction: "prune", dryRun: false }) // execute: archives stale lessons
-\`\`\`
-Archives lessons where: decayed confidence < 15 AND last accessed > 30 days ago.
-Safety: minimum 3 lessons always retained, dry-run by default.
-
-### Group Similar Lessons
-\`\`\`
-knowledge({ action: "lesson", subAction: "group" })                // dry-run: shows proposed groups
-knowledge({ action: "lesson", subAction: "group", dryRun: false }) // execute: adds group tags
-\`\`\`
-Clusters lessons with similar titles (Jaccard > 0.7), adds \`group:<label>\` tags.
-Non-destructive -- only adds tags, never modifies content.
-
-### Cross-Project Promotion
-\`\`\`
-knowledge({ action: "lesson", subAction: "promote" })                  // dry-run: shows candidates
-knowledge({ action: "lesson", subAction: "promote", dryRun: false })   // execute: copies to global
-knowledge({ action: "lesson", subAction: "demote", path: "<path>" }) // remove from global
-\`\`\`
-Requires user-level install. Scans all workspaces for similar lessons (Jaccard > 0.7 on insight text).
-Promotes when: found in 2+ workspaces AND average confidence >= 80.
-Global lessons available to ALL workspaces via \`workspaces: ["*"]\`.
-
-### Recommended Maintenance Cadence
-- **Every 5 sessions**: \`prune\` (dry-run review)
-- **Every 10 sessions**: \`group\` to organize
-- **Monthly**: \`promote\` to share universal lessons across projects
-
-## What NOT to Do
-
-| Avoid | Why | Instead |
-|-------|-----|---------|
-| Listing every principle that vaguely applies | Overwhelming and generic | Pick the 1-2 most relevant |
-| Analyzing files that were not changed | Scope creep | Stick to the diff |
-| Ignoring commit messages | They contain intent that diffs miss | Read them as primary context |
-| Abstract advice disconnected from the code | Not actionable | Always reference specific files/lines |
-| Negative-only feedback | Demoralizing | Lead with what works, then suggest improvements |
-| More than 2 lessons | Dilutes the insight | One well-grounded lesson beats seven vague ones |
-
-## NEVER
-
-- **NEVER present obvious refactoring as a lesson** ("the code got cleaner") -- this is table stakes, not insight
-- **NEVER force-fit a principle** that does not naturally emerge from the diff -- if you have to stretch to connect code to principle, the connection is not there
-- **NEVER produce more than 2 lessons** per analysis -- one well-grounded insight beats seven vague observations
-- **NEVER use "best practice" without citing WHICH practice and WHY it is best HERE** -- "best practice" is the refuge of those who cannot explain the reasoning
-- **NEVER analyze files that were not changed** -- scope creep dilutes focus
-- **NEVER start with criticism** -- lead with what the code demonstrates well, then optionally note opportunities
-- **NEVER produce a lesson without a concrete code reference** -- if you cannot point to a specific line or commit, the lesson is too abstract
-
-## Conversation Style
-
-- **Reflective, not prescriptive.** Use the user's own code as primary evidence.
-- **Never say "you should have..."** -- instead use "the approach here shows..." or "next time you face this, consider..."
-- **If the code is good, say so.** Not every lesson is about what went wrong. Recognizing good patterns reinforces them.
-- **If the changes are trivial** (a single config tweak, a typo fix), say so honestly rather than forcing a lesson. "These changes are straightforward -- no deep lesson here, just good housekeeping."
-- **Be specific.** Generic advice is worthless. Every claim must point to a concrete code change.
+- Use \`knowledge({ action: "lesson", subAction: "create" })\` for new lessons
+- Use \`knowledge({ action: "lesson", subAction: "confirm" })\` when new evidence supports an existing lesson
+- Use \`knowledge({ action: "lesson", subAction: "contradict" })\` when new evidence invalidates an existing lesson
+- Set confidence 60-70 for single observation, 80+ when multiple diffs confirm the same pattern
+
+After persisting, report: created/updated/skipped lessons, confidence, evidence citation, and reason if skipped.
 `}];export{e as default};