{"record":{"id":"dc263730bfac19c3","repo":"nextlevelbuilder/ui-ux-pro-max-skill","slug":"agent-guide-validation-failed","errorCode":null,"errorMessage":"Agent guide validation failed:","messagePattern":"Agent guide validation failed:","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"scripts/validate-agent-guide.py","lineNumber":190,"sourceCode":"                errors.append(f\"{label}: missing {phrase!r}\")\n        errors.extend(validate_commands(label, text))\n    design = run_json(\"beauty spa wellness service\", \"--design-system\")\n    if design[\"design_system\"][\"category\"] != \"Beauty/Spa/Wellness Service\":\n        errors.append(\"design-system example resolved wrong product category\")\n    ux = run_json(\"keyboard focus modal\", \"--domain\", \"ux\")\n    if ux.get(\"domain\") != \"ux\" or not ux.get(\"results\"):\n        errors.append(\"focused UX example did not return an explicit UX match\")\n    stack = run_json(\"virtualized list\", \"--stack\", \"react-native\")\n    if stack.get(\"stack\") != \"react-native\" or not stack.get(\"results\"):\n        errors.append(\"React Native stack example did not return a stack match\")\n    return errors\n\n\nif __name__ == \"__main__\":\n    problems = validate()\n    if problems:\n        print(\"Agent guide validation failed:\\n- \" + \"\\n- \".join(problems), file=sys.stderr)\n        raise SystemExit(1)\n    print(\n        f\"Agent guide validation passed: {PLATFORM_COUNT} platforms \"\n        \"and 3 locked examples checked.\"\n    )\n","sourceCodeStart":172,"sourceCodeEnd":195,"githubUrl":"https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/a38d04c3d5c298c851dbe5e6ee1965ee3de42cb5/scripts/validate-agent-guide.py#L172-L195","documentation":"Terminal failure message from validate-agent-guide.py: the validate() function returned a non-empty problems list, so one or more locked examples or platform checks failed. It prints each problem on its own bulleted line to stderr and exits 1. The locked examples shown are a focused UX domain search and a `--stack react-native` search for 'virtualized list' — both must return results with the expected domain/stack field.","triggerScenarios":"Any run of `python3 scripts/validate-agent-guide.py` where: the UX query's top JSON lacks domain=='ux' or empty results (BM25 ranking changed, ux.csv edited); the react-native stack example lacks stack=='react-native' or returns no results (stacks/react-native.csv edited or search.py CLI output schema changed); or platform file checks fail (platform config JSON invalid or PLATFORM_COUNT mismatches).","commonSituations":"After editing search.py's JSON output shape, refactoring core.py's ranking, or pruning rows from ux.csv / stacks/react-native.csv, the documented agent-guide examples stop matching reality and CI validation fails.","solutions":["Read the bulleted lines under the message — they name exactly which example failed; fix that specific data or code path first.","If the UX example fails, run `python3 src/ui-ux-pro-max/scripts/search.py \"<the locked ux query>\" --domain ux` and inspect the JSON: ensure domain and results fields are present and non-empty.","If the stack example fails, run the same with `--stack react-native` for 'virtualized list' and verify stacks/react-native.csv still contains matching rows and the output includes \"stack\": \"react-native\".","If you intentionally changed the locked examples, update validate-agent-guide.py's locked queries and the agent guide doc in the same commit so they stay in sync.","Re-run `npm run sync:assets` in cli/ if you edited src scripts, since the validator may execute mirrored copies."],"exampleFix":"# before: Agent guide validation failed:\n# - focused UX example did not return an explicit UX match\n\n# inspect what the engine now returns\npython3 src/ui-ux-pro-max/scripts/search.py \"accessible forms\" --domain ux\n\n# after: restore/keep the ux.csv rows the locked query relies on\n# (or update the locked query in scripts/validate-agent-guide.py and the guide together)","handlingStrategy":"validation","validationCode":"# Reproduce the locked examples before shipping ranking/data changes:\nimport json, subprocess, sys\ndef run_json(*args):\n    out = subprocess.run([sys.executable, \"src/ui-ux-pro-max/scripts/search.py\", *args],\n                         capture_output=True, text=True, check=True)\n    return json.loads(out.stdout)\nux = run_json(\"<locked ux query>\", \"--domain\", \"ux\")\nassert ux.get(\"domain\") == \"ux\" and ux.get(\"results\"), ux\nstack = run_json(\"virtualized list\", \"--stack\", \"react-native\")\nassert stack.get(\"stack\") == \"react-native\" and stack.get(\"results\"), stack","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run scripts/validate-agent-guide.py in pre-commit or CI whenever search.py, core.py, or data CSVs change.","When changing a locked example query, update validate-agent-guide.py and the agent guide in the same commit.","Keep search.py's JSON output schema stable (domain, stack, results keys) — the validator pins it."],"tags":["ci","validation","search","agent-guide"],"backgroundTag":null,"analyzedSha":"a38d04c3d5c298c851dbe5e6ee1965ee3de42cb5","analyzedAt":"2026-08-14T18:51:02.321Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}