fix: stop Cursor skill pointing at empty Quick Reference (#509)

* fix: stop Cursor skill pointing at empty Quick Reference

Platforms that set quickReference to false omitted the inlined
reference but still told the agent to use "the Quick Reference
sections above." Resolve QR/NOQR variants so Cursor (and other
non-inlined platforms) follow the existing search flow instead.
Claude and Codex keep the inlined reference wording.

Co-authored-by: Neal Meyer <ngmeyer@users.noreply.github.com>

* fix: accept 21 platform configs after ZCode

ZCode landed on main without updating the agent-guide validator
or the platform-count e2e assertion. This branch did not add a
platform; the stale expected count of 20 was failing CI.

Co-authored-by: Neal Meyer <ngmeyer@users.noreply.github.com>

* fix: refresh stale relevance runtime fingerprint

verify:data would fail next on evaluate:relevance because main's
threshold manifest still hashed the pre-#500 runtime. Metrics are
unchanged; only the fingerprint now matches current scripts/data.

Co-authored-by: Neal Meyer <ngmeyer@users.noreply.github.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Neal Meyer <ngmeyer@users.noreply.github.com>
This commit is contained in:
Neal Meyer 2026-10-03 09:05:26 -07:00 committed by GitHub
parent 09170eec67
commit 477bcb28c9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 74 additions and 27 deletions

View File

@ -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.",

View File

@ -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.",

View File

@ -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)

View File

@ -126,6 +126,21 @@ function renderFrontmatter(frontmatter: Record<string, string> | 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<string, string> | null): string {
export async function renderSkillFile(config: PlatformConfig, isGlobal = false): Promise<string> {
// Load base template
let content = await loadTemplate('base/skill-content.md');
content = applyQuickReferenceVariants(content, config.sections.quickReference);
// Load quick reference if needed
let quickReferenceContent = '';

View File

@ -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 "<project-root>"');
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');
}
}
});

View File

@ -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",

View File

@ -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.",

View File

@ -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)