diff --git a/.claude/skills/ui-ux-pro-max/scripts/tests/fixtures/relevance-thresholds.json b/.claude/skills/ui-ux-pro-max/scripts/tests/fixtures/relevance-thresholds.json index 4734669..1f90e98 100644 --- a/.claude/skills/ui-ux-pro-max/scripts/tests/fixtures/relevance-thresholds.json +++ b/.claude/skills/ui-ux-pro-max/scripts/tests/fixtures/relevance-thresholds.json @@ -2,7 +2,7 @@ "schemaVersion": 1, "status": "provisional-baseline-regression-gate", "baselineRevision": "97eb2a2", - "runtimeFingerprint": "3f902a88e2f9bd5f12965664cd31a60a31117de69f8b19ad1968536ea3c984b7", + "runtimeFingerprint": "48b4cb2aeafb795c76f34bf7faa65e07287811e229b86c152bac3d2cab751385", "oracleFingerprint": "02e7226428c64a995ec24ae104ce4d186f5f91bf0f062556e90ef9b0fcb6d67a", "approvingMaintainer": "repository maintainer approved Phase 1 testing checkpoint; second judgment review remains required before final-target promotion", "units": "All metrics are ratios in [0,1]. Precision treats missing ranks as non-relevant. Negative abstention is measured across the hard-negative by domain/stack cross-product.", diff --git a/cli/assets/scripts/tests/fixtures/relevance-thresholds.json b/cli/assets/scripts/tests/fixtures/relevance-thresholds.json index 4734669..1f90e98 100644 --- a/cli/assets/scripts/tests/fixtures/relevance-thresholds.json +++ b/cli/assets/scripts/tests/fixtures/relevance-thresholds.json @@ -2,7 +2,7 @@ "schemaVersion": 1, "status": "provisional-baseline-regression-gate", "baselineRevision": "97eb2a2", - "runtimeFingerprint": "3f902a88e2f9bd5f12965664cd31a60a31117de69f8b19ad1968536ea3c984b7", + "runtimeFingerprint": "48b4cb2aeafb795c76f34bf7faa65e07287811e229b86c152bac3d2cab751385", "oracleFingerprint": "02e7226428c64a995ec24ae104ce4d186f5f91bf0f062556e90ef9b0fcb6d67a", "approvingMaintainer": "repository maintainer approved Phase 1 testing checkpoint; second judgment review remains required before final-target promotion", "units": "All metrics are ratios in [0,1]. Precision treats missing ranks as non-relevant. Negative abstention is measured across the hard-negative by domain/stack cross-product.", diff --git a/cli/assets/templates/base/skill-content.md b/cli/assets/templates/base/skill-content.md index e0fbcb7..1f4dca9 100644 --- a/cli/assets/templates/base/skill-content.md +++ b/cli/assets/templates/base/skill-content.md @@ -12,7 +12,7 @@ python3 --version || python --version If Python is not installed, **do not install it yourself**. Stop and ask the user to install Python 3 using their preferred method (e.g. from [python.org](https://www.python.org/downloads/) or their OS package manager), then continue once it is available. Never run package-manager or system-modifying commands (`sudo`, `brew`, `apt`, `winget`, etc.) on the user's machine for this skill. -If the user prefers not to install Python, skip the CLI searches and rely on the Quick Reference sections above. +If the user prefers not to install Python, skip the CLI searches and {{#QR}}rely on the Quick Reference sections above{{/QR}}{{#NOQR}}use the Search Reference, Common Rules, and Pre-Delivery Checklist in this skill{{/NOQR}}. > **Note:** On Windows, use `python` instead of `python3` to run scripts (e.g., `python scripts/search.py` instead of `python3 scripts/search.py`). @@ -27,8 +27,8 @@ Use this skill when the user requests any of the following: | **New project / page** | "做一个 landing page"、"Build a dashboard" | Step 1 → Step 2 (design system) | | **New component** | "Create a pricing card"、"Fix modal focus" | Step 3 (one focused domain search) | | **Choose style / color / font** | "What style fits a fintech app?"、"推荐配色" | Step 2 (design system) | -| **Review existing UI** | "Review this page for UX issues"、"检查无障碍" | Quick Reference checklist above | -| **Fix a UI bug** | "Button hover is broken"、"Layout shifts on load" | Quick Reference → relevant section | +| **Review existing UI** | "Review this page for UX issues"、"检查无障碍" | {{#QR}}Quick Reference checklist above{{/QR}}{{#NOQR}}Step 3 (`ux` domain) + Common Rules{{/NOQR}} | +| **Fix a UI bug** | "Button hover is broken"、"Layout shifts on load" | {{#QR}}Quick Reference → relevant section{{/QR}}{{#NOQR}}Step 3 (relevant domain){{/NOQR}} | | **Improve / optimize** | "Reduce React list rerenders"、"Fix mobile touch targets" | Step 3 (explicit `react`, `ux`, or `web` domain) | | **Implement dark mode** | "Add dark mode support" | Step 3 (domain: style "dark mode") | | **Add charts / data viz** | "Add an analytics dashboard chart" | Step 3 (domain: chart) | @@ -285,19 +285,19 @@ python3 {{SCRIPT_PATH}} "fintech crypto" --design-system -f markdown | Problem | What to Do | |---------|------------| | Can't decide on style/color | Verify the category, then retry once with one product and one tone | -| Dark mode contrast issues | Quick Reference §6: `color-dark-mode` + `color-accessible-pairs` | -| Animations feel unnatural | Quick Reference §7: `spring-physics` + `easing` + `exit-faster-than-enter` | -| Form UX is poor | Quick Reference §8: `inline-validation` + `error-clarity` + `focus-management` | -| Navigation feels confusing | Quick Reference §9: `nav-hierarchy` + `bottom-nav-limit` + `back-behavior` | -| Layout breaks on small screens | Quick Reference §5: `mobile-first` + `breakpoint-consistency` | -| Performance / jank | Quick Reference §3: `virtualize-lists` + `main-thread-budget` + `debounce-throttle` | +| Dark mode contrast issues | {{#QR}}Quick Reference §6: `color-dark-mode` + `color-accessible-pairs`{{/QR}}{{#NOQR}}`"color-dark-mode color-accessible-pairs" --domain ux`{{/NOQR}} | +| Animations feel unnatural | {{#QR}}Quick Reference §7: `spring-physics` + `easing` + `exit-faster-than-enter`{{/QR}}{{#NOQR}}`"spring-physics easing" --domain ux`{{/NOQR}} | +| Form UX is poor | {{#QR}}Quick Reference §8: `inline-validation` + `error-clarity` + `focus-management`{{/QR}}{{#NOQR}}`"inline-validation error-clarity" --domain ux`{{/NOQR}} | +| Navigation feels confusing | {{#QR}}Quick Reference §9: `nav-hierarchy` + `bottom-nav-limit` + `back-behavior`{{/QR}}{{#NOQR}}`"nav-hierarchy back-behavior" --domain ux`{{/NOQR}} | +| Layout breaks on small screens | {{#QR}}Quick Reference §5: `mobile-first` + `breakpoint-consistency`{{/QR}}{{#NOQR}}`"mobile-first breakpoint-consistency" --domain ux`{{/NOQR}} | +| Performance / jank | {{#QR}}Quick Reference §3: `virtualize-lists` + `main-thread-budget` + `debounce-throttle`{{/QR}}{{#NOQR}}`"virtualize-lists debounce-throttle" --domain ux`{{/NOQR}} | ### Pre-Delivery Checklist -For web/desktop work, apply the relevant Quick Reference sections and focused searches. The device, Dynamic Type, touch-target, and safe-area checks below apply only to native/mobile app UI. +{{#QR}}For web/desktop work, apply the relevant Quick Reference sections and focused searches.{{/QR}}{{#NOQR}}For web/desktop work, apply focused domain searches and the Common Rules below.{{/NOQR}} The device, Dynamic Type, touch-target, and safe-area checks below apply only to native/mobile app UI. - Run focused searches only for concerns present in the interface, for example `"keyboard focus modal" --domain ux` -- Run through Quick Reference **§1–§3** (CRITICAL + HIGH) as a final review +- {{#QR}}Run through Quick Reference **§1–§3** (CRITICAL + HIGH) as a final review{{/QR}}{{#NOQR}}Review the Common Rules and Pre-Delivery Checklist below (CRITICAL + HIGH first){{/NOQR}} - Test on 375px (small phone) and landscape orientation - Verify behavior with **reduced-motion** enabled and **Dynamic Type** at largest size - Check dark mode contrast independently (don't assume light mode values work) diff --git a/cli/src/utils/template.ts b/cli/src/utils/template.ts index 78efaee..63f6397 100755 --- a/cli/src/utils/template.ts +++ b/cli/src/utils/template.ts @@ -126,6 +126,21 @@ function renderFrontmatter(frontmatter: Record | null): string { return lines.join('\n'); } +/** + * Resolve {{#QR}}...{{/QR}} / {{#NOQR}}...{{/NOQR}} pairs so platforms that + * omit the inlined Quick Reference do not tell the agent to read empty + * "sections above". + */ +function applyQuickReferenceVariants(content: string, includeQuickReference: boolean): string { + const drop = includeQuickReference + ? /\{\{#NOQR\}\}[\s\S]*?\{\{\/NOQR\}\}/g + : /\{\{#QR\}\}[\s\S]*?\{\{\/QR\}\}/g; + const keep = includeQuickReference + ? /\{\{#QR\}\}([\s\S]*?)\{\{\/QR\}\}/g + : /\{\{#NOQR\}\}([\s\S]*?)\{\{\/NOQR\}\}/g; + return content.replace(drop, '').replace(keep, '$1'); +} + /** * Render skill file content from template * When isGlobal=true, rewrites script paths to use ~/{root}/ prefix @@ -133,6 +148,7 @@ function renderFrontmatter(frontmatter: Record | null): string { export async function renderSkillFile(config: PlatformConfig, isGlobal = false): Promise { // Load base template let content = await loadTemplate('base/skill-content.md'); + content = applyQuickReferenceVariants(content, config.sections.quickReference); // Load quick reference if needed let quickReferenceContent = ''; diff --git a/cli/tests/e2e/agent-query-contract.spec.ts b/cli/tests/e2e/agent-query-contract.spec.ts index e4e1fce..e2848be 100644 --- a/cli/tests/e2e/agent-query-contract.spec.ts +++ b/cli/tests/e2e/agent-query-contract.spec.ts @@ -6,7 +6,7 @@ const DESCRIPTION = test('all platform metadata uses one accurate activation description', async () => { const configs = await loadAllPlatformConfigs(); - expect(configs.size).toBe(20); + expect(configs.size).toBe(21); for (const [platform, config] of configs) { expect(config.description, platform).toBe(DESCRIPTION); if (config.frontmatter?.description) { @@ -49,3 +49,34 @@ test('rendered examples encode mode, retry, and persistence boundaries', async ( expect(content).toContain('--output-dir ""'); expect(content).toContain('Read an existing `MASTER.md` before deciding whether `--force` is justified'); }); + +test('quick-reference copy matches whether the section is inlined', async () => { + const configs = await loadAllPlatformConfigs(); + const danglingTag = /\{\{#(NO)?QR\}\}|\{\{\/(NO)?QR\}\}/; + + for (const [platform, config] of configs) { + const content = await renderSkillFile(config); + expect(content, platform).not.toMatch(danglingTag); + + if (config.sections.quickReference) { + expect(content, platform).toContain('## Quick Reference'); + expect(content, platform).toContain('rely on the Quick Reference sections above'); + expect(content, platform).toContain('Quick Reference checklist above'); + expect(content, platform).toContain('Quick Reference → relevant section'); + expect(content, platform).toContain('Quick Reference §6:'); + expect(content, platform).toContain('apply the relevant Quick Reference sections and focused searches'); + expect(content, platform).toContain('Run through Quick Reference **§1–§3**'); + expect(content, platform).not.toContain('use the Search Reference, Common Rules, and Pre-Delivery Checklist in this skill'); + } else { + expect(content, platform).not.toContain('## Quick Reference'); + expect(content, platform).not.toContain('Quick Reference sections above'); + expect(content, platform).not.toContain('Quick Reference checklist above'); + expect(content, platform).not.toContain('Quick Reference →'); + expect(content, platform).not.toContain('Quick Reference §'); + expect(content, platform).toContain('use the Search Reference, Common Rules, and Pre-Delivery Checklist in this skill'); + expect(content, platform).toContain('Step 3 (`ux` domain) + Common Rules'); + expect(content, platform).toContain('`"color-dark-mode color-accessible-pairs" --domain ux`'); + expect(content, platform).toContain('apply focused domain searches and the Common Rules below'); + } + } +}); diff --git a/scripts/validate-agent-guide.py b/scripts/validate-agent-guide.py index 2cd3cb1..60db8e4 100644 --- a/scripts/validate-agent-guide.py +++ b/scripts/validate-agent-guide.py @@ -28,7 +28,7 @@ FLAGS = { "-f", "--persist", "--page", "--output-dir", "-o", "--force", "--variance", "--motion", "--density", } -PLATFORM_COUNT = 20 +PLATFORM_COUNT = 21 GUIDE_REQUIREMENTS = ( "## Query Contract", "one dominant intent", "Retry once", "Do not persist unverified output", "explicit accessibility outcome terms", diff --git a/src/ui-ux-pro-max/scripts/tests/fixtures/relevance-thresholds.json b/src/ui-ux-pro-max/scripts/tests/fixtures/relevance-thresholds.json index 4734669..1f90e98 100644 --- a/src/ui-ux-pro-max/scripts/tests/fixtures/relevance-thresholds.json +++ b/src/ui-ux-pro-max/scripts/tests/fixtures/relevance-thresholds.json @@ -2,7 +2,7 @@ "schemaVersion": 1, "status": "provisional-baseline-regression-gate", "baselineRevision": "97eb2a2", - "runtimeFingerprint": "3f902a88e2f9bd5f12965664cd31a60a31117de69f8b19ad1968536ea3c984b7", + "runtimeFingerprint": "48b4cb2aeafb795c76f34bf7faa65e07287811e229b86c152bac3d2cab751385", "oracleFingerprint": "02e7226428c64a995ec24ae104ce4d186f5f91bf0f062556e90ef9b0fcb6d67a", "approvingMaintainer": "repository maintainer approved Phase 1 testing checkpoint; second judgment review remains required before final-target promotion", "units": "All metrics are ratios in [0,1]. Precision treats missing ranks as non-relevant. Negative abstention is measured across the hard-negative by domain/stack cross-product.", diff --git a/src/ui-ux-pro-max/templates/base/skill-content.md b/src/ui-ux-pro-max/templates/base/skill-content.md index e0fbcb7..1f4dca9 100644 --- a/src/ui-ux-pro-max/templates/base/skill-content.md +++ b/src/ui-ux-pro-max/templates/base/skill-content.md @@ -12,7 +12,7 @@ python3 --version || python --version If Python is not installed, **do not install it yourself**. Stop and ask the user to install Python 3 using their preferred method (e.g. from [python.org](https://www.python.org/downloads/) or their OS package manager), then continue once it is available. Never run package-manager or system-modifying commands (`sudo`, `brew`, `apt`, `winget`, etc.) on the user's machine for this skill. -If the user prefers not to install Python, skip the CLI searches and rely on the Quick Reference sections above. +If the user prefers not to install Python, skip the CLI searches and {{#QR}}rely on the Quick Reference sections above{{/QR}}{{#NOQR}}use the Search Reference, Common Rules, and Pre-Delivery Checklist in this skill{{/NOQR}}. > **Note:** On Windows, use `python` instead of `python3` to run scripts (e.g., `python scripts/search.py` instead of `python3 scripts/search.py`). @@ -27,8 +27,8 @@ Use this skill when the user requests any of the following: | **New project / page** | "做一个 landing page"、"Build a dashboard" | Step 1 → Step 2 (design system) | | **New component** | "Create a pricing card"、"Fix modal focus" | Step 3 (one focused domain search) | | **Choose style / color / font** | "What style fits a fintech app?"、"推荐配色" | Step 2 (design system) | -| **Review existing UI** | "Review this page for UX issues"、"检查无障碍" | Quick Reference checklist above | -| **Fix a UI bug** | "Button hover is broken"、"Layout shifts on load" | Quick Reference → relevant section | +| **Review existing UI** | "Review this page for UX issues"、"检查无障碍" | {{#QR}}Quick Reference checklist above{{/QR}}{{#NOQR}}Step 3 (`ux` domain) + Common Rules{{/NOQR}} | +| **Fix a UI bug** | "Button hover is broken"、"Layout shifts on load" | {{#QR}}Quick Reference → relevant section{{/QR}}{{#NOQR}}Step 3 (relevant domain){{/NOQR}} | | **Improve / optimize** | "Reduce React list rerenders"、"Fix mobile touch targets" | Step 3 (explicit `react`, `ux`, or `web` domain) | | **Implement dark mode** | "Add dark mode support" | Step 3 (domain: style "dark mode") | | **Add charts / data viz** | "Add an analytics dashboard chart" | Step 3 (domain: chart) | @@ -285,19 +285,19 @@ python3 {{SCRIPT_PATH}} "fintech crypto" --design-system -f markdown | Problem | What to Do | |---------|------------| | Can't decide on style/color | Verify the category, then retry once with one product and one tone | -| Dark mode contrast issues | Quick Reference §6: `color-dark-mode` + `color-accessible-pairs` | -| Animations feel unnatural | Quick Reference §7: `spring-physics` + `easing` + `exit-faster-than-enter` | -| Form UX is poor | Quick Reference §8: `inline-validation` + `error-clarity` + `focus-management` | -| Navigation feels confusing | Quick Reference §9: `nav-hierarchy` + `bottom-nav-limit` + `back-behavior` | -| Layout breaks on small screens | Quick Reference §5: `mobile-first` + `breakpoint-consistency` | -| Performance / jank | Quick Reference §3: `virtualize-lists` + `main-thread-budget` + `debounce-throttle` | +| Dark mode contrast issues | {{#QR}}Quick Reference §6: `color-dark-mode` + `color-accessible-pairs`{{/QR}}{{#NOQR}}`"color-dark-mode color-accessible-pairs" --domain ux`{{/NOQR}} | +| Animations feel unnatural | {{#QR}}Quick Reference §7: `spring-physics` + `easing` + `exit-faster-than-enter`{{/QR}}{{#NOQR}}`"spring-physics easing" --domain ux`{{/NOQR}} | +| Form UX is poor | {{#QR}}Quick Reference §8: `inline-validation` + `error-clarity` + `focus-management`{{/QR}}{{#NOQR}}`"inline-validation error-clarity" --domain ux`{{/NOQR}} | +| Navigation feels confusing | {{#QR}}Quick Reference §9: `nav-hierarchy` + `bottom-nav-limit` + `back-behavior`{{/QR}}{{#NOQR}}`"nav-hierarchy back-behavior" --domain ux`{{/NOQR}} | +| Layout breaks on small screens | {{#QR}}Quick Reference §5: `mobile-first` + `breakpoint-consistency`{{/QR}}{{#NOQR}}`"mobile-first breakpoint-consistency" --domain ux`{{/NOQR}} | +| Performance / jank | {{#QR}}Quick Reference §3: `virtualize-lists` + `main-thread-budget` + `debounce-throttle`{{/QR}}{{#NOQR}}`"virtualize-lists debounce-throttle" --domain ux`{{/NOQR}} | ### Pre-Delivery Checklist -For web/desktop work, apply the relevant Quick Reference sections and focused searches. The device, Dynamic Type, touch-target, and safe-area checks below apply only to native/mobile app UI. +{{#QR}}For web/desktop work, apply the relevant Quick Reference sections and focused searches.{{/QR}}{{#NOQR}}For web/desktop work, apply focused domain searches and the Common Rules below.{{/NOQR}} The device, Dynamic Type, touch-target, and safe-area checks below apply only to native/mobile app UI. - Run focused searches only for concerns present in the interface, for example `"keyboard focus modal" --domain ux` -- Run through Quick Reference **§1–§3** (CRITICAL + HIGH) as a final review +- {{#QR}}Run through Quick Reference **§1–§3** (CRITICAL + HIGH) as a final review{{/QR}}{{#NOQR}}Review the Common Rules and Pre-Delivery Checklist below (CRITICAL + HIGH first){{/NOQR}} - Test on 375px (small phone) and landscape orientation - Verify behavior with **reduced-motion** enabled and **Dynamic Type** at largest size - Check dark mode contrast independently (don't assume light mode values work)